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.

1

Check your balance with Get merchant balances

{
    "USD": 761
}

The deposit leg spends this balance, so it has to cover the amount.

2

Call Get available currencies

Example response (trimmed to the two entries we need)

[
  {
    "currencyType": "merchant_balance",
    "currencyCode": "USD",
    "paymentChannels": [
      {
        "name": "Merchant balance",
        "type": "merchant_balance",
        "transferTypes": ["manual"],
        "isDepositAllowed": true,
        "isPayoutAllowed": true
      }
    ],
    "currencyDetails": { "merchantName": "Your company" },
    "pairs": ["fiat", "crypto"]
  },
  {
    "currencyType": "fiat",
    "currencyCode": "NGN",
    "paymentChannels": [
      {
        "name": "Bank",
        "type": "bank",
        "transferTypes": ["manual"],
        "isDepositAllowed": true,
        "isPayoutAllowed": true
      },
      {
        "name": "Airtime",
        "type": "airtime",
        "transferTypes": [],
        "isDepositAllowed": false,
        "isPayoutAllowed": true,
        "carriers": [
          { "code": "ng_mtn", "name": "MTN Nigeria" },
          { "code": "ng_airtel", "name": "Airtel Nigeria" },
          { "code": "ng_glo", "name": "Glo Mobile Nigeria" },
          { "code": "ng_9mobile", "name": "9Mobile Nigeria" }
        ]
      }
    ],
    "currencyDetails": { "countryIsoCode": "NG" },
    "pairs": ["crypto", "merchant_balance"]
  }
]

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.

You could pay out over airtime instead — it is payout-only, which is exactly what this flow needs. Swap payoutPaymentChannel and add a carrierCode.

3

Call Get order limits

• depositPaymentChannel: "merchant_balance"

• depositCurrencyType: "merchant_balance"

• depositCurrencyCode: "USD"

• payoutPaymentChannel: "bank"

• payoutCurrencyType: "fiat"

• payoutCurrencyCode: "NGN"

• payoutCountryIsoCode: "NG"

Example response

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

4

Call Create quote

Example request

{
  "deposit": {
    "paymentChannel": "merchant_balance",
    "currencyType": "merchant_balance",
    "currencyCode": "USD",
    "amount": 100
  },
  "payout": {
    "paymentChannel": "bank",
    "currencyType": "fiat",
    "currencyCode": "NGN",
    "countryIsoCode": "NG"
  }
}

Example response

{
    "quoteId": "692ef2bddebffd422445f0a7",
    "quoteExpiresAt": "2025-12-02T14:37:57.910Z",
    "deposit": {
        "paymentChannel": "merchant_balance",
        "currencyType": "merchant_balance",
        "currencyCode": "USD",
        "currencyDetails": { "merchantName": "Your company" },
        "cashout": {
            "amountBeforeFees": 100,
            "amountAfterFees": 100,
            "amountBeforeFeesUsd": 100,
            "amountAfterFeesUsd": 100,
            "chargedFees": [],
            "chargedFeesUsd": [],
            "totalChargedFees": 0,
            "totalChargedFeesUsd": 0,
            "exchangeRate": 1,
            "exchangeRateAfterFees": 1,
            "chargedFeesPerRecipient": {},
            "chargedFeesPerRecipientUsd": {},
            "feeSettings": []
        },
        "fieldsToCreateOrder": [
            {
                "key": "depositSandboxForcedFlow",
                "type": "enum",
                "label": "Sandbox deposit forced flow",
                "required": false,
                "defaultValue": "deposit_success",
                "options": [
                    { "label": "Deposit success", "value": "deposit_success" },
                    { "label": "Deposit invalid", "value": "deposit_invalid" },
                    { "label": "Deposit underpayment (50%)", "value": "deposit_underpayment" },
                    { "label": "Deposit overpayment (200%)", "value": "deposit_overpayment" }
                ]
            }
        ],
        "transferType": "manual"
    },
    "payout": {
        "paymentChannel": "bank",
        "currencyType": "fiat",
        "currencyCode": "NGN",
        "currencyDetails": { "countryIsoCode": "NG" },
        "cashout": {
            "amountBeforeFees": 146276,
            "amountAfterFees": 141156,
            "amountBeforeFeesUsd": 100,
            "amountAfterFeesUsd": 96.499768,
            "chargedFees": [
                { "id": "service_fee", "type": "percentage", "recipient": "platform", "amount": 3656.9 },
                { "id": "merchant_fee", "type": "percentage", "recipient": "merchant", "amount": 1462.76 }
            ],
            "chargedFeesUsd": [
                { "id": "service_fee", "type": "percentage", "recipient": "platform", "amount": 2.5 },
                { "id": "merchant_fee", "type": "percentage", "recipient": "merchant", "amount": 1 }
            ],
            "totalChargedFees": 5119.66,
            "totalChargedFeesUsd": 3.5,
            "exchangeRate": 1462.76,
            "exchangeRateAfterFees": 1515.8171,
            "chargedFeesPerRecipient": { "platform": 3656.9, "merchant": 1462.76 },
            "chargedFeesPerRecipientUsd": { "platform": 2.5, "merchant": 1 },
            "feeSettings": [
                { "id": "service_fee", "recipient": "platform", "type": "percentage", "value": 2.5, "min": 0, "max": "Infinity" },
                { "id": "merchant_fee", "recipient": "merchant", "type": "percentage", "value": 1, "min": 0, "max": "Infinity" }
            ]
        },
        "fieldsToCreateOrder": [
            { "key": "phoneNumber", "label": "Phone Number", "required": true, "type": "phone" },
            {
                "key": "bankCode",
                "label": "Bank name",
                "required": true,
                "type": "enum",
                "options": [
                    { "label": "Sandbox Bank", "value": "1" },
                    { "label": "Sandbox Bank 2", "value": "2" },
                    { "label": "Sandbox Bank 3", "value": "3" }
                ]
            },
            { "key": "bankAccountNumber", "label": "Bank Account Number", "required": true, "type": "string" },
            {
                "key": "payoutSandboxForcedFlow",
                "type": "enum",
                "label": "Sandbox payout forced flow",
                "required": false,
                "defaultValue": "payout_success",
                "options": [
                    { "label": "Payout success", "value": "payout_success" },
                    { "label": "Payout failed", "value": "payout_failed" }
                ]
            }
        ]
    }
}

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.

5

Call Create order

Example request

{
    "quoteId": "692ef2bddebffd422445f0a7",
    "userCountryIsoCode": "NG",
    "userEmail": "[e-mail]",
    "userIp": "223.134.123.12",
    "deposit": {
        "paymentChannel": "merchant_balance",
        "currencyType": "merchant_balance",
        "currencyCode": "USD",
        "amount": 100
    },
    "payout": {
        "paymentChannel": "bank",
        "currencyType": "fiat",
        "currencyCode": "NGN",
        "countryIsoCode": "NG"
    },
    "fieldsToCreateOrder": {
        "phoneNumber": "2348012345678",
        "bankCode": "1",
        "bankAccountNumber": "1234567890"
    }
}

Example response (trimmed)

{
    "quoteUsed": true,
    "order": {
        "_id": "692ef363ee270426b27cd0b6",
        "countryIsoCode": "NG",
        "userId": "686671f07730d8d1a9b2260a",
        "userEmail": "[e-mail]",
        "status": "deposit_awaiting",
        "deposit": {
            "paymentChannel": "merchant_balance",
            "currencyType": "merchant_balance",
            "currencyCode": "USD",
            "currencyDetails": { "merchantName": "Your company" },
            "providedFieldsToCreateOrder": {},
            "transferInstructions": {
                "type": "manual",
                "transferDetails": [],
                "instructionsText": "",
                "fieldsToConfirmOrder": []
            }
        },
        "payout": {
            "paymentChannel": "bank",
            "currencyType": "fiat",
            "currencyCode": "NGN",
            "currencyDetails": { "countryIsoCode": "NG" },
            "providedFieldsToCreateOrder": {
                "phoneNumber": "2348012345678",
                "bankCode": "1",
                "bankAccountNumber": "1234567890"
            }
        },
        "statusChangeLogs": [],
        "createdAt": "2025-12-02T14:10:43.333Z",
        "updatedAt": "2025-12-02T14:10:43.333Z",
        "expiresAt": "2025-12-02T17:10:43.294Z"
    }
}

The deposit's transferInstructions are empty, and that is correct — nobody has to pay anything by hand. Your balance is the deposit.

6

Call Confirm order

No fields are needed; your balance is debited automatically.

{
  "orderId": "692ef363ee270426b27cd0b6"
}

7

We debit your balance and send the payout

8

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.