Merchant balance to Fiat
A merchant balance USD deposit paying out NGN to a bank account. This is the payout flow: you spend your own USD balance to pay someone in their local currency.
Check your balance with Get merchant balances
{
"USD": 761
}The deposit leg spends this balance, so it has to cover the amount.
Call Get available currencies
The merchant balance entry allows payouts and deposits, and its pairs includes fiat. NGN's bank channel has isPayoutAllowed: true. So merchant balance USD → NGN over bank is legal.
Call Get order limits
depositPaymentChannel: "merchant_balance"
depositCurrencyType: "merchant_balance"
depositCurrencyCode: "USD"
payoutPaymentChannel: "bank"
payoutCurrencyType: "fiat"
payoutCurrencyCode: "NGN"
payoutCountryIsoCode: "NG"
{
"deposit": {
"min": 1,
"max": 500,
"minUsd": 1,
"maxUsd": 500,
"step": 0.01,
"supportsDecimals": true
},
"payout": {
"min": 1412,
"max": 705782,
"minUsd": 1,
"maxUsd": 500,
"step": 1,
"supportsDecimals": false
}
}You can spend 1 to 500 USD, delivering 1,412 to 705,782 NGN. We want to send 100 USD.
KYC still applies to the person being paid — run the KYC flow against their email and country, passing the amounts.
Call Create quote
{
"deposit": {
"paymentChannel": "merchant_balance",
"currencyType": "merchant_balance",
"currencyCode": "USD",
"amount": 100
},
"payout": {
"paymentChannel": "bank",
"currencyType": "fiat",
"currencyCode": "NGN",
"countryIsoCode": "NG"
}
}100 USD of your balance delivers 141,156 NGN. The fees come off the payout leg: 2.5% platform and 1% merchant — that merchant_fee is yours.
Required fields, all on the payout leg:
phoneNumber
bankCode (from the enum options)
bankAccountNumber
The two *SandboxForcedFlow fields are optional and sandbox-only.
Call Create order
The deposit's transferInstructions are empty, and that is correct — nobody has to pay anything by hand. Your balance is the deposit.
Call Confirm order
No fields are needed; your balance is debited automatically.
{
"orderId": "692ef363ee270426b27cd0b6"
}Wait for "payout_successful"
If the bank rejects the transfer the order goes to payout_failed and, if it cannot be retried, is refunded to your balance. See Order statuses.
Last updated

