> ## 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.

# Recipients and destinations introduction

> Why a transfer needs a destination rather than an account number, and when to save a recipient.

The obvious API design would let a transfer take an account number. Sakawave does not, and the reason shapes everything in this service.

## Why a destination exists

An account number is a claim. A destination is a *checked* claim, with a timestamp on it.

Creating a destination is where the work happens:

1. The destination currency is checked against the capability for this kind of transfer.
2. The route is confirmed to serve the country.
3. The route's required fields are confirmed present.
4. Where the rail supports it, the account is looked up with the provider and the real account name comes back.
5. The counterparty profile the payout rail needs is confirmed complete.

By the time you hold a `destinationId`, five things that could have failed have not. The transfer itself is then a small, fast operation — which matters when it is moving money.

The 24-hour expiry follows from the same logic. A verification is only as good as the moment it was made; an account closed yesterday should not be payable today on the strength of last week's lookup.

## Inline or saved

Both paths end at the same object. Choose on whether you will pay this person again.

| | Inline | Saved recipient |
| - | - | - |
| Calls to first payout | 1 | 3 |
| Calls to the next payout | 1 | 1 |
| Routing fields re-sent each time | Yes | No |
| You hold the account number | Yes, to re-send | No |
| Good for | One-off payouts, checkout flows | Payroll, suppliers, anyone recurring |

The second-to-last row is the one that decides it for most integrations. With saved recipients, the routing values live encrypted at Sakawave and you never handle them again. Inline, you must keep them somewhere to send them next time — and that somewhere is now in scope for your own compliance.

## When a recipient is not the answer

* **Paying your own account.** Use an `own_account` destination.
* **Paying another Sakawave account.** Use a `sakawave_tag` destination — including your own customers' wallets, which own-account destinations exclude.
* **A one-off you will never repeat.** Inline is fewer calls and leaves nothing behind.

## Recipients are not customers

Both hold names and addresses; they are opposite ends of the money.

| | Customer | Recipient |
| - | - | - |
| Relationship | Holds a balance with you | Receives money from you |
| Has accounts | Yes | No |
| Identity numbers | BVN, NIN, passport | None |
| Deduplicated by | `externalReference`, identity numbers | Nothing |

Nothing stops the same human being both. They are separate records with separate lifecycles, and Sakawave will not link them for you.

## The shape of the API

Eleven operations, all rate-limited together at 120 per minute.

| Operation | Notes |
| - | - |
| [`POST /v1/transfer-destinations`](/api-reference/transfer-destinations/create-a-transfer-destination) | Inline. Three shapes selected by `type`. |
| [`POST /v1/transfer-destinations/recipients/{recipientId}`](/api-reference/transfer-destinations/create-a-destination-from-a-recipient) | From a saved recipient. |
| [`POST /v1/transfer-recipients`](/api-reference/transfer-destinations/create-a-transfer-recipient) | Create a recipient. |
| [`GET /v1/transfer-recipients`](/api-reference/transfer-destinations/list-transfer-recipients) | All of them. Not paginated. |
| [`GET /v1/transfer-recipients/{recipientId}`](/api-reference/transfer-destinations/get-a-transfer-recipient) | One, with details inlined. |
| [`DELETE /v1/transfer-recipients/{recipientId}`](/api-reference/transfer-destinations/delete-a-transfer-recipient) | Deactivates it. |
| [`POST …/payment-details`](/api-reference/transfer-destinations/add-recipient-payment-detail) | Add routing. |
| [`GET …/payment-details`](/api-reference/transfer-destinations/list-recipient-payment-details) | List routing, masked. |
| [`GET …/payment-details/{paymentDetailId}`](/api-reference/transfer-destinations/get-recipient-payment-detail) | One detail. |
| [`PATCH …/payment-details/{paymentDetailId}`](/api-reference/transfer-destinations/set-default-payment-detail) | Promote to default. |
| [`DELETE …/payment-details/{paymentDetailId}`](/api-reference/transfer-destinations/delete-recipient-payment-detail) | Deactivate one. |

There is no endpoint to update a recipient or a payment detail. Both are create-and-delete: to correct an account number, add a new detail and delete the old one.


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