Skip to main content

​
What is a Transfer?

A transfer is a merchant-initiated send of funds to a bank recipient. Transfers support both Nigerian Naira (NGN) and US Dollar (USD) destinations.
CurrencyRecipient Types
NGNBANK_ACCOUNT
USDUS_BANK_ACCOUNT (ACH or wire), SWIFT_BANK_ACCOUNT

​
Funding Transfers

Transfers are funded from your withdrawal balance. There are two ways to ensure your balance has funds:
  1. From onramp settlements and offramp deposits — these land in your collection balance. Move them to the withdrawal balance via POST /v1/merchant/balance/transfer.
  2. Via merchant funding — send crypto or NGN directly to your funding accounts. These go straight into the withdrawal balance. NGN funding deposits are converted to USD at the current rate.

​
Saved vs Inline Recipients

Transfers support two modes for specifying the destination:

​
Saved recipients

Create a recipient once via POST /v1/recipients, then reference it by recipient_id in future transfers. This is ideal for recurring payments.

​
Inline recipients

Provide full destination details in the destination field of the transfer request. The recipient is created implicitly. This is convenient for one-off payments.
For inline USD destinations (US_BANK_ACCOUNT or SWIFT_BANK_ACCOUNT), on_behalf_of.customer_id is effectively required. That customer must have completed tier 2 verification.

​
Transfer Lifecycle

StatusMeaningTerminal
PROCESSINGTransfer has been accepted and is being executedNo
SETTLEDFunds delivered to the recipientYes
FAILEDTransfer failed permanentlyYes

​
NGN Transfers

When you create an NGN transfer:
  • The amount is in Naira (e.g. 50000.00)
  • The debit_amount in the response is the USD equivalent, calculated using the live USD→NGN sell rate at creation time
  • The rate field captures the exchange rate snapshot used
  • A minimum effective USD debit of $1.00 is enforced

​
USD Transfers

When you create a USD transfer:
  • The amount is in USD (e.g. 100.00)
  • debit_currency remains USD
  • The recipient’s customer must have completed tier 2 verification

​
Idempotency

POST /v1/transfers is idempotent. Include an Idempotency-Key header (or X-Idempotency-Key as a fallback) with a unique value to safely retry requests without creating duplicate transfers.

​
API Routes

​
Next Steps

Create Transfer

Send funds to a bank recipient

Create Recipient

Save a recipient for reuse

Merchant Balance

Check your available balance