> 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/fiat-to-crypto.md).

# Fiat to Crypto

An NGN (fiat) deposit paying out POLYGON\_USDT (crypto) — the classic on-ramp.

{% stepper %}
{% 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": "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": "crypto",
    "currencyCode": "POLYGON_USDT",
    "paymentChannels": [
      {
        "name": "Crypto",
        "type": "crypto",
        "transferTypes": ["manual"],
        "isDepositAllowed": true,
        "isPayoutAllowed": true
      }
    ],
    "currencyDetails": {
      "network": "POLYGON",
      "asset": "USDT",
      "contractAddress": "0xc2132D05D31c914a87C6611C10748AEb04B58e8F"
    },
    "pairs": ["fiat", "merchant_balance"]
  }
]
```

{% endcode %}

NGN takes deposits over `bank` and pays out over `bank` or `airtime` — airtime is payout-only, so it cannot be the deposit leg. POLYGON\_USDT allows both directions, and NGN's `pairs` includes `crypto`. So NGN → POLYGON\_USDT over `bank` is legal.
{% endstep %}

{% step %}

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

* 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;">crypto</mark>"
* payoutCurrencyType: "<mark style="color:yellow;">crypto</mark>"
* payoutCurrencyCode: "<mark style="color:yellow;">POLYGON\_USDT</mark>"

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

```json
{
  "deposit": {
    "min": 1556,
    "max": 311184,
    "minUsd": 1,
    "maxUsd": 200,
    "step": 1,
    "supportsDecimals": false
  },
  "payout": {
    "min": 1,
    "max": 200,
    "minUsd": 1,
    "maxUsd": 200,
    "step": 0.000001,
    "supportsDecimals": true
  }
}
```

{% endcode %}

The user wants 100 POLYGON\_USDT, which is inside the payout window. Check their KYC tier with the [KYC flow](/server-to-server/kyc-flow.md) — pass the amounts so the answer covers this order.
{% endstep %}

{% step %}

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

Set the amount on **one** leg only. Here it is the payout, because the user asked for a crypto amount.

{% code title="Example request" %}

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

{% endcode %}

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

```json
{
  "quoteId": "68628fa56ff494df5f39faf5",
  "quoteExpiresAt": "2026-08-20T10:10:10.000Z",
  "deposit": {
    "paymentChannel": "bank",
    "currencyType": "fiat",
    "currencyCode": "NGN",
    "currencyDetails": { "countryIsoCode": "NG" },
    "cashout": {
      "exchangeRate": 1500,
      "exchangeRateAfterFees": 1531.1269,
      "amountBeforeFees": 153128,
      "amountAfterFees": 150015,
      "amountBeforeFeesUsd": 102.085333,
      "amountAfterFeesUsd": 100.01,
      "chargedFees": [
        { "id": "provider_fee", "type": "flat_amount", "recipient": "provider", "amount": 50 },
        { "id": "service_fee", "type": "percentage", "recipient": "platform", "amount": 3063 }
      ],
      "totalChargedFees": 3113,
      "totalChargedFeesUsd": 2.075333,
      "chargedFeesPerRecipient": { "provider": 50, "platform": 3063 }
    },
    "fieldsToCreateOrder": [
      { "key": "phoneNumber", "label": "Phone Number", "required": true, "type": "phone" },
      {
        "key": "bankCode",
        "label": "Bank name",
        "required": true,
        "type": "enum",
        "options": [
          { "value": "120001:02", "label": "9Payment Service Bank" },
          { "value": "801:02", "label": "Abbey Mortgage Bank" }
        ]
      },
      { "key": "bankAccountNumber", "label": "Bank Account Number", "required": true, "type": "string" }
    ],
    "transferType": "manual"
  },
  "payout": {
    "paymentChannel": "crypto",
    "currencyType": "crypto",
    "currencyCode": "POLYGON_USDT",
    "currencyDetails": {
      "network": "POLYGON",
      "asset": "USDT",
      "contractAddress": "0xc2132D05D31c914a87C6611C10748AEb04B58e8F"
    },
    "cashout": {
      "exchangeRate": 1,
      "exchangeRateAfterFees": 1.0001,
      "amountBeforeFees": 100.01,
      "amountAfterFees": 100,
      "amountBeforeFeesUsd": 100.01,
      "amountAfterFeesUsd": 100,
      "chargedFees": [
        { "id": "gas", "type": "flat_amount", "recipient": "blockchain", "amount": 0.01 }
      ],
      "totalChargedFees": 0.01,
      "totalChargedFeesUsd": 0.01,
      "chargedFeesPerRecipient": { "blockchain": 0.01 }
    },
    "fieldsToCreateOrder": [
      { "key": "blockchainWalletAddress", "label": "Your wallet address", "required": true, "type": "string" }
    ]
  }
}
```

{% endcode %}

To receive 100 POLYGON\_USDT the user must deposit 153,128 NGN. Collect the required fields from both legs:

* `phoneNumber`
* `bankCode` (from the enum options)
* `bankAccountNumber`
* `blockchainWalletAddress`
  {% endstep %}

{% step %}

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

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

```json
{
  "quoteId": "68628fa56ff494df5f39faf5",
  "userCountryIsoCode": "NG",
  "userEmail": "someuser@example.com",
  "userIp": "174.3.2.22",
  "deposit": {
    "paymentChannel": "bank",
    "currencyType": "fiat",
    "currencyCode": "NGN",
    "countryIsoCode": "NG"
  },
  "payout": {
    "paymentChannel": "crypto",
    "currencyType": "crypto",
    "currencyCode": "POLYGON_USDT",
    "amount": 100
  },
  "fieldsToCreateOrder": {
    "phoneNumber": "2348012345678",
    "bankCode": "120001:02",
    "bankAccountNumber": "1234567890",
    "blockchainWalletAddress": "0x5b7ae3c6c87f4a3f94b35c77233b13191ebfad20"
  }
}
```

{% endcode %}

{% code title="Example response (transfer instructions excerpt)" overflow="wrap" expandable="true" %}

```json
{
  "quoteUsed": true,
  "order": {
    "_id": "68728fa56ff494df5f39faf5",
    "countryIsoCode": "NG",
    "userId": "57a28fa56ff494df5f39faf5",
    "userEmail": "someuser@example.com",
    "status": "deposit_awaiting",
    "deposit": {
      "transferInstructions": {
        "type": "manual",
        "instructionsText": "Transfer the NGN to the agent's bank account.",
        "warningText": "Only transfer from the bank account you gave us, and include the narration.",
        "transferDetails": [
          { "id": "recipientBankName", "label": "Bank name", "value": "Sterling Bank" },
          { "id": "recipientBankAccountNumber", "label": "Bank account number", "value": "9012345678" },
          { "id": "recipientBankAccountName", "label": "Bank account name", "value": "Fonbnk Agent Ltd" },
          { "id": "amountToSend", "label": "Amount to send", "value": "153128" },
          {
            "id": "bankTransferNarration",
            "label": "Bank transfer narration",
            "description": "TRANSFER WITHOUT NARRATION WILL BE IGNORED BY THE SYSTEM.",
            "value": "shc-pshr4upg8s"
          }
        ],
        "fieldsToConfirmOrder": []
      }
    },
    "payout": { "...": "see Get order for the full object" },
    "expiresAt": "2026-08-20T13:10:10.000Z"
  }
}
```

{% endcode %}

The `recipient*` details are the **agent's** account — where the user sends the money. They are not the `bankAccountNumber` you collected, which is the user's own account and only identifies who is paying.
{% endstep %}

{% step %}

#### The user transfers the exact amount, with the narration

The narration is how the payment is matched. A transfer without it, or from a different account than the one they gave, will not be recognised.
{% endstep %}

{% step %}

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

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

{% code title="Example request" %}

```json
{
  "orderId": "68728fa56ff494df5f39faf5"
}
```

{% endcode %}
{% endstep %}

{% step %}

#### We validate the deposit and send the payout

{% endstep %}

{% step %}

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

Handle the `order-status-change` [webhook](/server-to-server/webhooks.md), or poll [Get order](/server-to-server/api-endpoints/get-order.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/fiat-to-crypto.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.