# Merchant balance to Fiat

Let’s do a merchant balance USD deposit to NGN bank payout. 

{% stepper %}
{% step %}

#### First, call the [Get merchant balance](https://docs.fonbnk.com/server-to-server/api-endpoints/get-merchant-balances) endpoint to understand how much money is at your disposal.

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

{% endstep %}

{% step %}

#### Call [Get currencies](https://github.com/fonbnk/docs/blob/main/api-v2.md#get-currencies): 

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

```json
[
  {
    "currencyType": "fiat",
    "currencyCode": "NGN",
    "paymentChannels": [
      {
        "type": "bank",
        "transferTypes": [
          "manual",
          "redirect"
        ],
        "isDepositAllowed": true,
        "isPayoutAllowed": true
      },
      {
        "type": "airtime",
        "transferTypes": [
          "ussd"
        ],
        "carriers": [
          {
            "code": "MTN",
            "name": "MTN"
          },
          {
            "code": "AIRTEL",
            "name": "Airtel"
          },
          {
            "code": "GLO",
            "name": "Glo"
          },
          {
            "code": "9MOBILE",
            "name": "9Mobile"
          }
        ],
        "isDepositAllowed": true,
        "isPayoutAllowed": false
      },
      {
        "type": "mobile_money",
        "transferTypes": [
          "stk_push",
          "otp_stk_push"
        ],
        "carriers": [
          {
            "code": "MTN",
            "name": "MTN Mobile Money"
          },
          {
            "code": "AIRTEL",
            "name": "Airtel Money"
          },
          {
            "code": "GLO",
            "name": "Glo Mobile Money"
          },
          {
            "code": "9MOBILE",
            "name": "9Mobile Money"
          }
        ],
        "isDepositAllowed": true,
        "isPayoutAllowed": true
      }
    ],
    "currencyDetails": {
      "countryIsoCode": "NG",
    },
    "pairs": [
    "crypto",
      "merchant_balance"
    ]
  },
  {
    "currencyType": "merchant_balance",
    "currencyCode": "USD",
    "paymentChannels": [
      {
        "type": "merchant_balance",
        "transferTypes": [
          "manual"
        ],
        "isDepositAllowed": true,
        "isPayoutAllowed": true
      }
    ],
    "currencyDetails": {
      "merchantName": "Fonbnk"
    },
    "pairs": [
      "fiat",
      "crypto"
    ]
  }
]
```

{% endcode %}

We see that NGN supports deposit and payout. Merchant balance supports both deposit and payout too. So we can do NGN -> Merchant balance USD.
{% endstep %}

{% step %}

#### Call [Get order limits](https://docs.fonbnk.com/server-to-server/api-endpoints/get-order-limits) with:

* 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>"

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

```json
{
    "deposit": {
        "min": 1,
        "max": 500,
        "minUsd": 1,
        "maxUsd": 500
    },
    "payout": {
        "min": 1412,
        "max": 705782,
        "minUsd": 1,
        "maxUsd": 500
    }
}
```

{% endcode %}

We see that the minimum deposit is 1 USD and the maximum is 500 USD, a user can receive from 1412 NGN to 705782 NGN.

Assume the merchant wants to send 100 USD. Reuse the [KYC requirements](https://docs.fonbnk.com/server-to-server/kyc-flow) checklist to confirm the customer has passed the appropriate tier. With the example rules, this amount again requires the <mark style="color:yellow;">advanced</mark> document set before you continue.
{% endstep %}

{% step %}

#### Call [Create quote](https://docs.fonbnk.com/server-to-server/api-endpoints/create-quote):

{% 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": "tester"
        },
        "cashout": {
            "amountBeforeFees": 100,
            "amountAfterFees": 100,
            "chargedFees": [],
            "totalChargedFees": 0,
            "chargedFeesPerRecipient": {},
            "amountBeforeFeesUsd": 100,
            "amountAfterFeesUsd": 100,
            "chargedFeesUsd": [],
            "totalChargedFeesUsd": 0,
            "exchangeRate": 1,
            "exchangeRateAfterFees": 1,
            "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,
            "chargedFees": [
                {
                    "id": "service_fee",
                    "type": "percentage",
                    "recipient": "platform",
                    "amount": 3656.9
                },
                {
                    "id": "merchant_fee",
                    "type": "percentage",
                    "recipient": "merchant",
                    "amount": 1462.76
                }
            ],
            "totalChargedFees": 5119.66,
            "chargedFeesPerRecipient": {
                "platform": 3656.9,
                "merchant": 1462.76
            },
            "amountBeforeFeesUsd": 100,
            "amountAfterFeesUsd": 96.499768,
            "chargedFeesUsd": [
                {
                    "id": "service_fee",
                    "type": "percentage",
                    "recipient": "platform",
                    "amount": 2.5
                },
                {
                    "id": "merchant_fee",
                    "type": "percentage",
                    "recipient": "merchant",
                    "amount": 1
                }
            ],
            "totalChargedFeesUsd": 3.5,
            "exchangeRate": 1462.76,
            "exchangeRateAfterFees": 1515.8171,
            "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 %}

A user will receive 141156 NGN for 100 USD of merchant balance. Collect these fields:

* <mark style="color:yellow;">phoneNumber</mark>
* <mark style="color:yellow;">bankCode</mark>
* <mark style="color:yellow;">bankAccountNumber</mark>
* <mark style="color:yellow;">depositSandboxForcedFlow</mark> (sandbox optional field to simulate deposit success/failure/underpayment/overpayment)
* <mark style="color:yellow;">payoutSandboxForcedFlow</mark> (sandbox optional field to simulate payout success/failure)
  {% endstep %}

{% step %}

#### Create the order via [Create order](https://docs.fonbnk.com/server-to-server/api-endpoints/create-order):

{% 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" 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": "bohdan test"
            },
            "cashout": {
                "amountBeforeFees": 100,
                "amountAfterFees": 100,
                "chargedFees": [],
                "totalChargedFees": 0,
                "chargedFeesPerRecipient": {},
                "amountBeforeFeesUsd": 100,
                "amountAfterFeesUsd": 100,
                "chargedFeesUsd": [],
                "totalChargedFeesUsd": 0,
                "exchangeRate": 1,
                "exchangeRateAfterFees": 1,
                "chargedFeesPerRecipientUsd": {},
                "feeSettings": []
            },
            "providedFieldsToCreateOrder": {},
            "transferInstructions": {
                "type": "manual",
                "transferDetails": [],
                "instructionsText": "",
                "fieldsToConfirmOrder": []
            }
        },
        "payout": {
            "paymentChannel": "bank",
            "currencyType": "fiat",
            "currencyCode": "NGN",
            "currencyDetails": {
                "countryIsoCode": "NG"
            },
            "cashout": {
                "amountBeforeFees": 146276,
                "amountAfterFees": 141156,
                "chargedFees": [
                    {
                        "id": "service_fee",
                        "type": "percentage",
                        "recipient": "platform",
                        "amount": 3656.9
                    },
                    {
                        "id": "merchant_fee",
                        "type": "percentage",
                        "recipient": "merchant",
                        "amount": 1462.76
                    }
                ],
                "totalChargedFees": 5119.66,
                "chargedFeesPerRecipient": {
                    "platform": 3656.9,
                    "merchant": 1462.76
                },
                "amountBeforeFeesUsd": 100,
                "amountAfterFeesUsd": 96.499768,
                "chargedFeesUsd": [
                    {
                        "id": "service_fee",
                        "type": "percentage",
                        "recipient": "platform",
                        "amount": 2.5
                    },
                    {
                        "id": "merchant_fee",
                        "type": "percentage",
                        "recipient": "merchant",
                        "amount": 1
                    }
                ],
                "totalChargedFeesUsd": 3.5,
                "exchangeRate": 1462.76,
                "exchangeRateAfterFees": 1515.8171,
                "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"
                    }
                ]
            },
            "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 %}
{% endstep %}

{% step %}

#### Call [Confirm order](https://docs.fonbnk.com/server-to-server/api-endpoints/confirm-order):

Its a merchant balance deposit, so no fields are required, your balance will be debited automatically.

Example request

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

{% endstep %}

{% step %}

#### The system validates the deposit and processes payout.&#x20;

{% endstep %}

{% step %}

#### Use [Get order](https://docs.fonbnk.com/server-to-server/api-endpoints/get-order) to track status until " <mark style="color:yellow;">payout\_successful</mark>".

{% endstep %}
{% endstepper %}