Guides

Off-Ramp API Tutorial

Suggest Edits

This tutorial should be used if you want to implement crypto sell functionality from your application. This solution requires that you provide custodial wallets to your users, as you will need to be able to facilitate crypto transfers on their behalf as part of the crypto to fiat process.

Off-Ramp Integration using API

Order Initiation

If you have an interface for your customer to choose which type of coin they want to sell, which fiat currency they want to be paid, and how much coin they want to sell or how much fiat currency they want to be paid, follow the steps below:

  1. Call the Get Prices endpoint for the chosen coin type, fiat currency and amount to get a spot price quote value from Banxa.

  2. Create an Order using the Create Order endpoint:

    a) For Sell Orders, the fiat currency code is entered in the "target" field, and the coin code is entered in the "source" field.
    b) Enter either the "target_amount" or the "source_amount" that was selected by the Customer based on the information from the spot price quote values.
    c) You are required to provide a Customer "refund_address" (and the "refund_address_tag", if applicable) so that Banxa is able to process a refund if this is required.

  3. If either the "target_amount" or the "source_amount" has already been selected by the Customer and provided in the Order creation request, then the Banxa Order page becomes redundant. Therefore, once the Customer enters the Banxa checkout flow, the Banxa Order page will be skipped and the Customer will go to the next step of the flow.

If you do not have such interface, follow the steps below:

  1. Create an Order using the Create Order endpoint:

    a) For Sell Orders, the fiat currency code is entered in the "target" field, and the coin code is entered in the "source" field.
    b) You are required to provide a Customer "refund_address" (and the "refund_address_tag", if applicable) so that Banxa is able to process a refund if this is required.

Once the Customer enters Banxa's checkout flow, they will be guided through the process for Banxa to collect and verify their personal details, KYC documents, and the nominated bank account details for the Sell Order payout.

Order Finalisation

Once Banxa is satisfied that the KYC and compliance requirements for a Customer's Sell order has been sufficiently met, the Order will progress to the WAITINGPAYMENT status (see Order Status). The transition into this status will trigger a webhook. This webhook will serve as a notification that Banxa is ready to accept the coin to complete the Sell Order.

For Sell Orders, it is required that you are subscribed to receive this webhook. Refer to the Webhooks section for detail and instructions.

The following steps must now be taken:

  1. Request the Get Order endpoint for the Sell Order quoted in the webhook.

  2. Since the Order is now in the 'waitingPayment' status, the Get Order response payload will now contain a value in the "data.order.wallet_address" field and for some coins a value in the "data.order.wallet_address_tag" field. This is the wallet address to which the coin amount for Sell Order should be sent to (and wallet address tag/memo, if applicable). We request that this wallet address should not be exposed to Customers to avoid receiving unsolicited coin transfers to this wallet address.

  3. You are now responsible for facilitating the coin transfer to this wallet address with your Customer. The exact coin amount referenced in the order should be sent as soon as possible.

📘

Alternative to the Webhooks and Get Order flow

If you prefer, we are able to provide you a deeplink after the user has completed submitting their payment details. We will use the return_url_on_success request parameter that you provided in the POST Create Order, and we will append to it the deposit address as well as other details.

Example.

https://example.com/?orderId=64c50959eb5eec88039dk2ed1487b722c&providerWalletAddress=tb1qmszc3uatmwe3c7y0kme2c2r5za78mzjyw0gdef&blockchain=BTC&coinType=BTC&coinAmount=0.00179857&customerWalletAddress=1LbQ1WNTsm1Nzj1hbh3WDCbEim1oUg5rfi

  1. Once the coin has been sent, you must now notify Banxa that the coin has been sent by sending a request to Confirm Sell Order endpoint, providing the following information:

    a) The Sell Order reference
    b) The sending wallet address from which the coin was sourced
    c) The destination wallet address to which the coin was sent
    d) The transaction hash of the coin transfer

  2. It is important that this information is sent to Banxa as soon as the coin transfer is executed to prevent the Sell Order from expiring. Once Banxa receives this notification, the expiry timeframe for the Sell Order will be extended to cater for any delays on the blockchain.

  3. Once Banxa receives the coin transfer it will be reconciled to the Sell Order and the fiat currency amount will immediately be sent to the Customer's nominated bank account to complete the process. The Order will then progress to COMPLETED.

Updated 8 months ago