Skip to main content
POST
Create transfer

​
Overview

Create a transfer to send funds to a saved recipient or an inline destination. Transfers support NGN bank transfers, USD ACH/wire/RTP/SWIFT transfers, USD stablecoin transfers, and native SOL or BNB 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. With the default USD_BALANCE preference, the deposit converts to USD. With NGN_BALANCE, it remains NGN.
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. You can also pay from an individual customer’s retained NGN balance. Set debit_scope: CUSTOMER, debit_currency: NGN, and on_behalf_of.customer_id. See Customer NGN balances. 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

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

​
Request Body

​
string
required
Transfer currency.Allowed values: NGN | USD | SOL | BNB
  • NGN transfers: only BANK_ACCOUNT recipients.
  • USD transfers: US_BANK_ACCOUNT, SWIFT_BANK_ACCOUNT, or CRYPTO_ADDRESS recipients using USDC or USDT.
  • SOL transfers: CRYPTO_ADDRESS recipients using SOL on Solana.
  • BNB transfers: CRYPTO_ADDRESS recipients using BNB on BSC.
​
string
Balance currency used to fund the transfer. Allowed values: USD, NGN.NGN bank transfers default to USD when this field is omitted, preserving the existing conversion flow. Set it to NGN to spend a retained NGN balance. Omit it for native SOL and BNB transfers.
​
string
Owner of the balance used to fund the transfer. Allowed values: MERCHANT, CUSTOMER. Defaults to MERCHANT.CUSTOMER is supported only when both currency and debit_currency are NGN. You must also send on_behalf_of.customer_id.
​
string
required
Transfer amount as a decimal string in the target currency.For NGN bank transfers, this is the amount the recipient receives and it must be at least 100.00. Below 1000.00, the flat NGN 20 low-value fee applies. At 1000.00 or above, the configured percentage fee and cap apply. Fees are charged separately from the selected balance.Native SOL amounts support up to 9 decimal places. Native BNB amounts support up to 8 decimal places. Non-NGN transfers must also meet the minimum effective value of USD 0.50.Example: 50000.00
​
string
required
Merchant-provided unique reference for the transfer.Example: txn_abc123
​
string
ID of a previously saved recipient (UUID). Mutually exclusive with destination.Example: 750e8400-e29b-41d4-a716-446655440000
​
object
Inline destination details. Mutually exclusive with recipient_id.
​
object
Optional metadata linking the transfer to a customer. Required for customer-scoped NGN transfers and effectively required for inline USD destinations.

​
Request Examples

​
Response

​
string
required
Transfer ID (UUID)
​
string
required
Merchant-provided reference
​
string
required
External status: PROCESSING, SETTLED, or FAILED
​
string
required
Transfer rail: NGN_BANK, USD_BANK, or CRYPTO
​
string
required
Transfer currency (NGN, USD, SOL, or BNB)
​
string
required
Transfer amount in the target currency
​
string
required
Currency debited from the selected balance. NGN bank transfers return USD or NGN; native-asset transfers return the native currency.
​
string
required
Balance owner: MERCHANT or CUSTOMER.
​
string
required
Total removed from the selected balance, expressed in debit_currency. This already includes fee; do not add the fee again.
​
string
required
Fee amount.
​
object
Captured exchange rate snapshot. Present for NGN transfers.
​
object
Resolved recipient details
​
object
Customer metadata if provided
​
string
required
When the transfer was created (ISO 8601)
​
string
When the transfer settled (ISO 8601). Null if not yet settled.

​
Success Response

In transfer responses, amount is what the recipient receives. debit_amount is the total balance reduction (principal plus fee), while fee shows the fee component of that total.

​
Notes

​
Customer NGN balance transfer

  • Set currency: NGN, debit_currency: NGN, and debit_scope: CUSTOMER.
  • Include on_behalf_of.customer_id for the customer whose balance should be debited.
  • The recipient must belong to that same customer.
  • The customer must have completed Tier 1 KYC.
  • The amount and fee are debited directly in NGN, with no transfer FX conversion.
  • NGN bank recipients must receive at least NGN 100. A flat NGN 20 fee applies only when the recipient amount is below NGN 1,000. At NGN 1,000 or above, the configured percentage fee and NGN cap apply.
  • For USD-funded NGN transfers, the NGN amount and fee are converted to USD and charged to the merchant USD withdrawal balance.
  • For native SOL and BNB transfers, omit debit_currency; the matching merchant native-asset balance is debited and the transfer fee is zero.
  • For NGN-funded NGN transfers, the amount and fee remain NGN and are charged to the selected merchant or customer NGN balance.
  • Use GET /v1/fees for the active percentage, cap, low-value fee, threshold, and minimum recipient amount.
  • The $0.50 minimum effective debit continues to apply to non-NGN transfers.
  • 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.