On Ramp | v1.5 | Fonbnk Docs

Get best offer

get

/api/onramp/best-offer

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

Authorizations

x-client-idstringRequired

Your client ID

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

/api/onramp/best-offer

GET /api/onramp/best-offer?network=POLYGON&asset=USDC&currency=local&amount=1&countryIsoCode=text&paymentChannel=bank 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

/api/onramp/payment-channels

Returns a list of supported countries and their payment channels

Authorizations

x-client-idstringRequired

Your client ID

Responses

200

Successful response

application/json

get

/api/onramp/payment-channels

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

/api/onramp/limits

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

Authorizations

x-client-idstringRequired

Your client ID

Query parameters

networkstring · enumRequiredPossible values:

assetstring · enumOptionalPossible values:

countryIsoCodestringRequired

paymentChannelstring · enumRequiredPossible values:

carrierCodestringOptional

Responses

200

Successful response

application/json

get

/api/onramp/limits

GET /api/onramp/limits?network=POLYGON&countryIsoCode=text&paymentChannel=bank 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

/api/onramp/assets

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

Authorizations

x-client-idstringRequired

Your client ID

Responses

200

Successful response

application/json

get

/api/onramp/assets

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

/api/onramp/order

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

Authorizations

x-client-idstringRequired

Your client ID

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

/api/onramp/order

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

/api/onramp/orders

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

Authorizations

x-client-idstringRequired

Your client ID

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

get

/api/onramp/orders

GET /api/onramp/orders?limit=1 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

/api/onramp/order/create

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

Authorizations

x-client-idstringRequired

Your client ID

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

/api/onramp/order/create

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

/api/onramp/order/otp

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

Authorizations

x-client-idstringRequired

Your client ID

Body

orderIdstringRequired

ID of the order to verify OTP for

otpstringRequired

OTP code received by the user

post

/api/onramp/order/otp

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

/api/onramp/order/confirm

Confirms an onramp order

Authorizations

Body

orderIdstringRequired

The ID of the order to confirm

Example: 507f1f77bcf86cd799439011

Responses

200

Order confirmed successfully

application/json

post

/api/onramp/order/confirm

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

/api/onramp/order/reject

Rejects an onramp order

Authorizations

Body

orderIdstringRequired

The ID of the order to reject

Example: 507f1f77bcf86cd799439011

Responses

200

Order rejected successfully

application/json

post

/api/onramp/order/reject

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

hashtagGet best offer

hashtagGet payment channels

hashtagGet limits

hashtagGet list of supported assets

hashtagGet order

hashtagGet orders

hashtagCreate order

hashtagVerify OTP for order

hashtagConfirm onramp order

hashtagReject onramp order

Get best offer

Get payment channels

Get limits

Get list of supported assets

Get order

Get orders

Create order

Verify OTP for order

Confirm onramp order

Reject onramp order