Skip to main content
POST
/
v1
/
transfers
Create transfer
curl --request POST \
  --url https://api.daya.co/v1/transfers \
  --header 'Content-Type: application/json' \
  --header 'Idempotency-Key: <idempotency-key>' \
  --header 'X-Api-Key: <x-api-key>' \
  --data '
{
  "currency": "<string>",
  "amount": "<string>",
  "reference": "<string>",
  "recipient_id": "<string>",
  "destination": {
    "destination.type": "<string>",
    "destination.bank_account": {
      "destination.bank_account.account_number": "<string>",
      "destination.bank_account.bank_code": "<string>",
      "destination.bank_account.account_name": "<string>"
    },
    "destination.us_bank_account": {
      "destination.us_bank_account.account_owner_name": "<string>",
      "destination.us_bank_account.account_number": "<string>",
      "destination.us_bank_account.routing_number": "<string>",
      "destination.us_bank_account.bank_name": "<string>",
      "destination.us_bank_account.account_type": "<string>",
      "destination.us_bank_account.payout_scheme": "<string>",
      "destination.us_bank_account.address": {}
    },
    "destination.swift_bank_account": {
      "destination.swift_bank_account.account_owner_name": "<string>",
      "destination.swift_bank_account.account_owner_type": "<string>",
      "destination.swift_bank_account.account_country": "<string>",
      "destination.swift_bank_account.iban": "<string>",
      "destination.swift_bank_account.bic": "<string>",
      "destination.swift_bank_account.bank_name": "<string>",
      "destination.swift_bank_account.first_name": "<string>",
      "destination.swift_bank_account.last_name": "<string>",
      "destination.swift_bank_account.business_name": "<string>",
      "destination.swift_bank_account.category": "<string>",
      "destination.swift_bank_account.purpose_of_funds": [
        {}
      ],
      "destination.swift_bank_account.short_business_description": "<string>",
      "destination.swift_bank_account.address": {},
      "destination.swift_bank_account.bank_address": {}
    }
  },
  "on_behalf_of": {
    "on_behalf_of.customer_id": "<string>"
  }
}
'
{
  "id": "850e8400-e29b-41d4-a716-446655440000",
  "reference": "txn_ngn_001",
  "status": "PROCESSING",
  "rail": "NGN_BANK",
  "currency": "NGN",
  "amount": "50000.00",
  "debit_currency": "USD",
  "debit_amount": "33.07",
  "fee": "0.81",
  "rate": {
    "side": "SELL",
    "value": "1550.00",
    "captured_at": "2026-01-05T15:04:05Z"
  },
  "recipient": {
    "id": "750e8400-e29b-41d4-a716-446655440000",
    "type": "BANK_ACCOUNT",
    "bank_account": {
      "account_name": "John Doe",
      "account_number_last4": "7890",
      "bank_code": "044",
      "bank_name": "Access Bank"
    }
  },
  "on_behalf_of": null,
  "created_at": "2026-01-05T15:04:05Z",
  "settled_at": null
}

​
Overview

Create a transfer to send funds to a saved recipient or an inline destination. Transfers support both NGN bank transfers and USD ACH/wire/SWIFT transfers. Transfers are funded from your merchant balance. Before creating a transfer, ensure your balance has sufficient funds. You can fund your balance in two ways:
  • Crypto deposits — send stablecoins to your merchant funding crypto wallet addresses.
  • NGN deposits — transfer Naira to your permanent merchant funding NGN bank account (converted to USD at the current rate).
Funding account deposits are pooled into your collection balance. To use those funds for transfers or withdrawals, first move them to your withdrawal balance via the balance transfer endpoint. Merchant funding deposits go directly into your withdrawal balance. Exactly one of recipient_id or destination must be provided.
Saved vs inline recipients:
  • Saved recipients are created separately via POST /v1/recipients and referenced by recipient_id.
  • Inline recipients are created implicitly when destination is provided.
  • For inline USD destinations, on_behalf_of.customer_id is effectively required because the inline recipient-creation flow needs a customer context.
  • That customer must already be tier-2 verified; otherwise inline USD recipient creation fails.
Idempotency: This endpoint is idempotent. Use Idempotency-Key; X-Idempotency-Key is also accepted as a fallback.

​
Authentication

​
X-Api-Key
string
required
Your merchant API key
​
Idempotency-Key
string
required
Unique idempotency key for request deduplication. X-Idempotency-Key is also accepted.Example: 550e8400-e29b-41d4-a716-446655440000

​
Request Body

​
currency
string
required
Transfer currency.Allowed values: NGN | USD
  • NGN transfers: only BANK_ACCOUNT recipients.
  • USD transfers: only US_BANK_ACCOUNT or SWIFT_BANK_ACCOUNT recipients.
​
amount
string
required
Transfer amount as a decimal string in the target currency.Example: 50000.00
​
reference
string
required
Merchant-provided unique reference for the transfer.Example: txn_abc123
​
recipient_id
string
ID of a previously saved recipient (UUID). Mutually exclusive with destination.Example: 750e8400-e29b-41d4-a716-446655440000
​
destination
object
Inline destination details. Mutually exclusive with recipient_id.
​
on_behalf_of
object
Optional metadata linking the transfer to a customer. Effectively required for inline USD destinations.

​
Request Examples

curl --request POST \
  --url https://api.daya.co/v1/transfers \
  --header 'X-Api-Key: YOUR_API_KEY' \
  --header 'Idempotency-Key: 550e8400-e29b-41d4-a716-446655440000' \
  --header 'Content-Type: application/json' \
  --data '{
    "currency": "NGN",
    "amount": "50000.00",
    "reference": "txn_ngn_001",
    "recipient_id": "750e8400-e29b-41d4-a716-446655440000"
  }'

​
Response

​
id
string
required
Transfer ID (UUID)
​
reference
string
required
Merchant-provided reference
​
status
string
required
External status: PROCESSING, SETTLED, or FAILED
​
rail
string
required
Transfer rail: NGN_BANK or USD_BANK
​
currency
string
required
Transfer currency (NGN or USD)
​
amount
string
required
Transfer amount in the target currency
​
debit_currency
string
required
Currency debited from the merchant balance (USD)
​
debit_amount
string
required
Total amount debited from the merchant withdrawal balance, including fees.
​
fee
string
required
Fee amount.
​
rate
object
Captured exchange rate snapshot. Present for NGN transfers.
​
recipient
object
Resolved recipient details
​
on_behalf_of
object
Customer metadata if provided
​
created_at
string
required
When the transfer was created (ISO 8601)
​
settled_at
string
When the transfer settled (ISO 8601). Null if not yet settled.

​
Success Response

{
  "id": "850e8400-e29b-41d4-a716-446655440000",
  "reference": "txn_ngn_001",
  "status": "PROCESSING",
  "rail": "NGN_BANK",
  "currency": "NGN",
  "amount": "50000.00",
  "debit_currency": "USD",
  "debit_amount": "33.07",
  "fee": "0.81",
  "rate": {
    "side": "SELL",
    "value": "1550.00",
    "captured_at": "2026-01-05T15:04:05Z"
  },
  "recipient": {
    "id": "750e8400-e29b-41d4-a716-446655440000",
    "type": "BANK_ACCOUNT",
    "bank_account": {
      "account_name": "John Doe",
      "account_number_last4": "7890",
      "bank_code": "044",
      "bank_name": "Access Bank"
    }
  },
  "on_behalf_of": null,
  "created_at": "2026-01-05T15:04:05Z",
  "settled_at": null
}

​
Notes

  • A minimum effective USD debit of $1.00 is enforced.
  • For NGN transfers, amount is the NGN sent to the recipient and debit_amount is the total USD debited from your withdrawal balance, including fees.
  • Saved USD recipients can be reused later without resending full destination details.
  • Transfers emit transfer.* webhooks: transfer.created, transfer.processing, transfer.submitted, then transfer.completed or transfer.failed. transfer.requires_review is sent when a transfer is flagged.