# Fiat to Merchant balance

Let’s do a NGN (fiat) deposit to merchant balance USD payout. 

{% stepper %}
{% step %}

#### First, call [Get available currencies](https://docs.fonbnk.com/server-to-server/api-endpoints/get-available-currencies) and assume you receive:

{% 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 NGN supports deposit via bank/airtime/mobile money, and payout via bank/mobile money. Merchant balance supports both deposit and payout. So we can do Fiat → 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;">bank</mark>"
* depositCurrencyType: "<mark style="color:yellow;">fiat</mark>"
* depositCurrencyCode: "<mark style="color:yellow;">NGN</mark>"
* depositCountryIsoCode: "<mark style="color:yellow;">NG</mark>"
* payoutPaymentChannel: "<mark style="color:yellow;">merchant\_balance</mark>"
* payoutCurrencyType: "<mark style="color:yellow;">merchant\_balance</mark>"
* payoutCurrencyCode: "<mark style="color:yellow;">USD</mark>"

{% code title="Example response" %}

```json
{
  "deposit": {
    "min": 1523,
    "max": 761469,
    "minUsd": 1,
    "maxUsd": 500
  },
  "payout": {
    "min": 1,
    "max": 500,
    "minUsd": 1,
    "maxUsd": 500
  }
}
```

{% endcode %}

We see that the minimum deposit is 1523 NGN and the maximum is 761469 NGN, which corresponds to 1-500 USD limit for merchant balance.

Assume the merchant wants to receive 100 USD. Check the user’s tier using the [KYC requirements](https://docs.fonbnk.com/server-to-server/kyc-flow) flow before proceeding. In the sample sandbox rules, payouts of 100 USD or more trigger the <mark style="color:yellow;">advanced</mark> tier, so be sure the user has submitted and been approved for that document set.
{% endstep %}

{% step %}

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

{% code title="Example request" %}

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

{% endcode %}

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

```json
{
    "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": "bohdan test"
        },
        "cashout": {
            "amountBeforeFees": 100,
            "amountAfterFees": 100,
            "amountBeforeFeesUsd": 100,
            "amountAfterFeesUsd": 100,
            "chargedFees": [],
            "chargedFeesUsd": [],
            "totalChargedFees": 0,
            "totalChargedFeesUsd": 0,
            "exchangeRate": 1,
            "exchangeRateAfterFees": 1,
            "chargedFeesPerRecipient": {},
            "chargedFeesPerRecipientUsd": {},
            "feeSettings": []
        },
        "fieldsToCreateOrder": [
            {
                "key": "payoutSandboxForcedFlow",
                "type": "enum",
                "label": "Sandbox payout forced flow",
                "defaultValue": "payout_success",
                "required": false,
                "options": [
                    {
                        "label": "Payout success",
                        "value": "payout_success"
                    },
                    {
                        "label": "Payout failed -> Refund success",
                        "value": "refund_success"
                    },
                    {
                        "label": "Payout failed -> Refund failed",
                        "value": "refund_failed"
                    }
                ]
            }
        ]
    }
}
```

{% endcode %}

For a merchant to receive 100 USD, user must deposit 152206 NGN. Collect these fields:

* <mark style="color:yellow;">phoneNumber</mark>
* <mark style="color:yellow;">bankCode</mark> (from enum options)
* <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)

> **Sandbox tip:** When you're testing in the sandbox environment you can set <mark style="color:yellow;">depositSandboxForcedFlow</mark> or <mark style="color:yellow;">payoutSandboxForcedFlow</mark> to force the platform to return success, failure, or other edge outcomes. This makes it easy to imitate failed flows without moving real funds.
> {% 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": "692ee3e2f34fda2f154d4496",
    "userCountryIsoCode": "NG",
    "userEmail": "tester+ng@fonbnk.com",
    "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": {
        "blockchainWalletAddress": "0x5b7ae3c6c87f4a3f94b35c77233b13191ebfad20",
        "phoneNumber": "2348012345678",
        "bankCode": "1",
        "bankAccountNumber": "1234567890"
    }
}
```

{% endcode %}

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

```json
{
    "quoteUsed": true,
    "order": {
        "_id": "692ee4bba60e213546387b1e",
        "countryIsoCode": "NG",
        "userId": "686671f07730d8d1a9b2260a",
        "userEmail": "tester+ng@fonbnk.com",
        "status": "deposit_awaiting",
        "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"
                    }
                ]
            },
            "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": "bohdan test"
            },
            "cashout": {
                "amountBeforeFees": 100,
                "amountAfterFees": 100,
                "amountBeforeFeesUsd": 100,
                "amountAfterFeesUsd": 100,
                "chargedFees": [],
                "chargedFeesUsd": [],
                "totalChargedFees": 0,
                "totalChargedFeesUsd": 0,
                "exchangeRate": 1,
                "exchangeRateAfterFees": 1,
                "chargedFeesPerRecipient": {},
                "chargedFeesPerRecipientUsd": {
                    "platform": 2.59067,
                    "merchant": 1.036268
                },
                "feeSettings": []
            },
            "providedFieldsToCreateOrder": {}
        },
        "statusChangeLogs": [],
        "createdAt": "2025-12-02T13:08:11.013Z",
        "updatedAt": "2025-12-02T13:08:11.013Z",
        "expiresAt": "2025-12-02T13:13:10.972Z"
    }
}
```

{% endcode %}
{% endstep %}

{% step %}

#### A user makes the transfer with the exact amount and reference.&#x20;

{% endstep %}

{% step %}

#### Call [Confirm order](https://docs.fonbnk.com/server-to-server/api-endpoints/confirm-order) if no extra fields are required:

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

{% 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 %}