> For the complete documentation index, see [llms.txt](https://docs.fonbnk.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.fonbnk.com/server-to-server/integration-guide/flow-examples/merchant-balance-to-fiat.md).

# 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.

{% stepper %}
{% step %}

#### Check your balance with [Get merchant balances](/server-to-server/api-endpoints/merchant-balance/get-merchant-balances.md)

```json
{
    "USD": 761
}
```

The deposit leg spends this balance, so it has to cover the amount.
{% endstep %}

{% step %}

#### Call [Get available currencies](/server-to-server/api-endpoints/get-available-currencies.md)

{% code title="Example response (trimmed to the two entries we need)" overflow="wrap" expandable="true" %}

```json
[
  {
    "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"]
  }
]
```

{% endcode %}

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.

{% hint style="info" %}
You could pay out over `airtime` instead — it is payout-only, which is exactly what this flow needs. Swap `payoutPaymentChannel` and add a `carrierCode`.
{% endhint %}
{% endstep %}

{% step %}

#### Call [Get order limits](/server-to-server/api-endpoints/get-order-limits.md)

* depositPaymentChannel: "<mark style="color:yellow;">merchant\_balance</mark>"
* depositCurrencyType: "<mark style="color:yellow;">merchant\_balance</mark>"
* depositCurrencyCode: "<mark style="color:yellow;">USD</mark>"
* payoutPaymentChannel: "<mark style="color:yellow;">bank</mark>"
* payoutCurrencyType: "<mark style="color:yellow;">fiat</mark>"
* payoutCurrencyCode: "<mark style="color:yellow;">NGN</mark>"
* payoutCountryIsoCode: "<mark style="color:yellow;">NG</mark>"

{% code title="Example response" overflow="wrap" %}

```json
{
    "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
    }
}
```

{% endcode %}

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](/server-to-server/kyc-flow.md) against their email and country, passing the amounts.
{% endstep %}

{% step %}

#### Call [Create quote](/server-to-server/api-endpoints/create-quote.md)

{% code title="Example request" %}

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

{% endcode %}

{% code title="Example response" overflow="wrap" expandable="true" %}

```json
{
    "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" }
                ]
            }
        ]
    }
}
```

{% endcode %}

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:

* <mark style="color:yellow;">phoneNumber</mark>
* <mark style="color:yellow;">bankCode</mark> (from the enum options)
* <mark style="color:yellow;">bankAccountNumber</mark>

The two `*SandboxForcedFlow` fields are optional and sandbox-only.
{% endstep %}

{% step %}

#### Call [Create order](/server-to-server/api-endpoints/create-order.md)

{% code title="Example request" overflow="wrap" expandable="true" %}

```json
{
    "quoteId": "692ef2bddebffd422445f0a7",
    "userCountryIsoCode": "NG",
    "userEmail": "tester+ng@fonbnk.com",
    "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"
    }
}
```

{% endcode %}

{% code title="Example response (trimmed)" overflow="wrap" expandable="true" %}

```json
{
    "quoteUsed": true,
    "order": {
        "_id": "692ef363ee270426b27cd0b6",
        "countryIsoCode": "NG",
        "userId": "686671f07730d8d1a9b2260a",
        "userEmail": "tester+ng@fonbnk.com",
        "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"
    }
}
```

{% endcode %}

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

{% step %}

#### Call [Confirm order](/server-to-server/api-endpoints/confirm-order.md)

No fields are needed; your balance is debited automatically.

```json
{
  "orderId": "692ef363ee270426b27cd0b6"
}
```

{% endstep %}

{% step %}

#### We debit your balance and send the payout

{% endstep %}

{% step %}

#### Wait for "<mark style="color:yellow;">payout\_successful</mark>"

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](/server-to-server/order-statuses.md).
{% endstep %}
{% endstepper %}


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://docs.fonbnk.com/server-to-server/integration-guide/flow-examples/merchant-balance-to-fiat.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.