Skip to main content
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.