Buy Order Form (F2C) ​

Introduction ​

This document describes the steps to take in order to embed the BTC Direct buy order form widget in another website. It is aimed at developers that will implement this functionality.

Implementing the widget ​

In order to enable the widget in your website, the following script needs to be embedded. This script loads the widget from the BTC Direct CDN (Content Delivery Network) and initializes it automatically.

<script lang="js">
    (function (btc, d, i, r, e, c, t) {
        btc[r] = btc[r] || function () {
            (btc[r].q = btc[r].q || []).push(arguments)
        };
        c = d.createElement(i);
        c.id = r; c.src = e; c.async = true;
        c.type = 'module'; c.dataset.btcdirect = '';
        t = d.getElementsByTagName(i)[0];
        t.parentNode.insertBefore(c, t);
    })(window, document, 'script', 'btcdirect',
        'https://cdn.btcdirect.eu/fiat-to-coin/fiat-to-coin.js'
    );

    btcdirect('init', { token: 'API_KEY' });
</script>

If a valid key is provided, and the styling is added, it will result in the following:

Important: Provide wallet address(es) ​

When implementing the above example, there will be a notification shown instead of the wallet address selector. This is because the widget expects the user’s wallet addresses to be provided in order to select them.

The above preview has (demo) addresses provided and therefore shows the wallet address selector correctly.

Optional init call parameters ​

The init call, as described in Getting Started, can contain several key-value pairs to fine-tune the widget. The different options are described below.

All widgets support selector, debug, locale and theme.

Additional calls to the widget ​

The widget accepts several calls to it with which additional information can be provided. These can be added to the script tag that loads the widget.

Currencies ​

This call sets the selected currencies for the widget. This is for both the cryptocurrency and the fiat currency. The provided values result in these currencies being selected in the order form as initial values.

btcdirect('currencies', { crypto: 'BTC', fiat: 'EUR' });

• Available values for cryptocurrency: List of supported cryptocurrencies
• Available values for fiat: List of supported fiat currencies

Order information ​

It is possible to set up the basic information of an order, making it easier for your users to purchase crypto as most of the form will be pre-filled. In order to do this you can provide both currencies of the order (crypto and fiat), the order amount and if it is a fiat amount or crypto amount.

// JavaScript from previous code example
btcdirect('init', { token: 'API_KEY' });

btcdirect('order', {
    crypto: 'LTC',
    fiat: 'EUR',
    amount: 1,
    type: 'crypto'
});

• Available values for type: crypto and fiat
• Available values for cryptocurrency: List of supported cryptocurrencies
• Available values for fiat: List of supported fiat currencies

Locale ​

This call sets the locale for the application. This determines the way monetary values are displayed. For example 0 Euro’s in the EN-GB locale is displayed as “€0.00” whereas the NL-NL locale results in “€ 0,00”.

btcdirect('locale', { locale: 'en-GB' });

Payment method ​

This call sets the selected payment method for the order form. The payment methods are only visible once the user has logged in.

btcdirect('payment-method', { method: 'iDeal' });

The following payment methods are available.

Note: In order for Apple Pay to be visible in the list of payment methods, the widget needs to be initialised in Safari on an Apple device. To learn more about compatible devices, visit Apple's documentation.

Callback url ​

This call sets a callback url to which the result of the order is communicated. For example when setting the url to https://btcdirect.eu it will be called after an order has been completed. The status and ID of the order are added as query parameters, such as ?orderId=123456&status=success. This enables your website to catch the status of the order and display information accordingly.

btcdirect('callback', { callbackUrl: 'https://btcdirect.eu' });

The following values can be returned by the process, according to the status of the order:

Wallet address confirmation ​

When the init parameter walletConfirmationRequired parameter is set to true, and the btcdirect-embeddable-fiat-to-coin-order-confirmed is received, the widget needs a confirmation message from your application in order to continue the order. The idea is to have the user confirm the wallet address on your (hardware) wallet. Once the confirmation is done the following message can be sent to the widget confirming the wallet. In this example the address needs to be replaced by the user’s wallet address.

btcdirect('wallet-address-confirmation', {
    address: 'address'
});

Canceling wllet address confirmation ​

It’s possible to send a cancellation to the widget in order to stop the process. This results in the widget returning to the order form.

btcdirect('wallet-address-confirmation-canceled');

Events emitted by the widget ​

The widget also emits events. Listening to these events enables us to respond to specific state changes.

Order confirmation ​

When a user confirms his order in the order form, the user is redirected to the payment page of the selected payment provided (for example Adyen when selecting credit card). Before the redirect is executed an event is emitted containing the following information.

Event name: btcdirect-embeddable-fiat-to-coin-order-confirmed

// event.detail:
{
    currencyCode: 'iso:EUR', // The fiat currency code
    exchangeAmount: 100,     // The fiat amount that will be paid
    orderId: '123456789';    // The order ID
}

Wallet confirmation requested ​

When the setting walletConfirmationRequired is set to true in the init call, this event is emitted containing the following information.

Event name: btcdirect-embeddable-wallet-address-confirmation-requested

// event.detail:
{
    id: '123456789'; // The ID of the selected wallet
}

This ID is the ID of the provided wallet address in order to match these properly. See Provide wallet address(es) for more information.