Off Ramp

Off-ramp

Get best offer

get

https://sandbox-api.fonbnk.comhttps://api.fonbnk.com

/api/offramp/best-offer

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

Authorizations

ClientIdHeaderTimestampHeaderSignatureHeader

x-client-idstringRequired

Your client ID

Query parameters

amountnumberRequired

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

currencystring · enumRequired

Currency of the amount param

Possible values:

countryIsoCodestringRequired

country ISO code, for example KE for Kenya, NG for Nigeria

paymentChannelstring · enumRequired

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

Possible values:

networkstring · enumRequiredPossible values:

assetstring · enumRequiredPossible values:

Responses

200

Successful response

application/json

quoteIdstringOptional

Unique quote id

get

/api/offramp/best-offer

HTTPcURLJavaScriptPython

GET /api/offramp/best-offer?amount=1&currency=local&countryIsoCode=text&paymentChannel=bank&network=AVALANCHE&asset=USDC HTTP/1.1
Host: sandbox-api.fonbnk.com
x-client-id: YOUR_API_KEY
Accept: */*

200

Successful response

{
  "quoteId": "660528663163c4652145aaba",
  "offer": {
    "countryIsoCode": "NG",
    "currencyIsoCode": "NGN",
    "exchangeRate": 1260.2,
    "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
      }
    },
    "paymentChannel": "bank"
  },
  "cashout": {
    "localCurrencyAmount": 6301,
    "usdAmount": 5,
    "feeAmountUsd": 0.12,
    "feeAmountUsdFonbnk": 0.12,
    "feeAmountUsdPartner": 0,
    "feeAmountLocalCurrency": 155,
    "feeAmountLocalCurrencyFonbnk": 155,
    "feeAmountLocalCurrencyPartner": 0,
    "cryptoAmount": 5,
    "feeAmountCrypto": 0.12,
    "feeAmountCryptoFonbnk": 0.12,
    "feeAmountCryptoPartner": 0
  }
}

Get payment channels list

get

https://sandbox-api.fonbnk.comhttps://api.fonbnk.com

/api/offramp/payment-channels

Returns a list of supported countries and their payment channels

Authorizations

ClientIdHeaderTimestampHeaderSignatureHeader

x-client-idstringRequired

Your client ID

Responses

200

Successful response

application/json

countryIsoCodestringOptional

ISO code of the country, e.g. NG for Nigeria, KE for Kenya

currencyIsoCodestringOptional

ISO code of the local currency, e.g. NGN for Nigerian Naira, KES for Kenyan Shilling

namestringOptional

Name of the country, e.g. Nigeria, Kenya

get

/api/offramp/payment-channels

HTTPcURLJavaScriptPython

GET /api/offramp/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",
        "name": "Bank"
      },
      {
        "paymentChannel": "airtime",
        "name": "Airtime"
      }
    ]
  },
  {
    "countryIsoCode": "KE",
    "currencyIsoCode": "KES",
    "name": "Kenya",
    "paymentChannels": [
      {
        "paymentChannel": "mobile_money",
        "name": "M-PESA",
        "carriers": [
          {
            "id": "618e43914f57e07d255ff353",
            "name": "Safaricom Kenya",
            "code": "ke_safaricom"
          }
        ]
      },
      {
        "paymentChannel": "airtime",
        "name": "Airtime"
      },
      {
        "paymentChannel": "paybill",
        "name": "Paybill"
      }
    ]
  },
  {
    "countryIsoCode": "UG",
    "currencyIsoCode": "UGX",
    "name": "Uganda",
    "paymentChannels": [
      {
        "paymentChannel": "mobile_money",
        "name": "Mobile money"
      },
      {
        "paymentChannel": "airtime",
        "name": "Airtime"
      }
    ]
  },
  {
    "countryIsoCode": "GH",
    "currencyIsoCode": "GHS",
    "name": "Ghana",
    "paymentChannels": [
      {
        "paymentChannel": "mobile_money",
        "name": "Mobile money"
      },
      {
        "paymentChannel": "airtime",
        "name": "Airtime"
      }
    ]
  },
  {
    "countryIsoCode": "ZA",
    "currencyIsoCode": "ZAR",
    "name": "South Africa",
    "paymentChannels": [
      {
        "paymentChannel": "bank",
        "name": "Bank"
      },
      {
        "paymentChannel": "airtime",
        "name": "Airtime"
      }
    ]
  },
  {
    "countryIsoCode": "TZ",
    "currencyIsoCode": "TZS",
    "name": "Tanzania",
    "paymentChannels": [
      {
        "paymentChannel": "mobile_money",
        "name": "Mobile money"
      },
      {
        "paymentChannel": "airtime",
        "name": "Airtime"
      }
    ]
  }
]

Get off-ramp limits

get

https://sandbox-api.fonbnk.comhttps://api.fonbnk.com

/api/offramp/limits

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

Authorizations

ClientIdHeaderTimestampHeaderSignatureHeader

x-client-idstringRequired

Your client ID

Query parameters

paymentChannelstring · enumRequired

payment channel type

Possible values:

countryIsoCodestringRequired

country ISO code

networkstring · enumRequiredPossible values:

assetstring · enumRequiredPossible values:

Responses

200

Successful response

application/json

minUsdnumberOptional

maxUsdnumberOptional

minLocalCurrencynumberOptional

maxLocalCurrencynumberOptional

get

/api/offramp/limits

HTTPcURLJavaScriptPython

GET /api/offramp/limits?paymentChannel=bank&countryIsoCode=text&network=AVALANCHE&asset=USDC HTTP/1.1
Host: sandbox-api.fonbnk.com
x-client-id: YOUR_API_KEY
Accept: */*

200

Successful response

{
  "minUsd": 1.02,
  "maxUsd": 100,
  "minLocalCurrency": 1292,
  "maxLocalCurrency": 125921
}

Get supported blockchain assets

get

https://sandbox-api.fonbnk.comhttps://api.fonbnk.com

/api/offramp/assets

Returns a list of supported wallet networks and their assets for crypto wallet orders

Authorizations

ClientIdHeaderTimestampHeaderSignatureHeader

x-client-idstringRequired

Your client ID

Responses

200

A list of supported wallet networks and their assets

application/json

networkstring · enumOptionalPossible values:

assetstring · enumOptionalPossible values:

get

/api/offramp/assets

HTTPcURLJavaScriptPython

GET /api/offramp/assets HTTP/1.1
Host: sandbox-api.fonbnk.com
x-client-id: YOUR_API_KEY
Accept: */*

200

A list of supported wallet networks and their assets

[
  {
    "network": "POLYGON",
    "asset": "USDC"
  },
  {
    "network": "CELO",
    "asset": "USDC"
  },
  {
    "network": "ETHEREUM",
    "asset": "USDC"
  },
  {
    "network": "AVALANCHE",
    "asset": "USDC"
  },
  {
    "network": "CELO",
    "asset": "CUSD"
  },
  {
    "network": "POLYGON",
    "asset": "USDT"
  },
  {
    "network": "AVALANCHE",
    "asset": "USDT"
  },
  {
    "network": "CELO",
    "asset": "USDT"
  },
  {
    "network": "ETHEREUM",
    "asset": "USDT"
  }
]

Get off-ramp order

get

https://sandbox-api.fonbnk.comhttps://api.fonbnk.com

/api/offramp/order/{id}

Returns a single order by its ID.

Authorizations

ClientIdHeaderTimestampHeaderSignatureHeader

x-client-idstringRequired

Your client ID

Path parameters

idstringRequired

ID of the off-ramp order

Responses

200

Successful response

application/json

_idstringOptional

Unique identifier of the off-ramp order

networkstring · enumOptional

Blockchain network of the off-ramp order, e.g. AVALANCHE, POLYGON, CELO, ETHEREUM

Possible values:

assetstring · enumOptional

Blockchain asset of the off-ramp order, e.g. USDC, USDT, CUSD, CKES

Possible values:

exchangeRatenumberOptional

Exchange rate for the off-ramp order

fromAddressstringOptional

User wallet address from which the off-ramp order was initiated

toAddressstringOptional

The wallet address to which the crypto was sent

statusstring · enumOptional

Status of the off-ramp order

Possible values:

createdAtstring · date-timeOptional

Date and time when the off-ramp order was created

expiresAtstring · date-timeOptional

Date and time when the off-ramp order expires if it is not paid in time

hashstringOptional

Transaction hash if available

requiredFieldsobjectOptional

Fields that were provided by the user

countryIsoCodestringOptional

Country ISO code, e.g. NG for Nigeria, KE for Kenya

userPhoneNumberstringOptional

Phone number of the user, should include country code

userEmailstringOptional

Email address of the user

currencyIsoCodestringOptional

Local currency ISO code, e.g. NGN for Nigerian Naira, KES for Kenyan Shilling

orderParamsstringOptional

Value of the orderParams query param during order creation

paymentChannelstring · enumOptional

Type of the payment channel used for the off-ramp order, e.g. bank, mobile_money, airtime

Possible values:

get

/api/offramp/order/{id}

HTTPcURLJavaScriptPython

GET /api/offramp/order/{id} HTTP/1.1
Host: sandbox-api.fonbnk.com
x-client-id: YOUR_API_KEY
Accept: */*

200

Successful response

{
  "_id": "6603f8fc1c3f3f94d6b30818",
  "network": "CELO",
  "asset": "CUSD",
  "paymentChannel": "bank",
  "exchangeRate": 1268.6275,
  "cashout": {
    "localCurrencyAmount": 1294,
    "usdAmount": 1.02,
    "feeAmountUsd": 0.02,
    "feeAmountUsdFonbnk": 0.02,
    "feeAmountUsdPartner": 0,
    "feeAmountLocalCurrency": 26,
    "feeAmountLocalCurrencyFonbnk": 26,
    "feeAmountLocalCurrencyPartner": 0,
    "cryptoAmount": 1.02,
    "feeAmountCrypto": 0.02,
    "feeAmountCryptoFonbnk": 0.02,
    "feeAmountCryptoPartner": 0
  },
  "fromAddress": "0x5b7ae3c6c87F4A3F94b35c77233b13191eBFAD20",
  "toAddress": "0xe9bBDDCF0E8fcD41Bd1345aa5688B565931B0184",
  "status": "offramp_success",
  "createdAt": "2024-03-27T10:46:20.513Z",
  "expiresAt": "2024-03-27T11:46:20.509Z",
  "hash": "0xbda5dd11b17d65249238137f5d542320b66141ac96be3b750804354a6eadfb04",
  "statusHistory": [
    {
      "status": "initiated",
      "changedAt": "2024-03-27T10:46:20.522Z"
    },
    {
      "status": "awaiting_transaction_confirmation",
      "changedAt": "2024-03-27T10:46:31.007Z"
    },
    {
      "status": "transaction_confirmed",
      "changedAt": "2024-03-27T10:46:43.357Z"
    },
    {
      "status": "offramp_pending",
      "changedAt": "2024-03-27T10:46:44.568Z"
    },
    {
      "status": "offramp_success",
      "changedAt": "2024-03-27T10:50:02.649Z"
    }
  ],
  "requiredFields": {
    "bankCode": "011:02",
    "buyerBankAccountNumber": "3159586782",
    "phoneNumber": "2347000000007"
  },
  "countryIsoCode": "NG",
  "currencyIsoCode": "NGN",
  "offerRequiredFields": [
    {
      "label": "Phone number",
      "type": "phone",
      "value": "2347000000007"
    },
    {
      "label": "Bank name",
      "type": "enum",
      "value": "First Bank of Nigeria"
    },
    {
      "label": "Bank account Number",
      "type": "string",
      "value": "3179586682"
    }
  ],
  "orderParams": "43"
}

Get off-ramp orders

get

https://sandbox-api.fonbnk.comhttps://api.fonbnk.com

/api/offramp/orders

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

Authorizations

ClientIdHeaderTimestampHeaderSignatureHeader

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:

assetstring · enumOptional

asset of orders

Possible values:

fromAddressstringOptional

address of a user wallet

userPhoneNumberstringOptional

phone number of the client, should include country code

userEmailstringOptional

email of the client

hashstringOptional

hash of the user transaction

countryIsoCodestringOptional

country ISO code, e.g. NG

paymentChannelstring · enumOptional

type of the payment channel

Possible values:

orderParamsstringOptional

value of the orderParams query param during order creation

statusstring · enumOptional

• initiated: The offramp order has been initiated
• awaiting_transaction_confirmation: User sent the transaction hash and system is awaiting confirmation
• transaction_confirmed: User transaction has been confirmed
• transaction_failed: User transaction has failed
• offramp_success: The offramp transaction has been successful
• offramp_pending: The offramp transaction is pending
• offramp_failed: The offramp transaction has failed
• offramp_retry: The offramp transaction is being retried
• refunding: The offramp transaction is being refunded
• refunded: The offramp transaction has been refunded
• refund_failed: The offramp transaction refund has failed
• expired: The offramp order has expired
• cancelled: The offramp order has been cancelled by the user
• validating_transaction: The offramp transaction is being validated
• transaction_invalid: The offramp transaction is invalid

Possible values:

Responses

200

Successful response

application/json

get

/api/offramp/orders

HTTPcURLJavaScriptPython

GET /api/offramp/orders?limit=1 HTTP/1.1
Host: sandbox-api.fonbnk.com
x-client-id: YOUR_API_KEY
Accept: */*

200

Successful response

{
  "list": [
    {
      "_id": "6603f8fc1c3f3f94d6b30818",
      "network": "CELO",
      "asset": "CUSD",
      "exchangeRate": 1268.6275,
      "paymentChannel": "bank",
      "cashout": {
        "localCurrencyAmount": 1294,
        "usdAmount": 1.02,
        "feeAmountUsd": 0.02,
        "feeAmountUsdFonbnk": 0.02,
        "feeAmountUsdPartner": 0,
        "feeAmountLocalCurrency": 26,
        "feeAmountLocalCurrencyFonbnk": 26,
        "feeAmountLocalCurrencyPartner": 0,
        "cryptoAmount": 1.02,
        "feeAmountCrypto": 0.02,
        "feeAmountCryptoFonbnk": 0.02,
        "feeAmountCryptoPartner": 0
      },
      "fromAddress": "0x5b7ae3c6c87F4A3F94b35c77233b13191eBFAD20",
      "toAddress": "0xe9bBDDCF0E8fcD41Bd1345aa5688B565931B0184",
      "status": "offramp_success",
      "createdAt": "2024-03-27T10:46:20.513Z",
      "expiresAt": "2024-03-27T11:46:20.509Z",
      "hash": "0xbda5dd11b17d65249238137f5d542320b66141ac96be3b750804354a6eadfb04",
      "statusHistory": [
        {
          "status": "initiated",
          "changedAt": "2024-03-27T10:46:20.509Z"
        },
        {
          "status": "initiated",
          "changedAt": "2024-03-27T10:46:20.522Z"
        },
        {
          "status": "awaiting_transaction_confirmation",
          "changedAt": "2024-03-27T10:46:31.007Z"
        },
        {
          "status": "transaction_confirmed",
          "changedAt": "2024-03-27T10:46:43.357Z"
        },
        {
          "status": "offramp_pending",
          "changedAt": "2024-03-27T10:46:44.568Z"
        },
        {
          "status": "offramp_success",
          "changedAt": "2024-03-27T10:50:02.649Z"
        }
      ],
      "requiredFields": {
        "bankCode": "011:02",
        "buyerBankAccountNumber": "3159586782",
        "phoneNumber": "2347000000007"
      },
      "countryIsoCode": "NG",
      "currencyIsoCode": "NGN",
      "offerRequiredFields": [
        {
          "label": "Phone number",
          "type": "phone",
          "value": "2347000000007"
        },
        {
          "label": "Bank name",
          "type": "enum",
          "value": "First Bank of Nigeria"
        },
        {
          "label": "Bank account Number",
          "type": "string",
          "value": "3179586682"
        }
      ],
      "orderParams": "43"
    }
  ],
  "nextCursor": "646c7e3ce2597a00921e2c53"
}