Referral Method

The Referral Method allows you to link customers out to Banxa checkout without the need to make API calls. You can implement this simply by directing the customer to a blank order form, or by sending through parameters needed to populate the Banxa order form. Your customer will be directed to the Banxa order which will be pre-filled with any parameters that were passed through.

Use this integration option if you do not require webhooks or price comparison within your site.

The below integration steps uses our SDK, so that all you need to do is run a code snippet which will inject all the code you need in order to initiate Banxa checkout. Although using the SDK is not required, it is highly recommended.

Before you begin

  • Your Account Manager will enable your integration
  • If you wish to embed the Banxa checkout as an iFrame, you will need to provide us with the exact domain where you will host the iFrame so that we can conduct whitelisting

Using the SDK

Embed the following Code Snippet

!function(callback){
var b=document.createElement('script'); b.type="text/javascript", b.async=!0,
b.src="https://sdk.banxa.com/js/banxa-sdk-latest.js";
var x=document.getElementsByTagName('script')[0]; x.parentNode.insertBefore(b,x);
if(callback){b.addEventListener("load",function(){callback()})}}
(yourOnLoadFunction);

Initiate Banxa class

Use the following snippet to create an instance of the banxa class to generate redirect and iframes. Insert your company name into the code snippet.

<script>
    const production = new Banxa(`your-partner-name`); //Use this line of code if you want to use Production mode. 'your-partner-name` is the name of your company, e.g. `binance`
    const sandbox = new Banxa(`your-partner-name`, `sandbox`); //Use this line of code if you want to use Sandbox mode
</script>

Redirect

Use the following snippet to create a redirect to the Banxa Order page:

<script>
    banxa.redirect('#redirect',
            {
                'fiatType': 'AUD',
                'coinType': 'BTC',
                'fiatAmount': 500,
                'coinAmount': 0.2,
                'walletAddress': '3Hiy7HuFcqwkgERyfRSwEHqrwSwTirm8zb',
            });
</script>

<button id="redirect">Launch Redirect</button>

iFrame

Use the following snippet to create an iframe:

<script>
    banxa.iframe('#iframe', '#iframeTarget',
        {
            'fiatType': 'AUD',
            'coinType': 'BTC',
            'fiatAmount': 200,
            'coinAmount': 0.5,
            'walletAddress': '3Hiy7HuFcqwkgERyfRSwEHqrwSwTirm8zb',
        },
        "800px", //Optional width parameter – Pass `false` if not needed.
        "400px"  //Optional height parameter – Pass `false` if not needed.
    );

</script>

<button id="iframeButton">Launch iframe</button>

<div id="iframeTarget">
    <!-- Where the iframe will be loaded  -->
</div>

Parameters

Here are the supported parameters that can be passed to Banxa. All of these parameters are optional, however we recommend that you pass through as many values as possible as this significantly improves conversions.

👍

The exact name and case of the parameter must be used.

ParameterDescription
sellModeIndicates whether the customer wants to sell. The customer will be shown the Sell Order Form when they are redirected to the Banxa cart. This will depend on whether you have implemented the option to sell. If this parameter is not passed, then the order will default to buyMode
fiatTypeFiat currency code that the customer wants to exchange e.g USD
fiatAmountFiat amount that the customer wants to exchange e.g. 500. If both a fiatAmount and coinAmount are passed, then the fiatAmount will be used
coinTypeCoin currency code that the customer wants to exchange e.g. ETH
coinAmountCoin amount that the customer wants to exchange e.g. 800. If both a fiatAmount and coinAmount are passed, then the fiatAmount will be used
blockchainBlockchain network code that is selected by the customer. If this parameter is not passed, the default blockchain configured for the coinType selected will apply
walletAddressCustomer’s wallet address
walletAddressTagCustomer’s wallet tag or memo. This is required for transacting on certain blockchains such as BNB and XRP

Alternative Implementation

You can implement this by directing the customer to a blank order form with the base URL, or by constructing a URL that contains the parameters needed to populate the Banxa order form. Your customer will be directed to the Banxa order form which will be pre-filled with any parameters that were contained in the URL.

There are two UI approaches available for directing the customer to the Banxa checkout flow.

Redirect

This will redirect the customer to the Banxa checkout flow in another tab to complete their order. The customer’s order page will be pre-filled with the order details that have been passed through to Banxa via the referral URL.

Example of a redirect URL

https://{yourCompany}.banxa.com/?coinType=ETH&fiatType=USD&fiatAmount=500&blockchain=ETH

iFrame

This will host the Banxa site in an iFrame and allow customers to complete the checkout process within this iFrame. This can be done by including the iframe parameter as part of the URL.

Please contact your dedicated Customer Success Manager for this information.

Example of an iFrame URL

https://{yourCompany}.banxa.com/iframe?coinType=ETH&fiatType=USD&fiatAmount=500&blockchain=ETH

Dynamic Callback URL (Deeplinking)

If you would like to Banxa to append order parameters onto the callback URL, reach out to your Account Manager and we can set this up for you.

The available parameters that can be appended to a callback URL (the URL that we will use to redirect the customer back to your application after they have completed the checkout journey on Banxa), include:

fiatAmount
fiat
coinAmount
coin
orderId
orderRef
orderStatus
fulfillmentStatus
paymentStatus
identityStatus

Example of a callback URL

https://youCompanyName/?orderId={509427}&fiat={AUD}&fiatAmount={0}&coin={BTC}&coinAmount={0}&orderRef={12a320b36117089a9e94b3e8acd4cf5d}&orderStatus={Expired}&fulfillmentStatus={Pending}&paymentStatus={Expired}&identityStatus={Complete}