> ## Documentation Index
> Fetch the complete documentation index at: https://developers.yara.cash/llms.txt
> Use this file to discover all available pages before exploring further.
# Make a transfer
> Quote a payout, choose how to fund it, and initiate a transfer to a whitelisted destination.
A transfer has two steps. First, create a quote that fixes the payout and funding amounts. Then,
create the transfer from that quote. Your merchant is always the transfer principal.
## Before you start
* Add the payout destination in the [dashboard](https://dashboard.yara.cash) and copy its
`recipient_id`.
* Complete Tier 2 business verification and receive approval for USD banking before quoting a USD
bank payout.
* Choose one funding method: your Yara balance, an NGN bank transfer, or a supported stablecoin and
network.
* Keep a unique `X-Idempotency-Key` for each request. Reuse the same key when retrying that request.
## Step 1 — Quote the transfer
The destination amount and funding source are separate. This example pays 100 USD and collects the
funds by NGN bank transfer.
```bash theme={null}
curl https://api.yara.cash/v1/transfers/quotes \
--request POST \
--header "x-yara-api-key: $YARA_API_KEY" \
--header "X-Idempotency-Key: $(uuidgen)" \
--header "Content-Type: application/json" \
--data '{
"recipient_id": "3bf24579-a35a-4ba9-a936-5df9c1d809f9",
"amount": {
"value": "100.00",
"currency": "USD"
},
"funding_source": {
"method": "BANK_TRANSFER",
"currency": "NGN"
}
}'
```
Use one of these funding sources:
```json theme={null}
{ "method": "BALANCE" }
```
```json theme={null}
{ "method": "BANK_TRANSFER", "currency": "NGN" }
```
```json theme={null}
{ "method": "CRYPTO_DEPOSIT", "asset": "USDC", "network": "BASE" }
```
Bank funding supports NGN. Crypto funding supports USDC or USDT on an enabled network. Use the
exact asset and network returned by the API.
USD bank payouts support US bank accounts over ACH or wire and international bank accounts over
SWIFT. The recipient determines the payout rail. Your transfer request does not include a customer
or an on-behalf-of identity.
### Quote response
```json theme={null}
{
"data": {
"id": "0e0f7b9c-f47b-4f42-b56e-991b8f7a1cb3",
"destination_amount": { "value": "100", "currency": "USD" },
"transfer_fee": { "value": "0.4", "currency": "USD" },
"total_debit": { "value": "100.4", "currency": "USD" },
"destination_rail": "US_BANK_ACCOUNT",
"funding": {
"method": "BANK_TRANSFER",
"required_amount": { "value": "160640", "currency": "NGN" },
"fee": { "value": "0", "currency": "NGN" },
"rate": {
"base_currency": "USD",
"quote_currency": "NGN",
"value": "1600"
},
"expires_at": "2026-06-16T03:05:00Z"
},
"status": "ACTIVE",
"expires_at": "2026-06-16T03:05:00Z"
}
}
```
The quote fixes one funding method, the required source amount, the rate, fees, and expiry. You
cannot change the funding method when creating the transfer.
## Step 2 — Create the transfer
```bash theme={null}
curl https://api.yara.cash/v1/transfers \
--request POST \
--header "x-yara-api-key: $YARA_API_KEY" \
--header "X-Idempotency-Key: $(uuidgen)" \
--header "Content-Type: application/json" \
--data '{
"quote_id": "0e0f7b9c-f47b-4f42-b56e-991b8f7a1cb3",
"reference": "merchant-transfer-001"
}'
```
Balance-funded transfers reserve immediately and return `RESERVED`. Bank- and crypto-funded
transfers return `AWAITING_MERCHANT_FUNDING` with transfer-specific instructions.
### Bank funding instructions
```json theme={null}
{
"data": {
"id": "76179a66-8695-47fd-bca4-310eaa816077",
"quote_id": "0e0f7b9c-f47b-4f42-b56e-991b8f7a1cb3",
"reference": "merchant-transfer-001",
"status": "AWAITING_MERCHANT_FUNDING",
"funding_method": "BANK_TRANSFER",
"funding": {
"id": "0f92c60a-6870-48ba-b589-a5f9c91ac5ec",
"method": "BANK_TRANSFER",
"status": "PENDING",
"required_amount": { "value": "160640", "currency": "NGN" },
"expires_at": "2026-06-16T03:05:00Z",
"bank_transfer": {
"account_number": "1234567890",
"bank_code": "035",
"bank_name": "Wema Bank",
"account_name": "Yara",
"reference": "funding-0f92c60a687048bab589a5f9c91ac5ec"
}
},
"created_at": "2026-06-16T03:00:00Z"
}
}
```
If `funding` has no bank account or crypto address yet, Yara is retrying instruction provisioning.
Poll the funding endpoint:
```bash theme={null}
curl https://api.yara.cash/v1/transfers/76179a66-8695-47fd-bca4-310eaa816077/funding \
--header "x-yara-api-key: $YARA_API_KEY"
```
Yara selects the configured banking partner. You do not select the provider. Always use the exact
bank details returned for that transfer.
## Fund safely
* Use only the account, address, reference, asset, and network returned for this transfer.
* Never reuse instructions from another transfer.
* Send funds before `expires_at`.
* Do not infer a match from the amount and payment time. Yara uses the unique bank order or crypto
address to map the receipt to one transfer.
Bank and crypto funding must both match `required_amount` exactly. Any underpayment or overpayment
is recorded as `REQUIRES_REVIEW`; Yara sends `transfer.funding.flagged` and does not automatically
credit, reserve, or refund the payment. This prevents a payer who sends less than instructed from
consuming your existing merchant balance.
An exact payment credits the quoted net USD value and drives reservation of the transfer's fixed
debit.
Only one exact payment can credit a funding intent. A later exact provider transaction is retained
for audit, flagged, and cannot credit your balance again. If an exact payment arrives after
`expires_at`, Yara credits it to your general merchant balance but does not revive or reserve the
expired transfer.
Each accepted or flagged provider payment appears in `funding_receipts` on the transfer:
```bash theme={null}
curl https://api.yara.cash/v1/transfers/76179a66-8695-47fd-bca4-310eaa816077 \
--header "x-yara-api-key: $YARA_API_KEY"
```
```json theme={null}
{
"data": {
"id": "76179a66-8695-47fd-bca4-310eaa816077",
"status": "RESERVED",
"funding_method": "CRYPTO_DEPOSIT",
"funding_receipts": [{
"id": "c81427de-2ca1-4d4b-af89-5bdb65764d8c",
"status": "CONSUMED",
"method": "CRYPTO_DEPOSIT",
"provider_transaction_id": "0x4f5d2d7a2c8a95c3",
"received_amount": { "value": "100", "asset": "USDC", "network": "BASE" },
"expected_amount": { "value": "100", "asset": "USDC", "network": "BASE" },
"variance_amount": { "value": "0", "asset": "USDC", "network": "BASE" },
"gross_usd": { "value": "100", "currency": "USD" },
"fee_usd": { "value": "0", "currency": "USD" },
"net_usd": { "value": "100", "currency": "USD" },
"received_at": "2026-06-16T03:02:00Z"
}]
}
}
```
Provider routing data, internal ledger references, and webhook payloads are not returned.
## Track the transfer
Listen for [webhooks](/wallets/guides/webhooks), or fetch the transfer by its `id`:
```bash theme={null}
curl https://api.yara.cash/v1/transfers/76179a66-8695-47fd-bca4-310eaa816077 \
--header "x-yara-api-key: $YARA_API_KEY"
```
| Status | Meaning |
| --------------------------- | -------------------------------------------------------------------------------------------- |
| `AWAITING_MERCHANT_FUNDING` | Yara is waiting for the exact transfer-specific NGN or crypto payment. |
| `RESERVED` | The fixed debit is reserved and ready for payout processing. |
| `AWAITING_FUNDING` | Your debit is reserved while Yara prepares payout liquidity. No action is required from you. |
| `SUBMITTED` | The payout provider accepted the transfer. |
| `SUCCEEDED` | The payout settled. |
| `FAILED` | The payout failed terminally and Yara released your reservation. |
| `REQUIRES_REVIEW` | The result is ambiguous or inconsistent. Yara keeps the reservation while reviewing it. |
Listen for `transfer.submitted`, `transfer.succeeded`, `transfer.failed`, and
`transfer.requires_review`. A timeout does not mean the payout failed. Yara reconciles its original
provider request and does not blindly create another payout.
If a request times out, retry it with the same `X-Idempotency-Key`. A new key creates a new
request.
Quotes and funding instructions expire. Request a new quote instead of paying expired
instructions.