Off Ramp

Off-ramp

Get off-ramp order

get

Returns a single order by its ID.

Authorizations
Path parameters
idstringRequired
Responses
200
Successful response
application/json
get
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",
  "offerId": "65b8c6b8b188250081f30165",
  "paymentType": "CRYPTO_WALLET",
  "network": "CELO",
  "asset": "CUSD",
  "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

Returns a paginated list of 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

paymentTypestring · enumOptional
  • CRYPTO_WALLET: User will pay with a crypto wallet
  • VIRTUAL_WALLET: Order will be paid from a merchant's virtual wallet
Possible values:
networkstring · enumOptionalPossible values:
assetstring · enumOptionalPossible 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

offrampTypestring · enumOptional

type of the offramp

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
Responseall of
get
GET /api/offramp/orders HTTP/1.1
Host: sandbox-api.fonbnk.com
x-client-id: YOUR_API_KEY
Accept: */*
200

Successful response

{
  "list": [
    {
      "_id": "6603f8fc1c3f3f94d6b30818",
      "offerId": "65b8c6b8b188250081f30165",
      "network": "CELO",
      "asset": "CUSD",
      "paymentType": "CRYPTO_WALLET",
      "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.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"
}

Get best offer

get

Returns the best offer for the provided country, network, asset, amount and off-ramp type.

Authorizations
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:
countrystringRequired

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

typestring · enumRequiredPossible values:
networkstring · enumRequiredPossible values:
assetstring · enumRequiredPossible values:
Responses
200
Successful response
application/json
get
GET /api/offramp/best-offer HTTP/1.1
Host: sandbox-api.fonbnk.com
x-client-id: YOUR_API_KEY
Accept: */*
200

Successful response

{
  "offer": {
    "_id": "65b8c6b8b188250081f30165",
    "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
      }
    },
    "type": "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 off-ramp limits

get

Returns minimum and maximum amount of order in USD and local currency with applied fees.

Authorizations
Query parameters
typestring · enumRequired

offramp type

Possible values:
countrystringRequired

country ISO code

networkstring · enumRequiredPossible values:
assetstring · enumRequiredPossible values:
Responses
200
Successful response
application/json
get
GET /api/offramp/limits 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 countries

get

Returns a list of supported countries and their offramp types

Authorizations
Responses
200
Successful response
application/json
get
GET /api/offramp/countries HTTP/1.1
Host: sandbox-api.fonbnk.com
x-client-id: YOUR_API_KEY
Accept: */*
200

Successful response

[
  {
    "countryIsoCode": "NG",
    "currencyIsoCode": "NGN",
    "name": "Nigeria",
    "offrampTypes": [
      {
        "type": "bank",
        "name": "Bank"
      },
      {
        "type": "airtime",
        "name": "Airtime"
      }
    ]
  },
  {
    "countryIsoCode": "KE",
    "currencyIsoCode": "KES",
    "name": "Kenya",
    "offrampTypes": [
      {
        "type": "mobile_money",
        "name": "M-PESA",
        "carriers": [
          {
            "id": "618e43914f57e07d255ff353",
            "name": "Safaricom Kenya"
          }
        ]
      },
      {
        "type": "airtime",
        "name": "Airtime"
      },
      {
        "type": "paybill",
        "name": "Paybill"
      }
    ]
  },
  {
    "countryIsoCode": "UG",
    "currencyIsoCode": "UGX",
    "name": "Uganda",
    "offrampTypes": [
      {
        "type": "mobile_money",
        "name": "Mobile money"
      },
      {
        "type": "airtime",
        "name": "Airtime"
      }
    ]
  },
  {
    "countryIsoCode": "GH",
    "currencyIsoCode": "GHS",
    "name": "Ghana",
    "offrampTypes": [
      {
        "type": "mobile_money",
        "name": "Mobile money"
      },
      {
        "type": "airtime",
        "name": "Airtime"
      }
    ]
  },
  {
    "countryIsoCode": "ZA",
    "currencyIsoCode": "ZAR",
    "name": "South Africa",
    "offrampTypes": [
      {
        "type": "bank",
        "name": "Bank"
      },
      {
        "type": "airtime",
        "name": "Airtime"
      }
    ]
  },
  {
    "countryIsoCode": "TZ",
    "currencyIsoCode": "TZS",
    "name": "Tanzania",
    "offrampTypes": [
      {
        "type": "mobile_money",
        "name": "Mobile money"
      },
      {
        "type": "airtime",
        "name": "Airtime"
      }
    ]
  }
]

Get supported blockchain assets

get

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

Authorizations
Responses
200
A list of supported wallet networks and their assets
application/json
get
GET /api/offramp/wallets 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"
  }
]

Validate user required fields

post

The get best offer endpoint returns the required fields that need to be provided by a user. This endpoint allows you to validate the fields provided by a user. Endpoint might return a list of user information that can help a user to verify the correctness of the provided information.

Authorizations
Body
offerIdstringRequired

ID of the offer returned from get best offer endpoint

Responses
200
Validation successful
application/json
post
POST /api/offramp/validate-fields HTTP/1.1
Host: sandbox-api.fonbnk.com
x-client-id: YOUR_API_KEY
Content-Type: application/json
Accept: */*
Content-Length: 115

{
  "offerId": "65b8c6b8b188250081f30163",
  "requiredFields": {
    "bankCode": "011:02",
    "buyerBankAccountNumber": "3139586782"
  }
}
200

Validation successful

{
  "details": [
    {
      "label": "Bank account holder name",
      "value": "JOHN SMITH"
    }
  ]
}

Create order

post

Creates an order for a provided user details.

Authorizations
Body
offerIdstringRequired

ID of the offer returned from get best offer endpoint

paymentTypestring · enumRequired
  • CRYPTO_WALLET: User will pay with a crypto wallet
  • VIRTUAL_WALLET: Order will be paid from a merchant's virtual wallet
Possible values:
networkstring · enumRequiredPossible values:
assetstring · enumRequiredPossible values:
addressstringRequired

Address of the wallet from which funds will be sent

currencystring · enumRequiredPossible values:
amountnumberRequired

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

ipstringOptional

IP address of a user

orderParamsstringOptional

OrderParams that need to be associated with an order

Responses
200
Order created successfully
application/json
post
POST /api/offramp/create-order HTTP/1.1
Host: sandbox-api.fonbnk.com
x-client-id: YOUR_API_KEY
Content-Type: application/json
Accept: */*
Content-Length: 279

{
  "offerId": "65b8c4b8b188250081f30165",
  "network": "CELO",
  "asset": "CUSD",
  "amount": 1.02,
  "address": "0x5b7ae3c3c87F4A3F94b35c77233b13191eBFAD20",
  "requiredFields": {
    "bankCode": "011:02",
    "buyerBankAccountNumber": "3134586782"
  },
  "currency": "usd",
  "ip": "192.168.1.1",
  "orderParams": "someParams"
}
200

Order created successfully

{
  "_id": "6603f8fc1c3f3f94d6b30818",
  "offerId": "65b8c6b8b188250081f30165",
  "paymentType": "CRYPTO_WALLET",
  "network": "CELO",
  "asset": "CUSD",
  "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"
}

Confirm order

post

Confirms an order by providing a transaction hash for crypto orders and order ID returned from the create order endpoint.

Authorizations
Body
orderIdstringRequired

ID of the order returned from create order endpoint

hashstringRequired

Transaction hash for crypto orders

Responses
200
Order confirmed successfully
application/json
post
POST /api/offramp/confirm-order HTTP/1.1
Host: sandbox-api.fonbnk.com
x-client-id: YOUR_API_KEY
Content-Type: application/json
Accept: */*
Content-Length: 114

{
  "orderId": "660528663163c4652145aaba",
  "hash": "0xf4c04687dca90a9060861493d7baa8ce761081c44949ec3507c5413304b13ae3"
}
200

Order confirmed successfully

{
  "_id": "6603f8fc1c3f3f94d6b30818",
  "offerId": "65b8c6b8b188250081f30165",
  "paymentType": "CRYPTO_WALLET",
  "network": "CELO",
  "asset": "CUSD",
  "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"
}
PreviousOn RampNextUtil