Full-page checkout

Hosted pages

This allows you to redirect your users to a separate fiat off-ramp checkout page.

With the Checkout Redirect option, you can access the LocalRamp payment gateway by making a request from your server to our initiate sell checkout endpoint. We would return a response that includes a Checkout URL that loads the payment page where your users can sell crypto. After payment is completed or canceled, the customer is returned to any URL specified by you.

1. Collect payment details

Collect payment details from your user. These details are passed to the initiate sell checkout endpoint.

Please find below the request body for the endpoint.

Field Data Type Description

Field	Data Type	Description
reference	String	Required - Your unique transaction reference. Must be unique for every transaction. e.g "Abc123"
email	String	Optional e.g "customer@example.com"
from_currency	String	Optionally Required - The crypto currency your user would be sending. It becomes required only if `from_amount` or `to_amount` is provided. e.g "USDT"
crypto_chain	String	Optionally Required - The crypto_chain of from_currency. It becomes required only if `from_amount` or `to_amount` is provided. e.g "BSC"
to_currency	String	Optionally Required - The fiat currency that would be received. It becomes required only if `from_amount` , `to_amount` e.g "NGN"
country_code	String	Optionally Required - The country_code where payout would be received. It becomes required only if `to_currency` is present e.g "NG", "KE", "GH"
from_amount	String	Optional - crypto amount the user would be paying in `from_currency` unit. e.g "0.02343434". If this is present, then `to_amount` should be omitted
to_amount	String	Optional - fiat amount that should be paid out in `to_currency` unit. e.g "10000". If this is present, then `from_amount` should be omitted
widget_color	String	Optional - Hex color code to customize widget e.g "#DA70D6"
callback_url	String	Optional - The url to redirect your users to, when the transaction is complete

reference

String

Required - Your unique transaction reference. Must be unique for every transaction. e.g "Abc123"

String

Optional e.g "customer@example.com"

from_currency

String

Optionally Required - The crypto currency your user would be sending. It becomes required only if from_amount or to_amount is provided. e.g "USDT"

crypto_chain

String

Optionally Required - The crypto_chain of from_currency. It becomes required only if from_amount or to_amount is provided. e.g "BSC"

to_currency

String

Optionally Required - The fiat currency that would be received. It becomes required only if from_amount , to_amount e.g "NGN"

country_code

String

Optionally Required - The country_code where payout would be received. It becomes required only if to_currency is present e.g "NG", "KE", "GH"

from_amount

String

Optional - crypto amount the user would be paying in from_currency unit. e.g "0.02343434". If this is present, then to_amount should be omitted

to_amount

String

Optional - fiat amount that should be paid out in to_currency unit. e.g "10000". If this is present, then from_amount should be omitted

widget_color

String

Optional - Hex color code to customize widget e.g "#DA70D6"

callback_url

String

Optional - The url to redirect your users to, when the transaction is complete

You can pass either the from_amount or to_amount when initializing the widget but not both.

Before passing in either the from_amount or rto_amount, you'll need to know the maximum and minimum values allowed for each field. See limit section.

To get the list of supported currencies, crypto chains and country codes for both from_currency and to_currency see the Get currencies section.

from_amount and to_amount passed show payment intent and does not guarantee the exact value that would be received at the end of the transaction. To see the exact amounts received, get transaction state.

2 - Initialize the transaction

After collecting the necessary payment details for the transaction. Make a POST request to our initiate buy endpoint.

https://api.localramp.co/v1/transaction/sell-widget/initiate

This endpoint takes the payment details as the request body.

With the following header

x-auth-token: <SECRET_KEY>

This endpoint is protected by secret key authentication. So when calling it, append the x-auth-token header with your secret key.

If the API call is successful, LocalRamp returns the following response:


{
    "status": "success",
    "msg": "Transaction(sell) initiated successfully",
    "data": {
        "reference": "your-unique-reference",
        "checkout_link": "https://sell-checkout.localramp.co/TYUBjkns"
    }
}

You should then redirect your user to the Checkout URL provided in the response to enable them to complete their payment.

You can also choose to open the checkout link in an iframe

<iframe src="https://sell-checkout.localramp.co/bTYUBjkns" frameborder="0" width="350" height="500" allow="clipboard-read; clipboard-write self *"></iframe>

Once the offramp is complete or the checkout is closed, LocalRamp will redirect your user to your specified callback_url.

3. Verifying the transaction status

The transaction reference will be appended as a query parameter to your callback_url as well.

https://website_callback_url/?reference=YOUR_REFERENCE

You can now verify the status of the transaction. See verify section

In a situation where no callback_url is passed, the user will be redirected to your business website.

4. Receive confirmation via webhook

In some cases, the fiat might take a few minutes to arrive. If you do not want to keep querying the transaction status, you can always get informed when the transaction is complete through webhooks. See webhook section.

PreviousWidget Sell NextWidget Pop-up

Last updated 2 months ago