# On Ramp

On-ramp

## Get best offer

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

```json
{"openapi":"3.1.0","info":{"title":"Fonbnk On-ramp API","version":"1.0.0"},"tags":[{"name":"on-ramp","description":"On-ramp"}],"servers":[{"url":"https://sandbox-api.fonbnk.com","description":"Development server"},{"url":"https://api.fonbnk.com","description":"Production server"}],"security":[{"ClientIdHeader":[]},{"TimestampHeader":[]},{"SignatureHeader":[]}],"components":{"securitySchemes":{"ClientIdHeader":{"type":"apiKey","in":"header","name":"x-client-id","description":"Your client ID"},"TimestampHeader":{"type":"apiKey","in":"header","name":"x-timestamp","description":"The Unix timestamp of the request signature"},"SignatureHeader":{"type":"apiKey","in":"header","name":"x-signature","description":"HMAC-SHA256 signature generated using your secret"}},"schemas":{"OnRampNetwork":{"type":"string","enum":["POLYGON","ETHEREUM","STELLAR","AVALANCHE","SOLANA","CELO","BASE","TON","TRON","LISK","ARBITRUM","OPTIMISM","BNB"]},"OnRampAsset":{"type":"string","enum":["USDC","USDT","CUSD","CKES","CGHS","USDE"]},"WidgetAmountCurrency":{"type":"string","enum":["local","crypto"]},"OnRampPaymentChannel":{"type":"string","enum":["bank","mobile_money","airtime"]},"OnRampBestOfferResponse":{"type":"object","properties":{"quoteId":{"type":"string","description":"Unique quote id"},"offer":{"type":"object","properties":{"paymentChannel":{"$ref":"#/components/schemas/OnRampPaymentChannel","description":"Type of the payment channel, e.g. bank, mobile_money, airtime"},"countryIsoCode":{"type":"string","description":"Country ISO code, e.g. NG for Nigeria, KE for Kenya"},"currencyIsoCode":{"type":"string","description":"Local currency ISO code, e.g. NGN for Nigerian Naira, KES for Kenyan Shilling"},"exchangeRate":{"type":"number","description":"Exchange rate for the order"},"cryptoExchangeRate":{"type":"number","description":"Exchange rate for the crypto amount"},"requiredFields":{"type":"object","description":"Data required to submit the order","additionalProperties":{"type":"object","properties":{"type":{"$ref":"#/components/schemas/RequiredFieldType"},"label":{"type":"string"},"required":{"type":"boolean"},"options":{"type":"array","items":{"type":"object","properties":{"value":{"type":"string"},"label":{"type":"string"}}}}}}}}},"cashout":{"type":"object","properties":{"localCurrencyAmount":{"type":"number","description":"Amount in local currency user must to pay"},"totalAmountUsd":{"type":"number","description":"Total amount of local currency in USD user must to pay"},"totalAmountCrypto":{"type":"number","description":"Total amount of local currency in crypto user must to pay"},"withdrawAmountUsd":{"type":"number","description":"Amount in USD user will receive after the order is completed"},"withdrawAmountCrypto":{"type":"number","description":"Amount in crypto user will receive after the order is completed"},"feePercent":{"type":"number","description":"Total fee percent (fonbnk fee + partner fee)"},"feeAmountUsd":{"type":"number","description":"Total fee amount in USD"},"feeAmountLocalCurrency":{"type":"number","description":"Total fee amount in local currency"},"feeAmountCrypto":{"type":"number","description":"Total fee amount in crypto"},"feePercentFonbnk":{"type":"number","description":"Fonbnk fee percent"},"feeAmountUsdFonbnk":{"type":"number","description":"Fonbnk fee amount in USD"},"feeAmountLocalCurrencyFonbnk":{"type":"number","description":"Fonbnk fee amount in local currency"},"feeAmountCryptoFonbnk":{"type":"number","description":"Fonbnk fee amount in crypto"},"feePercentPartner":{"type":"number","description":"Partner fee percent"},"feeAmountUsdPartner":{"type":"number","description":"Partner fee amount in USD"},"feeAmountLocalCurrencyPartner":{"type":"number","description":"Partner fee amount in local currency"},"feeAmountCryptoPartner":{"type":"number","description":"Partner fee amount in crypto"},"gasAmountUsd":{"type":"number","description":"Gas fee amount in USD"},"gasAmountLocalCurrency":{"type":"number","description":"Gas fee amount in local currency"},"gasAmountCrypto":{"type":"number","description":"Gas fee amount in crypto"}}}}},"RequiredFieldType":{"type":"string","enum":["number","string","date","boolean","email","enum"]}}},"paths":{"/api/onramp/best-offer":{"get":{"tags":["on-ramp"],"summary":"Get best offer","description":"Returns the best offer for the provided country, network, asset, amount and payment channel.","operationId":"getOnrampBestOffer","parameters":[{"name":"network","in":"query","required":true,"description":"blockchain network of the order","schema":{"$ref":"#/components/schemas/OnRampNetwork"}},{"name":"asset","in":"query","required":true,"description":"asset of the order","schema":{"$ref":"#/components/schemas/OnRampAsset"}},{"name":"currency","in":"query","required":true,"description":"Currency of the amount param","schema":{"$ref":"#/components/schemas/WidgetAmountCurrency"}},{"name":"amount","in":"query","required":true,"description":"Amount of local currency user wants to pay or amount of crypto user wants to receive depending on the currency param value","schema":{"type":"number"}},{"name":"countryIsoCode","in":"query","required":true,"description":"country ISO code, e.g. NG, KE etc.","schema":{"type":"string"}},{"name":"paymentChannel","in":"query","required":true,"description":"type of the payment channel user wants to use, e.g. bank, mobile_money, airtime to pay local currency","schema":{"$ref":"#/components/schemas/OnRampPaymentChannel"}},{"name":"carrierCode","in":"query","required":false,"description":"carrier code if applicable, e.g. for mobile_money or airtime orders","schema":{"type":"string"}}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/OnRampBestOfferResponse"}}}}}}}}}
```

## Get payment channels

> Returns a list of supported countries and their payment channels

```json
{"openapi":"3.1.0","info":{"title":"Fonbnk On-ramp API","version":"1.0.0"},"tags":[{"name":"on-ramp","description":"On-ramp"}],"servers":[{"url":"https://sandbox-api.fonbnk.com","description":"Development server"},{"url":"https://api.fonbnk.com","description":"Production server"}],"security":[{"ClientIdHeader":[]},{"TimestampHeader":[]},{"SignatureHeader":[]}],"components":{"securitySchemes":{"ClientIdHeader":{"type":"apiKey","in":"header","name":"x-client-id","description":"Your client ID"},"TimestampHeader":{"type":"apiKey","in":"header","name":"x-timestamp","description":"The Unix timestamp of the request signature"},"SignatureHeader":{"type":"apiKey","in":"header","name":"x-signature","description":"HMAC-SHA256 signature generated using your secret"}},"schemas":{"OnRampPaymentChannelListResponse":{"type":"array","items":{"type":"object","properties":{"countryIsoCode":{"type":"string","description":"ISO code of the country, e.g. NG for Nigeria, KE for Kenya"},"currencyIsoCode":{"type":"string","description":"ISO code of the local currency, e.g. NGN for Nigerian Naira, KES for Kenyan Shilling"},"name":{"type":"string","description":"Name of the country, e.g. Nigeria, Kenya"},"paymentChannels":{"type":"array","description":"List of payment channels available for the country","items":{"type":"object","properties":{"paymentChannel":{"type":"string","description":"Type of the payment channel, e.g. bank, mobile_money, airtime"},"description":{"type":"string","description":"Description of the payment channel"},"requiresCarrier":{"type":"boolean","description":"Indicates if the payment channel requires a carrier ID"},"carriers":{"type":"array","description":"List of carriers available for the payment channel","items":{"type":"object","properties":{"id":{"type":"string","description":"Unique identifier of the carrier"},"name":{"type":"string","description":"Name of the carrier, e.g. Safaricom, MTN"},"code":{"type":"string","description":"Code of the carrier, e.g. ng_mtn, ke_safaricom"}}}}}}}}}}}},"paths":{"/api/onramp/payment-channels":{"get":{"tags":["on-ramp"],"summary":"Get payment channels","description":"Returns a list of supported countries and their payment channels","operationId":"getOnrampPaymentChannels","responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/OnRampPaymentChannelListResponse"}}}}}}}}}
```

## Get limits

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

```json
{"openapi":"3.1.0","info":{"title":"Fonbnk On-ramp API","version":"1.0.0"},"tags":[{"name":"on-ramp","description":"On-ramp"}],"servers":[{"url":"https://sandbox-api.fonbnk.com","description":"Development server"},{"url":"https://api.fonbnk.com","description":"Production server"}],"security":[{"ClientIdHeader":[]},{"TimestampHeader":[]},{"SignatureHeader":[]}],"components":{"securitySchemes":{"ClientIdHeader":{"type":"apiKey","in":"header","name":"x-client-id","description":"Your client ID"},"TimestampHeader":{"type":"apiKey","in":"header","name":"x-timestamp","description":"The Unix timestamp of the request signature"},"SignatureHeader":{"type":"apiKey","in":"header","name":"x-signature","description":"HMAC-SHA256 signature generated using your secret"}},"schemas":{"OnRampNetwork":{"type":"string","enum":["POLYGON","ETHEREUM","STELLAR","AVALANCHE","SOLANA","CELO","BASE","TON","TRON","LISK","ARBITRUM","OPTIMISM","BNB"]},"OnRampAsset":{"type":"string","enum":["USDC","USDT","CUSD","CKES","CGHS","USDE"]},"OnRampPaymentChannel":{"type":"string","enum":["bank","mobile_money","airtime"]},"OnRampLimitsResponse":{"type":"object","properties":{"minUsd":{"type":"number","description":"Minimum amount in USD for the order"},"maxUsd":{"type":"number","description":"Maximum amount in USD for the order"},"minLocalCurrency":{"type":"number","description":"Minimum amount in local currency for the order"},"maxLocalCurrency":{"type":"number","description":"Maximum amount in local currency for the order"},"minCrypto":{"type":"number","description":"Minimum amount in crypto for the order"},"maxCrypto":{"type":"number","description":"Maximum amount in crypto for the order"}}}}},"paths":{"/api/onramp/limits":{"get":{"tags":["on-ramp"],"summary":"Get limits","description":"Returns minimum and maximum amount of order in crypto and local currency and applied fees for specific payment channel, country, network and asset.","operationId":"getOnrampLimits","parameters":[{"name":"network","in":"query","required":true,"schema":{"$ref":"#/components/schemas/OnRampNetwork"}},{"name":"asset","in":"query","required":false,"schema":{"$ref":"#/components/schemas/OnRampAsset"}},{"name":"countryIsoCode","in":"query","required":true,"schema":{"type":"string"}},{"name":"paymentChannel","in":"query","required":true,"schema":{"$ref":"#/components/schemas/OnRampPaymentChannel"}},{"name":"carrierCode","in":"query","required":false,"schema":{"type":"string"}}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/OnRampLimitsResponse"}}}}}}}}}
```

## Get list of supported assets

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

```json
{"openapi":"3.1.0","info":{"title":"Fonbnk On-ramp API","version":"1.0.0"},"tags":[{"name":"on-ramp","description":"On-ramp"}],"servers":[{"url":"https://sandbox-api.fonbnk.com","description":"Development server"},{"url":"https://api.fonbnk.com","description":"Production server"}],"security":[{"ClientIdHeader":[]},{"TimestampHeader":[]},{"SignatureHeader":[]}],"components":{"securitySchemes":{"ClientIdHeader":{"type":"apiKey","in":"header","name":"x-client-id","description":"Your client ID"},"TimestampHeader":{"type":"apiKey","in":"header","name":"x-timestamp","description":"The Unix timestamp of the request signature"},"SignatureHeader":{"type":"apiKey","in":"header","name":"x-signature","description":"HMAC-SHA256 signature generated using your secret"}},"schemas":{"OnRampNetwork":{"type":"string","enum":["POLYGON","ETHEREUM","STELLAR","AVALANCHE","SOLANA","CELO","BASE","TON","TRON","LISK","ARBITRUM","OPTIMISM","BNB"]},"OnRampAsset":{"type":"string","enum":["USDC","USDT","CUSD","CKES","CGHS","USDE"]}}},"paths":{"/api/onramp/assets":{"get":{"tags":["on-ramp"],"summary":"Get list of supported assets","description":"Returns a list of supported blockchain assets for the on-ramp orders","operationId":"getOnrampAssets","responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"array","items":{"type":"object","properties":{"network":{"$ref":"#/components/schemas/OnRampNetwork"},"asset":{"$ref":"#/components/schemas/OnRampAsset"}}}}}}}}}}}}
```

## Get order

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

```json
{"openapi":"3.1.0","info":{"title":"Fonbnk On-ramp API","version":"1.0.0"},"tags":[{"name":"on-ramp","description":"On-ramp"}],"servers":[{"url":"https://sandbox-api.fonbnk.com","description":"Development server"},{"url":"https://api.fonbnk.com","description":"Production server"}],"security":[{"ClientIdHeader":[]},{"TimestampHeader":[]},{"SignatureHeader":[]}],"components":{"securitySchemes":{"ClientIdHeader":{"type":"apiKey","in":"header","name":"x-client-id","description":"Your client ID"},"TimestampHeader":{"type":"apiKey","in":"header","name":"x-timestamp","description":"The Unix timestamp of the request signature"},"SignatureHeader":{"type":"apiKey","in":"header","name":"x-signature","description":"HMAC-SHA256 signature generated using your secret"}},"schemas":{"OnRampOrder":{"type":"object","properties":{"_id":{"type":"string","description":"Order ID"},"status":{"$ref":"#/components/schemas/OnRampOrderStatus"},"date":{"type":"string","format":"date-time","description":"Date of order creation"},"orderId":{"type":"string","description":"Order ID"},"phoneNumber":{"type":"string","description":"User phone number, should include country code"},"email":{"type":"string","description":"User email address"},"localCurrencyAmount":{"type":"number","description":"Amount in local currency"},"currencyIsoCode":{"type":"string","description":"Local currency ISO code, e.g. NGN, KES"},"countryIsoCode":{"type":"string","description":"Country ISO code, e.g. NG"},"paymentChannel":{"$ref":"#/components/schemas/OnRampPaymentChannel","description":"Payment channel used for the order, e.g. bank, mobile_money, airtime"},"amount":{"type":"number","description":"Amount in USD"},"amountCrypto":{"type":"number","description":"Amount in crypto"},"network":{"$ref":"#/components/schemas/OnRampNetwork","description":"Blockchain network of the order, e.g. POLYGON, ETHEREUM, STELLAR"},"asset":{"$ref":"#/components/schemas/OnRampAsset","description":"Blockchain asset of the order, e.g. USDC, USDT, CUSD"},"address":{"type":"string","description":"User wallet address"},"memo":{"type":"string","description":"Memo for the Stellar, TON and other networks transactions that support it"},"hash":{"type":"string","description":"Transaction hash if available"},"orderParams":{"type":"string","description":"Value of the orderParams query param during order creation"},"resumeUrl":{"type":"string","description":"URL to resume the order in the pay widget"},"carrierId":{"type":"string","description":"Carrier ID if applicable, e.g. for mobile money orders"},"feePercent":{"type":"number","description":"total fee percent (fonbnk fee + partner fee)"},"feePercentFonbnk":{"type":"number","description":"fonbnk fee percent"},"feePercentPartner":{"type":"number","description":"partner fee percent"},"feeAmountUsd":{"type":"number","description":"Total fee amount in USD"},"feeAmountLocalCurrency":{"type":"number","description":"Total fee amount in local currency"},"feeAmountUsdFonbnk":{"type":"number","description":"Fonbnk fee amount in USD"},"feeAmountLocalCurrencyFonbnk":{"type":"number","description":"Fonbnk fee amount in local currency"},"feeAmountUsdPartner":{"type":"number","description":"Partner fee amount in USD"},"feeAmountLocalCurrencyPartner":{"type":"number","description":"Partner fee amount in local currency"},"gasAmountUsd":{"type":"number","description":"Gas fee amount in USD"},"gasAmountLocalCurrency":{"type":"number","description":"Gas fee amount in local currency"},"transferInstructions":{"type":"object","properties":{"type":{"type":"string","description":"Type of action required to complete the order","enum":["manual","redirect","stk_push","otp_stk_push","ussd"]},"ussdCode":{"type":"string","description":"USSD code a user needs to dial to complete the order, present only if type is \"ussd\". May include \"{pin}\" placeholder for user PIN, e.g. \"*123*{pin}#\" in this case it should be replaced with their PIN"},"paymentUrl":{"type":"string","description":"URL to redirect the user to complete the payment, present only if type is \"redirect\""},"instructionsText":{"type":"string","description":"Text with instructions for the user to complete the order"},"warningText":{"type":"string","description":"Warning text for the user"},"transferDetails":{"type":"object","properties":{"key":{"type":"object","properties":{"label":{"type":"string","description":"Label for the transfer detail"},"description":{"type":"string","description":"Description of the transfer detail"},"value":{"type":"string","description":"Value of the transfer detail, e.g. account number, phone number, etc."}}}}}}}}},"OnRampOrderStatus":{"type":"string","enum":["swap_initiated","swap_expired","swap_buyer_rejected","swap_buyer_confirmed","swap_seller_rejected","swap_seller_confirmed","pending","complete","failed"],"description":"- swap_initiated: user has created an order\n- swap_expired: an order has expired\n- swap_buyer_rejected: user has rejected an order\n- swap_buyer_confirmed: user has confirmed an order\n- swap_seller_rejected: agent has rejected an order, happens when agent don't receive a payment\n- swap_seller_confirmed: agent has confirmed an order\n- pending: crypto transaction is pending\n- complete: crypto transaction is complete\n- failed: crypto transaction has failed"},"OnRampPaymentChannel":{"type":"string","enum":["bank","mobile_money","airtime"]},"OnRampNetwork":{"type":"string","enum":["POLYGON","ETHEREUM","STELLAR","AVALANCHE","SOLANA","CELO","BASE","TON","TRON","LISK","ARBITRUM","OPTIMISM","BNB"]},"OnRampAsset":{"type":"string","enum":["USDC","USDT","CUSD","CKES","CGHS","USDE"]}}},"paths":{"/api/onramp/order":{"get":{"tags":["on-ramp"],"summary":"Get order","description":"Returns a single pay widget order by its ID or orderParams query parameter.","operationId":"getOnrampOrderById","parameters":[{"name":"orderId","in":"query","description":"id of the order which you could receive via a webhook or iframe events","required":false,"schema":{"type":"string"}},{"name":"orderParams","in":"query","required":false,"description":"Value which you provided in the orderParams parameter of the pay widget URL","schema":{"type":"string"}}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/OnRampOrder"}}}}}}}}}
```

## Get orders

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

```json
{"openapi":"3.1.0","info":{"title":"Fonbnk On-ramp API","version":"1.0.0"},"tags":[{"name":"on-ramp","description":"On-ramp"}],"servers":[{"url":"https://sandbox-api.fonbnk.com","description":"Development server"},{"url":"https://api.fonbnk.com","description":"Production server"}],"security":[{"ClientIdHeader":[]},{"TimestampHeader":[]},{"SignatureHeader":[]}],"components":{"securitySchemes":{"ClientIdHeader":{"type":"apiKey","in":"header","name":"x-client-id","description":"Your client ID"},"TimestampHeader":{"type":"apiKey","in":"header","name":"x-timestamp","description":"The Unix timestamp of the request signature"},"SignatureHeader":{"type":"apiKey","in":"header","name":"x-signature","description":"HMAC-SHA256 signature generated using your secret"}},"schemas":{"OnRampNetwork":{"type":"string","enum":["POLYGON","ETHEREUM","STELLAR","AVALANCHE","SOLANA","CELO","BASE","TON","TRON","LISK","ARBITRUM","OPTIMISM","BNB"]},"OnRampPaymentChannel":{"type":"string","enum":["bank","mobile_money","airtime"]},"BuySwapStatus":{"type":"string","enum":["initiated","expired","buyer_confirmed","seller_confirmation_pending","seller_confirmation_failed","seller_confirmed","seller_rejected"],"description":"- initiated: The buy swap has been initiated\n- expired: The buy swap has expired\n- buyer_confirmed: The buyer has confirmed the buy swap\n- seller_confirmation_pending: The agent is yet to confirm the buy swap\n- seller_confirmation_failed: The agent has failed to confirm the buy swap\n- seller_confirmed: The agent has confirmed the buy swap\n- seller_rejected: The agent has rejected the buy swap"},"WithdrawalStatus":{"type":"string","enum":["pending","complete","failed"]},"PaginatedOnrampOrders":{"allOf":[{"$ref":"#/components/schemas/Paginated"},{"type":"object","properties":{"list":{"type":"array","items":{"$ref":"#/components/schemas/OnRampOrder"}}}}]},"Paginated":{"type":"object","properties":{"nextCursor":{"type":"string"}}},"OnRampOrder":{"type":"object","properties":{"_id":{"type":"string","description":"Order ID"},"status":{"$ref":"#/components/schemas/OnRampOrderStatus"},"date":{"type":"string","format":"date-time","description":"Date of order creation"},"orderId":{"type":"string","description":"Order ID"},"phoneNumber":{"type":"string","description":"User phone number, should include country code"},"email":{"type":"string","description":"User email address"},"localCurrencyAmount":{"type":"number","description":"Amount in local currency"},"currencyIsoCode":{"type":"string","description":"Local currency ISO code, e.g. NGN, KES"},"countryIsoCode":{"type":"string","description":"Country ISO code, e.g. NG"},"paymentChannel":{"$ref":"#/components/schemas/OnRampPaymentChannel","description":"Payment channel used for the order, e.g. bank, mobile_money, airtime"},"amount":{"type":"number","description":"Amount in USD"},"amountCrypto":{"type":"number","description":"Amount in crypto"},"network":{"$ref":"#/components/schemas/OnRampNetwork","description":"Blockchain network of the order, e.g. POLYGON, ETHEREUM, STELLAR"},"asset":{"$ref":"#/components/schemas/OnRampAsset","description":"Blockchain asset of the order, e.g. USDC, USDT, CUSD"},"address":{"type":"string","description":"User wallet address"},"memo":{"type":"string","description":"Memo for the Stellar, TON and other networks transactions that support it"},"hash":{"type":"string","description":"Transaction hash if available"},"orderParams":{"type":"string","description":"Value of the orderParams query param during order creation"},"resumeUrl":{"type":"string","description":"URL to resume the order in the pay widget"},"carrierId":{"type":"string","description":"Carrier ID if applicable, e.g. for mobile money orders"},"feePercent":{"type":"number","description":"total fee percent (fonbnk fee + partner fee)"},"feePercentFonbnk":{"type":"number","description":"fonbnk fee percent"},"feePercentPartner":{"type":"number","description":"partner fee percent"},"feeAmountUsd":{"type":"number","description":"Total fee amount in USD"},"feeAmountLocalCurrency":{"type":"number","description":"Total fee amount in local currency"},"feeAmountUsdFonbnk":{"type":"number","description":"Fonbnk fee amount in USD"},"feeAmountLocalCurrencyFonbnk":{"type":"number","description":"Fonbnk fee amount in local currency"},"feeAmountUsdPartner":{"type":"number","description":"Partner fee amount in USD"},"feeAmountLocalCurrencyPartner":{"type":"number","description":"Partner fee amount in local currency"},"gasAmountUsd":{"type":"number","description":"Gas fee amount in USD"},"gasAmountLocalCurrency":{"type":"number","description":"Gas fee amount in local currency"},"transferInstructions":{"type":"object","properties":{"type":{"type":"string","description":"Type of action required to complete the order","enum":["manual","redirect","stk_push","otp_stk_push","ussd"]},"ussdCode":{"type":"string","description":"USSD code a user needs to dial to complete the order, present only if type is \"ussd\". May include \"{pin}\" placeholder for user PIN, e.g. \"*123*{pin}#\" in this case it should be replaced with their PIN"},"paymentUrl":{"type":"string","description":"URL to redirect the user to complete the payment, present only if type is \"redirect\""},"instructionsText":{"type":"string","description":"Text with instructions for the user to complete the order"},"warningText":{"type":"string","description":"Warning text for the user"},"transferDetails":{"type":"object","properties":{"key":{"type":"object","properties":{"label":{"type":"string","description":"Label for the transfer detail"},"description":{"type":"string","description":"Description of the transfer detail"},"value":{"type":"string","description":"Value of the transfer detail, e.g. account number, phone number, etc."}}}}}}}}},"OnRampOrderStatus":{"type":"string","enum":["swap_initiated","swap_expired","swap_buyer_rejected","swap_buyer_confirmed","swap_seller_rejected","swap_seller_confirmed","pending","complete","failed"],"description":"- swap_initiated: user has created an order\n- swap_expired: an order has expired\n- swap_buyer_rejected: user has rejected an order\n- swap_buyer_confirmed: user has confirmed an order\n- swap_seller_rejected: agent has rejected an order, happens when agent don't receive a payment\n- swap_seller_confirmed: agent has confirmed an order\n- pending: crypto transaction is pending\n- complete: crypto transaction is complete\n- failed: crypto transaction has failed"},"OnRampAsset":{"type":"string","enum":["USDC","USDT","CUSD","CKES","CGHS","USDE"]}}},"paths":{"/api/onramp/orders":{"get":{"tags":["on-ramp"],"summary":"Get orders","description":"Returns a paginated list of pay widget orders. Filters can be applied to the list by providing query parameters.","operationId":"getOnrampOrders","parameters":[{"name":"cursor","in":"query","description":"this parameter should be provided in order to get a next page from the pagination, it should be taken from \"nextCursor\" response value","required":false,"schema":{"type":"string"}},{"name":"limit","in":"query","description":"number from 1 to 100, describes how many records should be in each pagination page","required":true,"schema":{"type":"integer"}},{"name":"network","in":"query","description":"blockchain network of orders","required":false,"schema":{"$ref":"#/components/schemas/OnRampNetwork"}},{"name":"address","in":"query","required":false,"schema":{"type":"string"}},{"name":"userPhoneNumber","in":"query","description":"phone number of the client, should include country code","required":false,"schema":{"type":"string"}},{"name":"userEmail","in":"query","description":"email of the client","required":false,"schema":{"type":"string"}},{"name":"paymentChannel","in":"query","required":false,"description":"type of the payment channel","schema":{"$ref":"#/components/schemas/OnRampPaymentChannel"}},{"name":"buySwapStatus","in":"query","description":"status of a buy swap","required":false,"schema":{"$ref":"#/components/schemas/BuySwapStatus"}},{"name":"withdrawalStatus","in":"query","description":"status of a crypto transfer","required":false,"schema":{"$ref":"#/components/schemas/WithdrawalStatus"}}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PaginatedOnrampOrders"}}}}}}}}}
```

## Create order

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

```json
{"openapi":"3.1.0","info":{"title":"Fonbnk On-ramp API","version":"1.0.0"},"tags":[{"name":"on-ramp","description":"On-ramp"}],"servers":[{"url":"https://sandbox-api.fonbnk.com","description":"Development server"},{"url":"https://api.fonbnk.com","description":"Production server"}],"security":[{"ClientIdHeader":[]},{"TimestampHeader":[]},{"SignatureHeader":[]}],"components":{"securitySchemes":{"ClientIdHeader":{"type":"apiKey","in":"header","name":"x-client-id","description":"Your client ID"},"TimestampHeader":{"type":"apiKey","in":"header","name":"x-timestamp","description":"The Unix timestamp of the request signature"},"SignatureHeader":{"type":"apiKey","in":"header","name":"x-signature","description":"HMAC-SHA256 signature generated using your secret"}},"schemas":{"OnRampNetwork":{"type":"string","enum":["POLYGON","ETHEREUM","STELLAR","AVALANCHE","SOLANA","CELO","BASE","TON","TRON","LISK","ARBITRUM","OPTIMISM","BNB"]},"WidgetAmountCurrency":{"type":"string","enum":["local","crypto"]},"OnRampAsset":{"type":"string","enum":["USDC","USDT","CUSD","CKES","CGHS","USDE"]},"OnRampOrder":{"type":"object","properties":{"_id":{"type":"string","description":"Order ID"},"status":{"$ref":"#/components/schemas/OnRampOrderStatus"},"date":{"type":"string","format":"date-time","description":"Date of order creation"},"orderId":{"type":"string","description":"Order ID"},"phoneNumber":{"type":"string","description":"User phone number, should include country code"},"email":{"type":"string","description":"User email address"},"localCurrencyAmount":{"type":"number","description":"Amount in local currency"},"currencyIsoCode":{"type":"string","description":"Local currency ISO code, e.g. NGN, KES"},"countryIsoCode":{"type":"string","description":"Country ISO code, e.g. NG"},"paymentChannel":{"$ref":"#/components/schemas/OnRampPaymentChannel","description":"Payment channel used for the order, e.g. bank, mobile_money, airtime"},"amount":{"type":"number","description":"Amount in USD"},"amountCrypto":{"type":"number","description":"Amount in crypto"},"network":{"$ref":"#/components/schemas/OnRampNetwork","description":"Blockchain network of the order, e.g. POLYGON, ETHEREUM, STELLAR"},"asset":{"$ref":"#/components/schemas/OnRampAsset","description":"Blockchain asset of the order, e.g. USDC, USDT, CUSD"},"address":{"type":"string","description":"User wallet address"},"memo":{"type":"string","description":"Memo for the Stellar, TON and other networks transactions that support it"},"hash":{"type":"string","description":"Transaction hash if available"},"orderParams":{"type":"string","description":"Value of the orderParams query param during order creation"},"resumeUrl":{"type":"string","description":"URL to resume the order in the pay widget"},"carrierId":{"type":"string","description":"Carrier ID if applicable, e.g. for mobile money orders"},"feePercent":{"type":"number","description":"total fee percent (fonbnk fee + partner fee)"},"feePercentFonbnk":{"type":"number","description":"fonbnk fee percent"},"feePercentPartner":{"type":"number","description":"partner fee percent"},"feeAmountUsd":{"type":"number","description":"Total fee amount in USD"},"feeAmountLocalCurrency":{"type":"number","description":"Total fee amount in local currency"},"feeAmountUsdFonbnk":{"type":"number","description":"Fonbnk fee amount in USD"},"feeAmountLocalCurrencyFonbnk":{"type":"number","description":"Fonbnk fee amount in local currency"},"feeAmountUsdPartner":{"type":"number","description":"Partner fee amount in USD"},"feeAmountLocalCurrencyPartner":{"type":"number","description":"Partner fee amount in local currency"},"gasAmountUsd":{"type":"number","description":"Gas fee amount in USD"},"gasAmountLocalCurrency":{"type":"number","description":"Gas fee amount in local currency"},"transferInstructions":{"type":"object","properties":{"type":{"type":"string","description":"Type of action required to complete the order","enum":["manual","redirect","stk_push","otp_stk_push","ussd"]},"ussdCode":{"type":"string","description":"USSD code a user needs to dial to complete the order, present only if type is \"ussd\". May include \"{pin}\" placeholder for user PIN, e.g. \"*123*{pin}#\" in this case it should be replaced with their PIN"},"paymentUrl":{"type":"string","description":"URL to redirect the user to complete the payment, present only if type is \"redirect\""},"instructionsText":{"type":"string","description":"Text with instructions for the user to complete the order"},"warningText":{"type":"string","description":"Warning text for the user"},"transferDetails":{"type":"object","properties":{"key":{"type":"object","properties":{"label":{"type":"string","description":"Label for the transfer detail"},"description":{"type":"string","description":"Description of the transfer detail"},"value":{"type":"string","description":"Value of the transfer detail, e.g. account number, phone number, etc."}}}}}}}}},"OnRampOrderStatus":{"type":"string","enum":["swap_initiated","swap_expired","swap_buyer_rejected","swap_buyer_confirmed","swap_seller_rejected","swap_seller_confirmed","pending","complete","failed"],"description":"- swap_initiated: user has created an order\n- swap_expired: an order has expired\n- swap_buyer_rejected: user has rejected an order\n- swap_buyer_confirmed: user has confirmed an order\n- swap_seller_rejected: agent has rejected an order, happens when agent don't receive a payment\n- swap_seller_confirmed: agent has confirmed an order\n- pending: crypto transaction is pending\n- complete: crypto transaction is complete\n- failed: crypto transaction has failed"},"OnRampPaymentChannel":{"type":"string","enum":["bank","mobile_money","airtime"]}}},"paths":{"/api/onramp/order/create":{"post":{"tags":["on-ramp"],"summary":"Create order","description":"Creates a new on-ramp order using a quote ID from the best offer endpoint","operationId":"createOnrampOrder","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["quoteId","network","amount","currency","asset","email","userIp"],"properties":{"quoteId":{"type":"string","description":"Quote ID from the best offer endpoint"},"network":{"$ref":"#/components/schemas/OnRampNetwork"},"amount":{"type":"number","description":"Amount based on the currency parameter"},"currency":{"$ref":"#/components/schemas/WidgetAmountCurrency"},"asset":{"$ref":"#/components/schemas/OnRampAsset"},"address":{"type":"string","description":"Wallet address to receive the crypto"},"email":{"type":"string","format":"email","description":"User email address"},"orderParams":{"type":"string","description":"Optional parameter for order tracking"},"extraFields":{"type":"object","description":"Additional fields required for the order","additionalProperties":true},"userIp":{"type":"string","format":"ipv4","description":"User's IP address"},"redirectUrl":{"type":"string","format":"uri","description":"URL to redirect the user after completion of the transfer, applicable only for orders with transferInstructions.type = \"redirect\""}}}}}},"responses":{"200":{"description":"Order created successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/OnRampOrder"}}}}}}}}}
```

## Verify OTP for order

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

```json
{"openapi":"3.1.0","info":{"title":"Fonbnk On-ramp API","version":"1.0.0"},"tags":[{"name":"on-ramp","description":"On-ramp"}],"servers":[{"url":"https://sandbox-api.fonbnk.com","description":"Development server"},{"url":"https://api.fonbnk.com","description":"Production server"}],"security":[{"ClientIdHeader":[]},{"TimestampHeader":[]},{"SignatureHeader":[]}],"components":{"securitySchemes":{"ClientIdHeader":{"type":"apiKey","in":"header","name":"x-client-id","description":"Your client ID"},"TimestampHeader":{"type":"apiKey","in":"header","name":"x-timestamp","description":"The Unix timestamp of the request signature"},"SignatureHeader":{"type":"apiKey","in":"header","name":"x-signature","description":"HMAC-SHA256 signature generated using your secret"}}},"paths":{"/api/onramp/order/otp":{"post":{"tags":["on-ramp"],"summary":"Verify OTP for order","description":"Verifies OTP code for an on-ramp order that requires OTP authentication.","operationId":"verifyOnrampOrderOtp","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["orderId","otp"],"properties":{"orderId":{"type":"string","description":"ID of the order to verify OTP for"},"otp":{"type":"string","description":"OTP code received by the user"}}}}}}}}}}
```

## Confirm onramp order

> Confirms an onramp order

```json
{"openapi":"3.1.0","info":{"title":"Fonbnk On-ramp API","version":"1.0.0"},"tags":[{"name":"on-ramp","description":"On-ramp"}],"servers":[{"url":"https://sandbox-api.fonbnk.com","description":"Development server"},{"url":"https://api.fonbnk.com","description":"Production server"}],"security":[{"ApiKeyAuth":[]}],"components":{"securitySchemes":{},"schemas":{"OnRampOrder":{"type":"object","properties":{"_id":{"type":"string","description":"Order ID"},"status":{"$ref":"#/components/schemas/OnRampOrderStatus"},"date":{"type":"string","format":"date-time","description":"Date of order creation"},"orderId":{"type":"string","description":"Order ID"},"phoneNumber":{"type":"string","description":"User phone number, should include country code"},"email":{"type":"string","description":"User email address"},"localCurrencyAmount":{"type":"number","description":"Amount in local currency"},"currencyIsoCode":{"type":"string","description":"Local currency ISO code, e.g. NGN, KES"},"countryIsoCode":{"type":"string","description":"Country ISO code, e.g. NG"},"paymentChannel":{"$ref":"#/components/schemas/OnRampPaymentChannel","description":"Payment channel used for the order, e.g. bank, mobile_money, airtime"},"amount":{"type":"number","description":"Amount in USD"},"amountCrypto":{"type":"number","description":"Amount in crypto"},"network":{"$ref":"#/components/schemas/OnRampNetwork","description":"Blockchain network of the order, e.g. POLYGON, ETHEREUM, STELLAR"},"asset":{"$ref":"#/components/schemas/OnRampAsset","description":"Blockchain asset of the order, e.g. USDC, USDT, CUSD"},"address":{"type":"string","description":"User wallet address"},"memo":{"type":"string","description":"Memo for the Stellar, TON and other networks transactions that support it"},"hash":{"type":"string","description":"Transaction hash if available"},"orderParams":{"type":"string","description":"Value of the orderParams query param during order creation"},"resumeUrl":{"type":"string","description":"URL to resume the order in the pay widget"},"carrierId":{"type":"string","description":"Carrier ID if applicable, e.g. for mobile money orders"},"feePercent":{"type":"number","description":"total fee percent (fonbnk fee + partner fee)"},"feePercentFonbnk":{"type":"number","description":"fonbnk fee percent"},"feePercentPartner":{"type":"number","description":"partner fee percent"},"feeAmountUsd":{"type":"number","description":"Total fee amount in USD"},"feeAmountLocalCurrency":{"type":"number","description":"Total fee amount in local currency"},"feeAmountUsdFonbnk":{"type":"number","description":"Fonbnk fee amount in USD"},"feeAmountLocalCurrencyFonbnk":{"type":"number","description":"Fonbnk fee amount in local currency"},"feeAmountUsdPartner":{"type":"number","description":"Partner fee amount in USD"},"feeAmountLocalCurrencyPartner":{"type":"number","description":"Partner fee amount in local currency"},"gasAmountUsd":{"type":"number","description":"Gas fee amount in USD"},"gasAmountLocalCurrency":{"type":"number","description":"Gas fee amount in local currency"},"transferInstructions":{"type":"object","properties":{"type":{"type":"string","description":"Type of action required to complete the order","enum":["manual","redirect","stk_push","otp_stk_push","ussd"]},"ussdCode":{"type":"string","description":"USSD code a user needs to dial to complete the order, present only if type is \"ussd\". May include \"{pin}\" placeholder for user PIN, e.g. \"*123*{pin}#\" in this case it should be replaced with their PIN"},"paymentUrl":{"type":"string","description":"URL to redirect the user to complete the payment, present only if type is \"redirect\""},"instructionsText":{"type":"string","description":"Text with instructions for the user to complete the order"},"warningText":{"type":"string","description":"Warning text for the user"},"transferDetails":{"type":"object","properties":{"key":{"type":"object","properties":{"label":{"type":"string","description":"Label for the transfer detail"},"description":{"type":"string","description":"Description of the transfer detail"},"value":{"type":"string","description":"Value of the transfer detail, e.g. account number, phone number, etc."}}}}}}}}},"OnRampOrderStatus":{"type":"string","enum":["swap_initiated","swap_expired","swap_buyer_rejected","swap_buyer_confirmed","swap_seller_rejected","swap_seller_confirmed","pending","complete","failed"],"description":"- swap_initiated: user has created an order\n- swap_expired: an order has expired\n- swap_buyer_rejected: user has rejected an order\n- swap_buyer_confirmed: user has confirmed an order\n- swap_seller_rejected: agent has rejected an order, happens when agent don't receive a payment\n- swap_seller_confirmed: agent has confirmed an order\n- pending: crypto transaction is pending\n- complete: crypto transaction is complete\n- failed: crypto transaction has failed"},"OnRampPaymentChannel":{"type":"string","enum":["bank","mobile_money","airtime"]},"OnRampNetwork":{"type":"string","enum":["POLYGON","ETHEREUM","STELLAR","AVALANCHE","SOLANA","CELO","BASE","TON","TRON","LISK","ARBITRUM","OPTIMISM","BNB"]},"OnRampAsset":{"type":"string","enum":["USDC","USDT","CUSD","CKES","CGHS","USDE"]}}},"paths":{"/api/onramp/order/confirm":{"post":{"tags":["on-ramp"],"summary":"Confirm onramp order","description":"Confirms an onramp order","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["orderId"],"properties":{"orderId":{"type":"string","description":"The ID of the order to confirm"}}}}}},"responses":{"200":{"description":"Order confirmed successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/OnRampOrder"}}}}}}}}}
```

## Reject onramp order

> Rejects an onramp order

```json
{"openapi":"3.1.0","info":{"title":"Fonbnk On-ramp API","version":"1.0.0"},"tags":[{"name":"on-ramp","description":"On-ramp"}],"servers":[{"url":"https://sandbox-api.fonbnk.com","description":"Development server"},{"url":"https://api.fonbnk.com","description":"Production server"}],"security":[{"ApiKeyAuth":[]}],"components":{"securitySchemes":{},"schemas":{"OnRampOrder":{"type":"object","properties":{"_id":{"type":"string","description":"Order ID"},"status":{"$ref":"#/components/schemas/OnRampOrderStatus"},"date":{"type":"string","format":"date-time","description":"Date of order creation"},"orderId":{"type":"string","description":"Order ID"},"phoneNumber":{"type":"string","description":"User phone number, should include country code"},"email":{"type":"string","description":"User email address"},"localCurrencyAmount":{"type":"number","description":"Amount in local currency"},"currencyIsoCode":{"type":"string","description":"Local currency ISO code, e.g. NGN, KES"},"countryIsoCode":{"type":"string","description":"Country ISO code, e.g. NG"},"paymentChannel":{"$ref":"#/components/schemas/OnRampPaymentChannel","description":"Payment channel used for the order, e.g. bank, mobile_money, airtime"},"amount":{"type":"number","description":"Amount in USD"},"amountCrypto":{"type":"number","description":"Amount in crypto"},"network":{"$ref":"#/components/schemas/OnRampNetwork","description":"Blockchain network of the order, e.g. POLYGON, ETHEREUM, STELLAR"},"asset":{"$ref":"#/components/schemas/OnRampAsset","description":"Blockchain asset of the order, e.g. USDC, USDT, CUSD"},"address":{"type":"string","description":"User wallet address"},"memo":{"type":"string","description":"Memo for the Stellar, TON and other networks transactions that support it"},"hash":{"type":"string","description":"Transaction hash if available"},"orderParams":{"type":"string","description":"Value of the orderParams query param during order creation"},"resumeUrl":{"type":"string","description":"URL to resume the order in the pay widget"},"carrierId":{"type":"string","description":"Carrier ID if applicable, e.g. for mobile money orders"},"feePercent":{"type":"number","description":"total fee percent (fonbnk fee + partner fee)"},"feePercentFonbnk":{"type":"number","description":"fonbnk fee percent"},"feePercentPartner":{"type":"number","description":"partner fee percent"},"feeAmountUsd":{"type":"number","description":"Total fee amount in USD"},"feeAmountLocalCurrency":{"type":"number","description":"Total fee amount in local currency"},"feeAmountUsdFonbnk":{"type":"number","description":"Fonbnk fee amount in USD"},"feeAmountLocalCurrencyFonbnk":{"type":"number","description":"Fonbnk fee amount in local currency"},"feeAmountUsdPartner":{"type":"number","description":"Partner fee amount in USD"},"feeAmountLocalCurrencyPartner":{"type":"number","description":"Partner fee amount in local currency"},"gasAmountUsd":{"type":"number","description":"Gas fee amount in USD"},"gasAmountLocalCurrency":{"type":"number","description":"Gas fee amount in local currency"},"transferInstructions":{"type":"object","properties":{"type":{"type":"string","description":"Type of action required to complete the order","enum":["manual","redirect","stk_push","otp_stk_push","ussd"]},"ussdCode":{"type":"string","description":"USSD code a user needs to dial to complete the order, present only if type is \"ussd\". May include \"{pin}\" placeholder for user PIN, e.g. \"*123*{pin}#\" in this case it should be replaced with their PIN"},"paymentUrl":{"type":"string","description":"URL to redirect the user to complete the payment, present only if type is \"redirect\""},"instructionsText":{"type":"string","description":"Text with instructions for the user to complete the order"},"warningText":{"type":"string","description":"Warning text for the user"},"transferDetails":{"type":"object","properties":{"key":{"type":"object","properties":{"label":{"type":"string","description":"Label for the transfer detail"},"description":{"type":"string","description":"Description of the transfer detail"},"value":{"type":"string","description":"Value of the transfer detail, e.g. account number, phone number, etc."}}}}}}}}},"OnRampOrderStatus":{"type":"string","enum":["swap_initiated","swap_expired","swap_buyer_rejected","swap_buyer_confirmed","swap_seller_rejected","swap_seller_confirmed","pending","complete","failed"],"description":"- swap_initiated: user has created an order\n- swap_expired: an order has expired\n- swap_buyer_rejected: user has rejected an order\n- swap_buyer_confirmed: user has confirmed an order\n- swap_seller_rejected: agent has rejected an order, happens when agent don't receive a payment\n- swap_seller_confirmed: agent has confirmed an order\n- pending: crypto transaction is pending\n- complete: crypto transaction is complete\n- failed: crypto transaction has failed"},"OnRampPaymentChannel":{"type":"string","enum":["bank","mobile_money","airtime"]},"OnRampNetwork":{"type":"string","enum":["POLYGON","ETHEREUM","STELLAR","AVALANCHE","SOLANA","CELO","BASE","TON","TRON","LISK","ARBITRUM","OPTIMISM","BNB"]},"OnRampAsset":{"type":"string","enum":["USDC","USDT","CUSD","CKES","CGHS","USDE"]}}},"paths":{"/api/onramp/order/reject":{"post":{"tags":["on-ramp"],"summary":"Reject onramp order","description":"Rejects an onramp order","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["orderId"],"properties":{"orderId":{"type":"string","description":"The ID of the order to reject"}}}}}},"responses":{"200":{"description":"Order rejected successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/OnRampOrder"}}}}}}}}}
```


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.fonbnk.com/v1.5/endpoints/on-ramp.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.