Fiat to Merchant balance

An NGN (fiat) deposit crediting your USD merchant balance. This is the collections flow: a user pays in local currency and you hold the value in USD.

Every response on this page is a sandbox capture — hence "Sandbox Bank" in the bank list and the depositSandboxForcedFlow field on the deposit leg.

1

Call Get available currencies

Example response (trimmed to the two entries we need)

[
  {
    "currencyType": "fiat",
    "currencyCode": "NGN",
    "paymentChannels": [
      {
        "name": "Bank transfer",
        "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"]
  },
  {
    "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"]
  }
]

NGN takes deposits over bank, and its pairs includes merchant_balance. So NGN → merchant balance USD over bank is legal. Airtime is payout-only, so it cannot be the deposit leg here.

2

Call Get order limits

• depositPaymentChannel: "bank"

• depositCurrencyType: "fiat"

• depositCurrencyCode: "NGN"

• depositCountryIsoCode: "NG"

• payoutPaymentChannel: "merchant_balance"

• payoutCurrencyType: "merchant_balance"

• payoutCurrencyCode: "USD"

Example response

{
  "deposit": {
    "min": 1523,
    "max": 761469,
    "minUsd": 1,
    "maxUsd": 500,
    "step": 1,
    "supportsDecimals": false
  },
  "payout": {
    "min": 1,
    "max": 500,
    "minUsd": 1,
    "maxUsd": 500,
    "step": 0.01,
    "supportsDecimals": true
  }
}

The user can pay 1,523 to 761,469 NGN, crediting 1 to 500 USD. We want 100 USD credited.

KYC applies to the person paying — run the KYC flow against their email and country, passing the amounts.

3

Call Create quote

Example request

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

Example response

{
    "quoteId": "692ee3e2f34fda2f154d4496",
    "quoteExpiresAt": "2025-12-02T13:34:34.797Z",
    "deposit": {
        "paymentChannel": "bank",
        "currencyType": "fiat",
        "currencyCode": "NGN",
        "currencyDetails": { "countryIsoCode": "NG" },
        "cashout": {
            "amountBeforeFees": 152206,
            "amountAfterFees": 146879,
            "amountBeforeFeesUsd": 103.626795,
            "amountAfterFeesUsd": 100,
            "chargedFees": [
                { "id": "service_fee", "type": "percentage", "recipient": "platform", "amount": 3805.15 },
                { "id": "merchant_fee", "type": "percentage", "recipient": "merchant", "amount": 1522.06 }
            ],
            "chargedFeesUsd": [
                { "id": "service_fee", "type": "percentage", "recipient": "platform", "amount": 2.59067 },
                { "id": "merchant_fee", "type": "percentage", "recipient": "merchant", "amount": 1.036268 }
            ],
            "totalChargedFees": 5327.21,
            "totalChargedFeesUsd": 3.626938,
            "exchangeRate": 1468.79,
            "exchangeRateAfterFees": 1522.06,
            "chargedFeesPerRecipient": { "platform": 3805.15, "merchant": 1522.06 },
            "chargedFeesPerRecipientUsd": { "platform": 2.59067, "merchant": 1.036268 },
            "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": "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": "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": []
    }
}

For you to be credited 100 USD the user pays 152,206 NGN. The fees come off the deposit leg: 2.5% platform and 1% merchant — that merchant_fee is yours.

Required fields, all on the deposit leg:

• phoneNumber

• bankCode (from the enum options)

• bankAccountNumber

The payout leg needs nothing — the destination is your own balance.

Sandbox tip: set depositSandboxForcedFlow to force a success, a failure, an underpayment or an overpayment. It is the easy way to exercise your error paths without moving real funds. Read the values from the field's own options array — they differ by offer, and the merchant-balance leg publishes no forced-flow field at all.

4

Call Create order

Send only the fields the quote asked for — there is no wallet address in this flow.

Example request

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

Example response (trimmed)

{
    "quoteUsed": true,
    "order": {
        "_id": "692ee4bba60e213546387b1e",
        "countryIsoCode": "NG",
        "userId": "686671f07730d8d1a9b2260a",
        "userEmail": "[e-mail]",
        "status": "deposit_awaiting",
        "deposit": {
            "paymentChannel": "bank",
            "currencyType": "fiat",
            "currencyCode": "NGN",
            "currencyDetails": { "countryIsoCode": "NG" },
            "providedFieldsToCreateOrder": {
                "phoneNumber": "2348012345678",
                "bankCode": "1",
                "bankAccountNumber": "1234567890"
            },
            "transferInstructions": {
                "type": "manual",
                "instructionsText": "It is a sandbox offer. Confirm the transfer from your side and system will automatically confirm the transfer within 1 minute.",
                "warningText": "Non-confirmed orders will be automatically canceled after 5 minutes.",
                "transferDetails": [
                    { "id": "recipientBankName", "label": "Bank name", "value": "Sandbox Bank" },
                    { "id": "recipientBankAccountNumber", "label": "Bank account number", "value": "1073315490" },
                    { "id": "recipientBankAccountName", "label": "Bank account name", "value": "SANDY BOXERRITTO" },
                    { "id": "amountToSend", "label": "Amount to send", "value": "152206" }
                ],
                "fieldsToConfirmOrder": []
            }
        },
        "payout": {
            "paymentChannel": "merchant_balance",
            "currencyType": "merchant_balance",
            "currencyCode": "USD",
            "currencyDetails": { "merchantName": "Your company" },
            "providedFieldsToCreateOrder": {}
        },
        "statusChangeLogs": [],
        "createdAt": "2025-12-02T13:08:11.013Z",
        "updatedAt": "2025-12-02T13:08:11.013Z",
        "expiresAt": "2025-12-02T13:13:10.972Z"
    }
}

The recipient* values are the agent's account — where the user sends the money — not the bankAccountNumber you collected, which is the user's own.

5

The user transfers the exact amount

In production a bank transfer also carries a narration the user must copy. Show every entry of transferDetails as it comes.

6

Call Confirm order

fieldsToConfirmOrder is empty, so the order ID is all you need.

{
  "orderId": "692ee4bba60e213546387b1e"
}

7

We validate the deposit and credit your balance

8

Wait for "payout_successful"

Then Get merchant balances shows the new total.