On Ramp

On-ramp

Get best offer

get

Returns the best offer for the provided country, network, asset, amount and payment channel.

Authorizations
Query parameters
networkstring · enumRequired

blockchain network of the order

Possible values:
assetstring · enumRequired

asset of the order

Possible values:
currencystring · enumRequired

Currency of the amount param

Possible values:
amountnumberRequired

Amount of local currency user wants to pay or amount of crypto user wants to receive depending on the currency param value

countryIsoCodestringRequired

country ISO code, e.g. NG, KE etc.

paymentChannelstring · enumRequired

type of the payment channel user wants to use, e.g. bank, mobile_money, airtime to pay local currency

Possible values:
carrierCodestringOptional

carrier code if applicable, e.g. for mobile_money or airtime orders

Responses
200

Successful response

application/json
get
GET /api/onramp/best-offer HTTP/1.1
Host: sandbox-api.fonbnk.com
x-client-id: YOUR_API_KEY
Accept: */*
200

Successful response

{
  "quoteId": "651e764399a4b360c7eb0178",
  "offer": {
    "countryIsoCode": "NG",
    "currencyIsoCode": "NGN",
    "exchangeRate": 1,
    "cryptoExchangeRate": 1,
    "paymentChannel": "bank",
    "requiredFields": {
      "phoneNumber": {
        "type": "phone",
        "label": "Phone number",
        "required": true
      },
      "bankCode": {
        "required": true,
        "type": "enum",
        "label": "Bank name",
        "options": [
          {
            "value": "120001:02",
            "label": "9Payment Service Bank"
          },
          {
            "value": "801:02",
            "label": "Abbey Mortgage Bank"
          }
        ]
      },
      "buyerBankAccountNumber": {
        "type": "string",
        "label": "Bank account Number",
        "required": true
      }
    }
  },
  "cashout": {
    "localCurrencyAmount": 2100,
    "totalAmountUsd": 2.15,
    "withdrawAmountUsd": 2.1,
    "totalAmountCrypto": 2.15,
    "withdrawAmountCrypto": 2.1,
    "feePercent": 2.5,
    "feePercentFonbnk": 1.5,
    "feePercentPartner": 1,
    "feeAmountUsd": 0.05,
    "feeAmountUsdFonbnk": 0.03,
    "feeAmountUsdPartner": 0.02,
    "feeAmountLocalCurrency": 50,
    "feeAmountLocalCurrencyFonbnk": 30,
    "feeAmountLocalCurrencyPartner": 20,
    "feeAmountCrypto": 0.05,
    "feeAmountCryptoFonbnk": 0.03,
    "feeAmountCryptoPartner": 0.02,
    "gasAmountUsd": 0,
    "gasAmountLocalCurrency": 0
  }
}

Get payment channels

get

Returns a list of supported countries and their payment channels

Authorizations
Responses
200

Successful response

application/json
get
GET /api/onramp/payment-channels HTTP/1.1
Host: sandbox-api.fonbnk.com
x-client-id: YOUR_API_KEY
Accept: */*
200

Successful response

[
  {
    "countryIsoCode": "NG",
    "currencyIsoCode": "NGN",
    "name": "Nigeria",
    "paymentChannels": [
      {
        "paymentChannel": "bank",
        "description": "Bank transfer",
        "requiresCarrier": false,
        "carriers": []
      }
    ]
  },
  {
    "countryIsoCode": "KE",
    "currencyIsoCode": "KES",
    "name": "Kenya",
    "paymentChannels": [
      {
        "paymentChannel": "airtime",
        "description": "Airtime",
        "requiresCarrier": true,
        "carriers": [
          {
            "id": "618e43914f57e07d255ff353",
            "name": "Safaricom Kenya",
            "code": "ke_safaricom"
          }
        ]
      },
      {
        "paymentChannel": "mobile_money",
        "description": "M-PESA",
        "requiresCarrier": true,
        "carriers": [
          {
            "id": "618e43914f57e07d255ff353",
            "name": "Safaricom Kenya",
            "code": "ke_safaricom"
          }
        ]
      }
    ]
  }
]

Get limits

get

Returns minimum and maximum amount of order in crypto and local currency and applied fees for specific payment channel, country, network and asset.

Authorizations
Query parameters
networkstring · enumRequiredPossible values:
assetstring · enumOptionalPossible values:
countryIsoCodestringRequired
paymentChannelstring · enumRequiredPossible values:
carrierCodestringOptional
Responses
200

Successful response

application/json
get
GET /api/onramp/limits HTTP/1.1
Host: sandbox-api.fonbnk.com
x-client-id: YOUR_API_KEY
Accept: */*
200

Successful response

{
  "minCrypto": 1,
  "maxCrypto": 200,
  "minLocalCurrency": 100,
  "maxLocalCurrency": 20000,
  "minUsd": 1,
  "maxUsd": 200
}

Get list of supported assets

get

Returns a list of supported blockchain assets for the on-ramp orders

Authorizations
Responses
200

Successful response

application/json
get
GET /api/onramp/assets HTTP/1.1
Host: sandbox-api.fonbnk.com
x-client-id: YOUR_API_KEY
Accept: */*
200

Successful response

[
  {
    "network": "POLYGON",
    "asset": "USDC"
  },
  {
    "network": "CELO",
    "asset": "USDC"
  },
  {
    "network": "ETHEREUM",
    "asset": "USDC"
  },
  {
    "network": "BASE",
    "asset": "USDC"
  },
  {
    "network": "AVALANCHE",
    "asset": "USDC"
  },
  {
    "network": "POLYGON",
    "asset": "USDC_E"
  },
  {
    "network": "SOLANA",
    "asset": "USDC"
  },
  {
    "network": "OPTIMISM",
    "asset": "USDC"
  },
  {
    "network": "CELO",
    "asset": "CUSD"
  },
  {
    "network": "POLYGON",
    "asset": "USDT"
  },
  {
    "network": "AVALANCHE",
    "asset": "USDT"
  },
  {
    "network": "CELO",
    "asset": "USDT"
  },
  {
    "network": "ETHEREUM",
    "asset": "USDT"
  },
  {
    "network": "TON",
    "asset": "USDT"
  },
  {
    "network": "STELLAR",
    "asset": "USDC"
  },
  {
    "network": "SOLANA",
    "asset": "USDT"
  },
  {
    "network": "OPTIMISM",
    "asset": "USDT"
  },
  {
    "network": "CELO",
    "asset": "CKES"
  },
  {
    "network": "LISK",
    "asset": "USDT"
  },
  {
    "network": "BNB",
    "asset": "USDT"
  },
  {
    "network": "BNB",
    "asset": "USDC"
  },
  {
    "network": "ARBITRUM",
    "asset": "USDT"
  },
  {
    "network": "ARBITRUM",
    "asset": "USDC"
  }
]

Get order

get

Returns a single pay widget order by its ID or orderParams query parameter.

Authorizations
Query parameters
orderIdstringOptional

id of the order which you could receive via a webhook or iframe events

orderParamsstringOptional

Value which you provided in the orderParams parameter of the pay widget URL

Responses
200

Successful response

application/json
get
GET /api/onramp/order HTTP/1.1
Host: sandbox-api.fonbnk.com
x-client-id: YOUR_API_KEY
Accept: */*
200

Successful response

{
  "_id": "651e764399a4b360c7eb0178",
  "orderId": "651e764399a4b360c7eb0178",
  "status": "seller_confirmed",
  "phoneNumber": "380962669394",
  "paymentChannel": "bank",
  "email": "[email protected]",
  "currencyIsoCode": "NGN",
  "countryIsoCode": "NG",
  "network": "SOLANA",
  "asset": "USDC",
  "address": "53L9ahwHcNnD4F11TqNHQgVUa75WgaCL2WGeiKiK2gCc",
  "feePercent": 2.5,
  "feePercentFonbnk": 1.5,
  "feePercentPartner": 1,
  "date": "2023-10-05T08:39:31.691Z",
  "orderParams": "{id: \"651e764}",
  "localCurrencyAmount": 2100,
  "amount": 2.1,
  "amountCrypto": 2.1,
  "hash": "F19TfyGxBgebZt4q8h5bgf9Luabpypm3zSSzWR5ZUp8CKGNvL2r58zqGvWXvKftppiWKszV11jNQtsMUoFppmyb",
  "feeAmountUsd": 0.05,
  "feeAmountLocalCurrency": 50,
  "feeAmountUsdFonbnk": 0.03,
  "feeAmountLocalCurrencyFonbnk": 30,
  "feeAmountUsdPartner": 0.02,
  "feeAmountLocalCurrencyPartner": 20,
  "gasAmountUsd": 0,
  "gasAmountLocalCurrency": 0,
  "resumeUrl": "https://pay.fonbnk.com/swap-status?orderId=651e764399a4b360c7eb0178"
}

Get orders

get

Returns a paginated list of pay widget orders. Filters can be applied to the list by providing query parameters.

Authorizations
Query parameters
cursorstringOptional

this parameter should be provided in order to get a next page from the pagination, it should be taken from "nextCursor" response value

limitintegerRequired

number from 1 to 100, describes how many records should be in each pagination page

networkstring · enumOptional

blockchain network of orders

Possible values:
addressstringOptional
userPhoneNumberstringOptional

phone number of the client, should include country code

userEmailstringOptional

email of the client

paymentChannelstring · enumOptional

type of the payment channel

Possible values:
buySwapStatusstring · enumOptional
  • initiated: The buy swap has been initiated
  • expired: The buy swap has expired
  • buyer_confirmed: The buyer has confirmed the buy swap
  • seller_confirmation_pending: The agent is yet to confirm the buy swap
  • seller_confirmation_failed: The agent has failed to confirm the buy swap
  • seller_confirmed: The agent has confirmed the buy swap
  • seller_rejected: The agent has rejected the buy swap
Possible values:
withdrawalStatusstring · enumOptional

status of a crypto transfer

Possible values:
Responses
200

Successful response

application/json
Responseall of
get
GET /api/onramp/orders HTTP/1.1
Host: sandbox-api.fonbnk.com
x-client-id: YOUR_API_KEY
Accept: */*
200

Successful response

{
  "nextCursor": "651e764399a4b360c7eb0178",
  "list": [
    {
      "_id": "651e764399a4b360c7eb0178",
      "orderId": "651e764399a4b360c7eb0178",
      "status": "seller_confirmed",
      "phoneNumber": "380962669394",
      "email": "[email protected]",
      "currencyIsoCode": "NGN",
      "countryIsoCode": "NG",
      "network": "SOLANA",
      "asset": "USDC",
      "address": "53L9ahwHcNnD4F11TqNHQgVUa75WgaCL2WGeiKiK2gCc",
      "feePercent": 2.5,
      "feePercentFonbnk": 1.5,
      "feePercentPartner": 1,
      "date": "2023-10-05T08:39:31.691Z",
      "orderParams": "{id: \"651e764}",
      "localCurrencyAmount": 2100,
      "amount": 2.1,
      "amountCrypto": 2.1,
      "hash": "F19TfyGxBgebZt4q8h5bgf9Luabpypm3zSSzWR5ZUp8CKGNvL2r58zqGvWXvKftppiWKszV11jNQtsMUoFppmyb",
      "feeAmountUsd": 0.05,
      "feeAmountLocalCurrency": 50,
      "feeAmountUsdFonbnk": 0.03,
      "feeAmountLocalCurrencyFonbnk": 30,
      "feeAmountUsdPartner": 0.02,
      "feeAmountLocalCurrencyPartner": 20,
      "gasAmountUsd": 0,
      "gasAmountLocalCurrency": 0,
      "resumeUrl": "https://pay.fonbnk.com/swap-status?orderId=651e764399a4b360c7eb0178"
    }
  ]
}

Create order

post

Creates a new on-ramp order using a quote ID from the best offer endpoint

Authorizations
Body
quoteIdstringRequired

Quote ID from the best offer endpoint

networkstring · enumRequiredPossible values:
amountnumberRequired

Amount based on the currency parameter

currencystring · enumRequiredPossible values:
assetstring · enumRequiredPossible values:
addressstringOptional

Wallet address to receive the crypto

emailstring · emailRequired

User email address

orderParamsstringOptional

Optional parameter for order tracking

userIpstring · ipv4Required

User's IP address

redirectUrlstring · uriOptional

URL to redirect the user after completion of the transfer, applicable only for orders with transferInstructions.type = "redirect"

Responses
200

Order created successfully

application/json
post
POST /api/onramp/order/create HTTP/1.1
Host: sandbox-api.fonbnk.com
x-client-id: YOUR_API_KEY
Content-Type: application/json
Accept: */*
Content-Length: 292

{
  "quoteId": "651e764399a4b360c7eb0178",
  "network": "SOLANA",
  "amount": 2.1,
  "currency": "crypto",
  "asset": "USDC",
  "address": "53L9ahwHcNnD4F11TqNHQgVUa75WgaCL2WGeiKiK2gCc",
  "email": "[email protected]",
  "orderParams": "user-order-123",
  "userIp": "100.102.120.240",
  "extraFields": {
    "phoneNumber": "234567890123"
  }
}
200

Order created successfully

{
  "_id": "651e764399a4b360c7eb0178",
  "orderId": "651e764399a4b360c7eb0178",
  "status": "seller_confirmed",
  "phoneNumber": "380962669394",
  "paymentChannel": "bank",
  "email": "[email protected]",
  "currencyIsoCode": "NGN",
  "countryIsoCode": "NG",
  "network": "SOLANA",
  "asset": "USDC",
  "address": "53L9ahwHcNnD4F11TqNHQgVUa75WgaCL2WGeiKiK2gCc",
  "feePercent": 2.5,
  "feePercentFonbnk": 1.5,
  "feePercentPartner": 1,
  "date": "2023-10-05T08:39:31.691Z",
  "orderParams": "{id: \"651e764}",
  "localCurrencyAmount": 2100,
  "amount": 2.1,
  "amountCrypto": 2.1,
  "hash": "F19TfyGxBgebZt4q8h5bgf9Luabpypm3zSSzWR5ZUp8CKGNvL2r58zqGvWXvKftppiWKszV11jNQtsMUoFppmyb",
  "feeAmountUsd": 0.05,
  "feeAmountLocalCurrency": 50,
  "feeAmountUsdFonbnk": 0.03,
  "feeAmountLocalCurrencyFonbnk": 30,
  "feeAmountUsdPartner": 0.02,
  "feeAmountLocalCurrencyPartner": 20,
  "gasAmountUsd": 0,
  "gasAmountLocalCurrency": 0,
  "resumeUrl": "https://pay.fonbnk.com/swap-status?orderId=651e764399a4b360c7eb0178"
}

Verify OTP for order

post

Verifies OTP code for an on-ramp order that requires OTP authentication.

Authorizations
Body
orderIdstringRequired

ID of the order to verify OTP for

otpstringRequired

OTP code received by the user

post
POST /api/onramp/order/otp HTTP/1.1
Host: sandbox-api.fonbnk.com
x-client-id: YOUR_API_KEY
Content-Type: application/json
Accept: */*
Content-Length: 53

{
  "orderId": "651e764399a4b360c7eb0178",
  "otp": "123456"
}

Confirm onramp order

post

Confirms an onramp order

Body
orderIdstringRequired

The ID of the order to confirm

Example: 507f1f77bcf86cd799439011
Responses
200

Order confirmed successfully

application/json
post
POST /api/onramp/order/confirm HTTP/1.1
Host: sandbox-api.fonbnk.com
Content-Type: application/json
Accept: */*
Content-Length: 38

{
  "orderId": "507f1f77bcf86cd799439011"
}
200

Order confirmed successfully

{
  "_id": "651e764399a4b360c7eb0178",
  "orderId": "651e764399a4b360c7eb0178",
  "status": "seller_confirmed",
  "phoneNumber": "380962669394",
  "paymentChannel": "bank",
  "email": "[email protected]",
  "currencyIsoCode": "NGN",
  "countryIsoCode": "NG",
  "network": "SOLANA",
  "asset": "USDC",
  "address": "53L9ahwHcNnD4F11TqNHQgVUa75WgaCL2WGeiKiK2gCc",
  "feePercent": 2.5,
  "feePercentFonbnk": 1.5,
  "feePercentPartner": 1,
  "date": "2023-10-05T08:39:31.691Z",
  "orderParams": "{id: \"651e764}",
  "localCurrencyAmount": 2100,
  "amount": 2.1,
  "amountCrypto": 2.1,
  "hash": "F19TfyGxBgebZt4q8h5bgf9Luabpypm3zSSzWR5ZUp8CKGNvL2r58zqGvWXvKftppiWKszV11jNQtsMUoFppmyb",
  "feeAmountUsd": 0.05,
  "feeAmountLocalCurrency": 50,
  "feeAmountUsdFonbnk": 0.03,
  "feeAmountLocalCurrencyFonbnk": 30,
  "feeAmountUsdPartner": 0.02,
  "feeAmountLocalCurrencyPartner": 20,
  "gasAmountUsd": 0,
  "gasAmountLocalCurrency": 0,
  "resumeUrl": "https://pay.fonbnk.com/swap-status?orderId=651e764399a4b360c7eb0178"
}

Reject onramp order

post

Rejects an onramp order

Body
orderIdstringRequired

The ID of the order to reject

Example: 507f1f77bcf86cd799439011
Responses
200

Order rejected successfully

application/json
post
POST /api/onramp/order/reject HTTP/1.1
Host: sandbox-api.fonbnk.com
Content-Type: application/json
Accept: */*
Content-Length: 38

{
  "orderId": "507f1f77bcf86cd799439011"
}
200

Order rejected successfully

{
  "_id": "651e764399a4b360c7eb0178",
  "orderId": "651e764399a4b360c7eb0178",
  "status": "seller_confirmed",
  "phoneNumber": "380962669394",
  "paymentChannel": "bank",
  "email": "[email protected]",
  "currencyIsoCode": "NGN",
  "countryIsoCode": "NG",
  "network": "SOLANA",
  "asset": "USDC",
  "address": "53L9ahwHcNnD4F11TqNHQgVUa75WgaCL2WGeiKiK2gCc",
  "feePercent": 2.5,
  "feePercentFonbnk": 1.5,
  "feePercentPartner": 1,
  "date": "2023-10-05T08:39:31.691Z",
  "orderParams": "{id: \"651e764}",
  "localCurrencyAmount": 2100,
  "amount": 2.1,
  "amountCrypto": 2.1,
  "hash": "F19TfyGxBgebZt4q8h5bgf9Luabpypm3zSSzWR5ZUp8CKGNvL2r58zqGvWXvKftppiWKszV11jNQtsMUoFppmyb",
  "feeAmountUsd": 0.05,
  "feeAmountLocalCurrency": 50,
  "feeAmountUsdFonbnk": 0.03,
  "feeAmountLocalCurrencyFonbnk": 30,
  "feeAmountUsdPartner": 0.02,
  "feeAmountLocalCurrencyPartner": 20,
  "gasAmountUsd": 0,
  "gasAmountLocalCurrency": 0,
  "resumeUrl": "https://pay.fonbnk.com/swap-status?orderId=651e764399a4b360c7eb0178"
}
PreviousEndpointsNextOff Ramp