Fiat -> Crypto

Let’s do an NGN (fiat) deposit to POLYGON_USDT (crypto) payout. First, call Get available currencies and assume you receive:

Example response

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

We see NGN supports deposit via bank/airtime/mobile money, and payout via bank/mobile money. POLYGON_USDT supports both deposit and payout. So we can do Fiat → Crypto (NGN → POLYGON_USDT).

Next, call Get order limits with the next query params:

• depositPaymentChannel: "bank"

• depositCurrencyType: "fiat"

• depositCurrencyCode: "NGN"

• depositCountryIsoCode: "NG"

• payoutPaymentChannel: "crypto"

• payoutCurrencyType: "crypto"

• payoutCurrencyCode: "POLYGON_USDT"

Example response

{
  "deposit": {
    "min": 1556,
    "max": 311184,
    "minUsd": 1,
    "maxUsd": 200
  },
  "payout": {
    "min": 1,
    "max": 200,
    "minUsd": 1,
    "maxUsd": 200
  }
}

Assume the user wants to receive 100 POLYGON_USDT. Validate their tier using the KYC requirements flow.

Then Create quote:

Example request

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

Example response

{
  "quoteId": "68628fa56ff494df5f39faf5",
  "quoteExpiresAt": "2024-10-10T10:10:10.000Z",
  "deposit": {
    "paymentChannel": "bank",
    "currencyType": "fiat",
    "currencyCode": "NGN",
    "currencyDetails": {
      "countryIsoCode": "NG",
      "countryName": "Nigeria",
      "countryCode": "234",
      "currencySymbol": "₦",
      "currencyIcon": "https://cdn.example.com/flags/ng.png"
    },
    "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": "platform_fee",
          "type": "percentage",
          "recipient": "platform",
          "amount": 3063
        }
      ],
      "chargedFeesUsd": [
        {
          "id": "provider_fee",
          "type": "flat_amount",
          "recipient": "provider",
          "amount": 0.033333
        },
        {
          "id": "platform_fee",
          "type": "percentage",
          "recipient": "platform",
          "amount": 2.042
        }
      ],
      "totalChargedFees": 3113,
      "totalChargedFeesUsd": 2.075333,
      "chargedFeesPerRecipient": {
        "provider": 50,
        "platform": 3063
      },
      "chargedFeesPerRecipientUsd": {
        "provider": 0.033333,
        "platform": 2.042
      },
      "feeSettings": [
        {
          "id": "provider_fee",
          "recipient": "provider",
          "type": "flat_amount",
          "value": 50,
          "min": 0,
          "max": "Infinity"
        },
        {
          "id": "platform_fee",
          "recipient": "platform",
          "type": "percentage",
          "value": 2,
          "min": 0,
          "max": "Infinity"
        }
      ]
    },
    "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.001,
      "amountBeforeFees": 100.01,
      "amountAfterFees": 100,
      "amountBeforeFeesUsd": 100.01,
      "amountAfterFeesUsd": 100,
      "feeSettings": [
        {
          "id": "gas_fee",
          "recipient": "blockchain",
          "type": "flat_amount",
          "value": 0.01,
          "min": 0,
          "max": "Infinity"
        }
      ],
      "chargedFees": [
        {
          "id": "gas_fee",
          "type": "flat_amount",
          "recipient": "blockchain",
          "amount": 0.01
        }
      ],
      "chargedFeesUsd": [
        {
          "id": "gas_fee",
          "type": "flat_amount",
          "recipient": "blockchain",
          "amount": 0.01
        }
      ],
      "totalChargedFees": 0.01,
      "totalChargedFeesUsd": 0.01,
      "chargedFeesPerRecipient": {
        "blockchain": 0.01
      },
      "chargedFeesPerRecipientUsd": {
        "blockchain": 0.01
      }
    },
    "fieldsToCreateOrder": [
      {
        "key": "blockchainWalletAddress",
        "label": "Your wallet address",
        "required": true,
        "type": "string"
      }
    ]
  }
}

To receive 100 POLYGON_USDT, user must deposit 153128 NGN. Collect these fields:

• phoneNumber

• bankCode (from enum options)

• bankAccountNumber

• blockchainWalletAddress

Create the order via Create order:

Example request

{
  "quoteId": "68628fa56ff494df5f39faf5",
  "userEmail": "[email protected]",
  "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": "0x5b7ae3c6c83F4A3F94b35c77233b13191eBGAD21"
  }
}

Example response

const response = {
  "order": {
    "_id": "68728fa56ff494df5f39faf5",
    "countryIsoCode": "NG",
    "userId": "57a28fa56ff494df5f39faf5",
    "userEmail": "[email protected]",
    "status": "deposit_awaiting",
    "deposit": {
      //...
      transferInstructions: {
        type: "manual",
        instructionsText: "Please use the following bank details to make a transfer...",
        warningText: "Make sure to include the reference code in your transfer.",
        transferDetails: [
          {id: "recipientBankName", label: "Bank Name", value: "9Payment Service Bank"},
          {id: "recipientBankAccountNumber", label: "Account Number", value: "1234567890"},
          {id: "recipientBankAccountName", label: "Account Name", value: "Example Company Ltd"},
          {id: "amountToSend", label: "Amount to Send", value: "153128"},
          {
            id: "bankTransferNarration",
            label: "Transfer Narration / Reference",
            value: "ORDER-5F8D0D55B54764421B7156C5",
            description: "Use this as the transfer reference."
          }
        ],
        fieldsToConfirmOrder: [],
      }
    },
    "payout": {
      //...
    }
  }
}

A user makes the transfer with the exact amount and reference. Then call Confirm order if no extra fields are required:

Example request

{
  "orderId": "68728fa56ff494df5f39faf5"
}

The system validates the deposit and processes payout. Use Get order to track status until "payout_successful".