# On Ramp

On-ramp

## Get list of supported assets

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

```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://aten.fonbnk-services.com","description":"Production server"}],"security":[{"ClientIdHeader":[]},{"TimestampHeader":[]},{"SignatureHeader":[]}],"components":{"securitySchemes":{"ClientIdHeader":{"type":"apiKey","in":"header","name":"x-client-id"},"TimestampHeader":{"type":"apiKey","in":"header","name":"x-timestamp"},"SignatureHeader":{"type":"apiKey","in":"header","name":"x-signature"}},"schemas":{"OnrampNetwork":{"type":"string","enum":["POLYGON","ETHEREUM","STELLAR","AVALANCHE","SOLANA","ALGORAND","CELO","BASE","TON","LISK","ARBITRUM","OPTIMISM","BNB"]},"OnrampAsset":{"type":"string","enum":["USDC","USDC_E","USDT","CUSD","CKES"]}}},"paths":{"/api/pay-widget-merchant/assets":{"get":{"tags":["on-ramp"],"summary":"Get list of supported assets","description":"Returns a list of supported blockchain assets for the on-ramp","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://aten.fonbnk-services.com","description":"Production server"}],"security":[{"ClientIdHeader":[]},{"TimestampHeader":[]},{"SignatureHeader":[]}],"components":{"securitySchemes":{"ClientIdHeader":{"type":"apiKey","in":"header","name":"x-client-id"},"TimestampHeader":{"type":"apiKey","in":"header","name":"x-timestamp"},"SignatureHeader":{"type":"apiKey","in":"header","name":"x-signature"}},"schemas":{"OnrampOrder":{"type":"object","properties":{"_id":{"type":"string","description":"Order ID"},"walletType":{"$ref":"#/components/schemas/OnrampNetwork","description":"Network type"},"asset":{"$ref":"#/components/schemas/OnrampAsset","description":"Asset type"},"walletAddress":{"type":"string","description":"User wallet address"},"feePercent":{"type":"number","description":"total fee percent (fonbnk fee + partner fee)"},"fonbnkFeePercent":{"type":"number"},"partnerFeePercent":{"type":"number"},"gasUsdAmount":{"type":"number"},"merchantId":{"type":"string"},"createdAt":{"type":"string","format":"date-time"},"buySwap":{"type":"object","properties":{"_id":{"type":"string"},"buyerUserPhone":{"type":"string"},"buyerUserEmail":{"type":"string"},"sellerUserPhone":{"type":"string"},"amount":{"type":"number","description":"Amount in cents"},"airtimeAmount":{"type":"number"},"status":{"$ref":"#/components/schemas/BuySwapStatus"},"provider":{"$ref":"#/components/schemas/OnRampProvider"},"expiresAt":{"type":"string","format":"date-time"},"createdAt":{"type":"string","format":"date-time"},"buyerConfirmedAt":{"type":"string","format":"date-time"},"countryIsoCode":{"type":"string"}}},"withdrawal":{"type":"object","properties":{"_id":{"type":"string"},"status":{"$ref":"#/components/schemas/WithdrawalStatus"},"withdrawAmount":{"description":"Amount in USD","type":"number"},"withdrawCryptoAmount":{"description":"Amount in crypto","type":"number"},"transactionHash":{"type":"string"}}},"feeAmount":{"type":"number","description":"Total fee amount in USD"},"localCurrencyFeeAmount":{"type":"number","description":"Total fee amount in local currency"},"fonbnkFeeAmount":{"type":"number"},"localCurrencyFonbnkFeeAmount":{"type":"number"},"partnerFeeAmount":{"type":"number"},"localCurrencyPartnerFeeAmount":{"type":"number"},"networkFeeAmount":{"type":"number"},"localCurrencyNetworkFeeAmount":{"type":"number"},"resumeUrl":{"type":"string"}}},"OnrampNetwork":{"type":"string","enum":["POLYGON","ETHEREUM","STELLAR","AVALANCHE","SOLANA","ALGORAND","CELO","BASE","TON","LISK","ARBITRUM","OPTIMISM","BNB"]},"OnrampAsset":{"type":"string","enum":["USDC","USDC_E","USDT","CUSD","CKES"]},"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"},"OnRampProvider":{"type":"string","enum":["bank_transfer","mobile_money","mpesa","carrier"]},"WithdrawalStatus":{"type":"string","enum":["pending","complete","failed"]}}},"paths":{"/api/pay-widget-merchant/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://aten.fonbnk-services.com","description":"Production server"}],"security":[{"ClientIdHeader":[]},{"TimestampHeader":[]},{"SignatureHeader":[]}],"components":{"securitySchemes":{"ClientIdHeader":{"type":"apiKey","in":"header","name":"x-client-id"},"TimestampHeader":{"type":"apiKey","in":"header","name":"x-timestamp"},"SignatureHeader":{"type":"apiKey","in":"header","name":"x-signature"}},"schemas":{"OnrampNetwork":{"type":"string","enum":["POLYGON","ETHEREUM","STELLAR","AVALANCHE","SOLANA","ALGORAND","CELO","BASE","TON","LISK","ARBITRUM","OPTIMISM","BNB"]},"OnRampProvider":{"type":"string","enum":["bank_transfer","mobile_money","mpesa","carrier"]},"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"},"walletType":{"$ref":"#/components/schemas/OnrampNetwork","description":"Network type"},"asset":{"$ref":"#/components/schemas/OnrampAsset","description":"Asset type"},"walletAddress":{"type":"string","description":"User wallet address"},"feePercent":{"type":"number","description":"total fee percent (fonbnk fee + partner fee)"},"fonbnkFeePercent":{"type":"number"},"partnerFeePercent":{"type":"number"},"gasUsdAmount":{"type":"number"},"merchantId":{"type":"string"},"createdAt":{"type":"string","format":"date-time"},"buySwap":{"type":"object","properties":{"_id":{"type":"string"},"buyerUserPhone":{"type":"string"},"buyerUserEmail":{"type":"string"},"sellerUserPhone":{"type":"string"},"amount":{"type":"number","description":"Amount in cents"},"airtimeAmount":{"type":"number"},"status":{"$ref":"#/components/schemas/BuySwapStatus"},"provider":{"$ref":"#/components/schemas/OnRampProvider"},"expiresAt":{"type":"string","format":"date-time"},"createdAt":{"type":"string","format":"date-time"},"buyerConfirmedAt":{"type":"string","format":"date-time"},"countryIsoCode":{"type":"string"}}},"withdrawal":{"type":"object","properties":{"_id":{"type":"string"},"status":{"$ref":"#/components/schemas/WithdrawalStatus"},"withdrawAmount":{"description":"Amount in USD","type":"number"},"withdrawCryptoAmount":{"description":"Amount in crypto","type":"number"},"transactionHash":{"type":"string"}}},"feeAmount":{"type":"number","description":"Total fee amount in USD"},"localCurrencyFeeAmount":{"type":"number","description":"Total fee amount in local currency"},"fonbnkFeeAmount":{"type":"number"},"localCurrencyFonbnkFeeAmount":{"type":"number"},"partnerFeeAmount":{"type":"number"},"localCurrencyPartnerFeeAmount":{"type":"number"},"networkFeeAmount":{"type":"number"},"localCurrencyNetworkFeeAmount":{"type":"number"},"resumeUrl":{"type":"string"}}},"OnrampAsset":{"type":"string","enum":["USDC","USDC_E","USDT","CUSD","CKES"]}}},"paths":{"/api/pay-widget-merchant/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":"walletType","in":"query","description":"wallet type of orders","required":false,"schema":{"$ref":"#/components/schemas/OnrampNetwork"}},{"name":"walletAddress","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":"swapProvider","in":"query","required":false,"schema":{"$ref":"#/components/schemas/OnRampProvider"}},{"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"}}}}}}}}}
```

## Get price

> Returns expected price in USDC, cUSD etc. for a given amount of mobile money and vice versa.

```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://aten.fonbnk-services.com","description":"Production server"}],"security":[{"ClientIdHeader":[]},{"TimestampHeader":[]},{"SignatureHeader":[]}],"components":{"securitySchemes":{"ClientIdHeader":{"type":"apiKey","in":"header","name":"x-client-id"},"TimestampHeader":{"type":"apiKey","in":"header","name":"x-timestamp"},"SignatureHeader":{"type":"apiKey","in":"header","name":"x-signature"}},"schemas":{"OnrampNetwork":{"type":"string","enum":["POLYGON","ETHEREUM","STELLAR","AVALANCHE","SOLANA","ALGORAND","CELO","BASE","TON","LISK","ARBITRUM","OPTIMISM","BNB"]},"OnrampAsset":{"type":"string","enum":["USDC","USDC_E","USDT","CUSD","CKES"]},"OnrampCurrency":{"type":"string","enum":["usdc","local"]},"OnRampProvider":{"type":"string","enum":["bank_transfer","mobile_money","mpesa","carrier"]},"OnrampPriceResponse":{"type":"object","properties":{"quoteId":{"type":"string","description":"Unique quote id"},"cryptoTotalAmount":{"type":"number","description":"Amount of crypto user should receive before fees"},"cryptoWithdrawAmount":{"type":"number","description":"Amount of crypto user should receive after fees"},"cryptoFeeAmount":{"type":"number","description":"Total fee amount (fonbnk fee + partner fee) in crypto"},"cryptoGasAmount":{"type":"number","description":"Network fee in crypto"},"localCurrencyAmount":{"type":"number","description":"Amount of local currency user should pay"},"feePercent":{"type":"number","description":"Total fee percent (fonbnk fee + partner fee)"},"fonbnkFeePercent":{"type":"number"},"partnerFeePercent":{"type":"number"},"totalAmount":{"type":"number","description":"Amount of funds user will receive before fees"},"withdrawAmount":{"type":"number","description":"Amount of funds user will receive after fees"},"feeAmount":{"type":"number","description":"Total fee amount (fonbnk fee + partner fee)"},"localCurrencyFeeAmount":{"type":"number","description":"Total fee amount in local currency (fonbnk fee + partner fee)"},"fonbnkFeeAmount":{"type":"number"},"localCurrencyFonbnkFeeAmount":{"type":"number"},"partnerFeeAmount":{"type":"number"},"localCurrencyPartnerFeeAmount":{"type":"number"},"networkFeeAmount":{"type":"number"},"localCurrencyNetworkFeeAmount":{"type":"number"},"usdcTotalAmount":{"type":"number","description":"Amount of usd user will receive before fees (deprecated)"},"usdcWithdrawAmount":{"type":"number","description":"Amount of usd user will receive after fees (deprecated)"},"usdcFeeAmount":{"type":"number","description":"Fonbnk service fee (deprecated)"},"usdcGasAmount":{"type":"number","description":"Network fee (deprecated)"}}}}},"paths":{"/api/pay-widget-merchant/price":{"get":{"tags":["on-ramp"],"summary":"Get price","description":"Returns expected price in USDC, cUSD etc. for a given amount of mobile money and vice versa.","operationId":"getPrice","parameters":[{"name":"network","in":"query","required":true,"schema":{"$ref":"#/components/schemas/OnrampNetwork"}},{"name":"asset","in":"query","required":true,"schema":{"$ref":"#/components/schemas/OnrampAsset"}},{"name":"currency","in":"query","required":true,"schema":{"$ref":"#/components/schemas/OnrampCurrency"}},{"name":"amount","in":"query","required":true,"schema":{"type":"number"}},{"name":"country","in":"query","required":true,"description":"country ISO code, e.g. NG","schema":{"type":"string"}},{"name":"provider","in":"query","required":true,"schema":{"$ref":"#/components/schemas/OnRampProvider"}},{"name":"carrierId","in":"query","required":false,"schema":{"type":"string"}}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/OnrampPriceResponse"}}}}}}}}}
```

## Get providers

> Returns a list of providers. Optionally includes limitations data.

```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://aten.fonbnk-services.com","description":"Production server"}],"security":[{"ClientIdHeader":[]},{"TimestampHeader":[]},{"SignatureHeader":[]}],"components":{"securitySchemes":{"ClientIdHeader":{"type":"apiKey","in":"header","name":"x-client-id"},"TimestampHeader":{"type":"apiKey","in":"header","name":"x-timestamp"},"SignatureHeader":{"type":"apiKey","in":"header","name":"x-signature"}},"schemas":{"OnrampNetwork":{"type":"string","enum":["POLYGON","ETHEREUM","STELLAR","AVALANCHE","SOLANA","ALGORAND","CELO","BASE","TON","LISK","ARBITRUM","OPTIMISM","BNB"]},"OnrampProvidersListResponse":{"type":"array","items":{"type":"object","properties":{"countryIsoCode":{"type":"string"},"currencyIsoCode":{"type":"string"},"providers":{"type":"array","items":{"type":"object","properties":{"name":{"type":"string"},"description":{"type":"string"},"requiresCarrier":{"type":"boolean"},"limits":{"$ref":"#/components/schemas/OnrampProviderLimitations"},"carriers":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"limits":{"$ref":"#/components/schemas/OnrampProviderLimitations"}}}}}}}}}},"OnrampProviderLimitations":{"type":"object","properties":{"AVALANCHE":{"$ref":"#/components/schemas/OnrampProviderLimit"},"CELO":{"$ref":"#/components/schemas/OnrampProviderLimit"},"POLYGON":{"$ref":"#/components/schemas/OnrampProviderLimit"},"STELLAR":{"$ref":"#/components/schemas/OnrampProviderLimit"},"SOLANA":{"$ref":"#/components/schemas/OnrampProviderLimit"},"BASE":{"$ref":"#/components/schemas/OnrampProviderLimit"},"TON":{"$ref":"#/components/schemas/OnrampProviderLimit"}}},"OnrampProviderLimit":{"type":"object","properties":{"cryptoLimits":{"type":"object","properties":{"min":{"type":"number"},"max":{"type":"number"}}},"fees":{"type":"object","properties":{"feePercent":{"type":"number"},"fonbnkFeePercent":{"type":"number"},"partnerFeePercent":{"type":"number"},"gasAmount":{"type":"number"},"minFee":{"type":"number"}}},"localCurrency":{"type":"object","properties":{"type":{"type":"string","enum":["open_range","fixed_list"]},"max":{"type":"number"},"min":{"type":"number"},"step":{"type":"number"},"withCents":{"type":"boolean"},"values":{"type":"array","items":{"type":"number"}}}}}}}},"paths":{"/api/pay-widget-merchant/providers":{"get":{"tags":["on-ramp"],"summary":"Get providers","description":"Returns a list of providers. Optionally includes limitations data.","operationId":"getProviders","parameters":[{"name":"includeLimits","in":"query","description":"Should limitations data be included in the response. Defaults to true. If limitations are not included the request will be much faster.","required":false,"schema":{"type":"boolean","default":true}},{"name":"network","in":"query","required":false,"schema":{"$ref":"#/components/schemas/OnrampNetwork"}}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/OnrampProvidersListResponse"}}}}}}}}}
```

## Get limits

> Returns minimum and maximum amount of order in crypto and local currency and applied fees.

```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://aten.fonbnk-services.com","description":"Production server"}],"security":[{"ClientIdHeader":[]},{"TimestampHeader":[]},{"SignatureHeader":[]}],"components":{"securitySchemes":{"ClientIdHeader":{"type":"apiKey","in":"header","name":"x-client-id"},"TimestampHeader":{"type":"apiKey","in":"header","name":"x-timestamp"},"SignatureHeader":{"type":"apiKey","in":"header","name":"x-signature"}},"schemas":{"OnrampNetwork":{"type":"string","enum":["POLYGON","ETHEREUM","STELLAR","AVALANCHE","SOLANA","ALGORAND","CELO","BASE","TON","LISK","ARBITRUM","OPTIMISM","BNB"]},"OnrampAsset":{"type":"string","enum":["USDC","USDC_E","USDT","CUSD","CKES"]},"OnRampProvider":{"type":"string","enum":["bank_transfer","mobile_money","mpesa","carrier"]},"OnrampLimitsResponse":{"type":"object","properties":{"cryptoLimits":{"type":"object","properties":{"min":{"type":"number"},"max":{"type":"number"}}},"localCurrencyLimits":{"oneOf":[{"type":"object","properties":{"type":{"type":"string","enum":["open_range","fixed_list"]},"min":{"type":"number"},"max":{"type":"number"},"step":{"type":"number"},"withCents":{"type":"boolean"},"values":{"type":"array","items":{"type":"number"}}}},{"type":"object","properties":{"type":{"type":"string","enum":["fixed_list"]},"values":{"type":"array","items":{"type":"number"}},"withCents":{"type":"boolean"}}}]},"fees":{"type":"object","properties":{"feePercent":{"type":"number"},"fonbnkFeePercent":{"type":"number"},"partnerFeePercent":{"type":"number"},"gasAmount":{"type":"number"},"minFee":{"type":"number"}}}}}}},"paths":{"/api/pay-widget-merchant/limits":{"get":{"tags":["on-ramp"],"summary":"Get limits","description":"Returns minimum and maximum amount of order in crypto and local currency and applied fees.","operationId":"getLimits","parameters":[{"name":"network","in":"query","required":true,"schema":{"$ref":"#/components/schemas/OnrampNetwork"}},{"name":"asset","in":"query","required":false,"schema":{"$ref":"#/components/schemas/OnrampAsset"}},{"name":"country","in":"query","required":true,"schema":{"type":"string"}},{"name":"provider","in":"query","required":true,"schema":{"$ref":"#/components/schemas/OnRampProvider"}},{"name":"carrierId","in":"query","required":false,"schema":{"type":"string"}}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/OnrampLimitsResponse"}}}}}}}}}
```