The Referral Link (URL parametization) 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.

Before you begin

• If you have requested a Banxa account, you will first need your Account Manager to enable your integration

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, a redirect to a new tab, or an iFrame.

➡️ 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&backgroundColor=ffffff&primaryColor=e014c2&secondaryColor=4287f5&textColor=000000&theme=light&walletAddress=0xf831d1781287e499bd546cc4831cf783af84b8e3

🗔 iFrame

This will host the Banxa site in an iFrame and allow customers to complete the checkout process within this iFrame. The same URL can be used as in above example.

Allow the below permissions for the iframe

• payment
• encrypted-media
• microphone
• camera
• midi

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 This is the overall status of the order.
fulfillmentStatus This a sub-status for the progress of crypto transfer.
paymentStatus This is a sub-status for the progress of fiat payment.
identityStatus This is a sub-status for the progress of the customer's KYC.

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}

📘

Building the Banxa Order Summary Page

If you would like to provide a link for your customer to the Banxa Order Status page, you can append the orderRef value to your Return on Success URL. e.g. https://binance.banxa.com/status/{{orderRef}}

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.

Using the SDK

Alternatively, you can use our SDK. All you need to do is run a code snippet which will inject all the code you need in order to initiate Banxa checkout.

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 to a new tab

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',
 		'theme': 'dark'
            });
</script>

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

🗔 iFrame embedded directly into your application

Use the following snippet to create an iframe:

<script>
    banxa.iframe('#iframeButton', '#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>