Make a transfer

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

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:

{ "method": "BALANCE" }

{ "method": "BANK_TRANSFER", "currency": "NGN" }

{ "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

{
  "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

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

{
  "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:

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:

curl https://api.yara.cash/v1/transfers/76179a66-8695-47fd-bca4-310eaa816077 \
  --header "x-yara-api-key: $YARA_API_KEY"

{
  "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, or fetch the transfer by its id:

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.

Wallets as a Service

Guides

API reference

Addresses

Balance

Deposits

Transfers

Transactions

Webhooks

Reference data

Status

Make a transfer

Before you start

Step 1 — Quote the transfer

Quote response

Step 2 — Create the transfer

Bank funding instructions

Fund safely

Track the transfer

​Before you start

​Step 1 — Quote the transfer

​Quote response

​Step 2 — Create the transfer

​Bank funding instructions

​Fund safely

​Track the transfer

Before you start

Step 1 — Quote the transfer

Quote response

Step 2 — Create the transfer

Bank funding instructions

Fund safely

Track the transfer