> ## Documentation Index
> Fetch the complete documentation index at: https://docs.sakawave.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Transfer corridors and recipients

> Discover payout fields, save reusable recipient resources, and create provider-neutral transfer destinations.

Sakawave route IDs, recipient IDs, and payment-detail IDs are stable client resources. The payout provider is selected internally when a short-lived destination is created, so provider changes do not alter your integration.

## Discover a corridor

Call `GET /v1/transfer-corridors` and optionally filter by `currency`, `country`, or `paymentMethod`. Each active route includes settlement timing, limits, institution-directory availability, and ordered `fields`.

When `institutionDirectoryEnabled` is `true`, load the route's institution directory and submit its institution code in the corresponding routing field. Do not send `institutionName`; Sakawave resolves and stores the canonical name. Routes without a directory expose `institutionName` as a normal required field.

Render the returned field descriptors instead of hard-coding routing forms. Submit values under the descriptor's stable `key`. Amount limits are integers in the destination currency's minor unit.

Contract-pending routes are not returned. Never infer support from a currency alone.

## Reuse recipients and payment details

A recipient stores identity and contact information. A payment detail stores one bank account or mobile-money destination. One recipient can own several payment details, and exactly one active detail can be the default.

1. Create the identity with `POST /v1/transfer-recipients`.
2. Add routing data with `POST /v1/transfer-recipients/{recipientId}/payment-details`.
3. Create a short-lived destination with `POST /v1/transfer-destinations/recipients/{recipientId}`. Omit `paymentDetailId` to use the default.
4. Reuse the same Sakawave IDs for later transfers.

Payment responses contain only masked routing information. Provider names, provider IDs, encrypted values, and raw provider errors are never exposed.

## Inline compatibility

`POST /v1/transfer-destinations` still accepts inline external routing fields. `saveRecipient` remains `false` by default for API clients. Set it to `true` to retain the recipient and payment detail.

## Deletion

Deleting a payment detail or recipient immediately removes it from reads and invalidates unused destinations. Provider cleanup is asynchronous and retries safely. Existing and in-flight transfers retain immutable masked snapshots and remain pinned to their original provider.

## Validation errors

Corridor-field and amount-limit failures return HTTP `422` with a stable top-level `code` and an `errors` array. Each error contains `field`, `path`, `code`, and `message`, so a client can attach feedback to the matching form control.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.