Appearance

Sell Order Form (C2F) ​

Introduction ​

This document describes the steps to take in order to embed the BTC Direct sell 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.

html
<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/coin-to-fiat/coin-to-fiat.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.

KeyTypeDescriptionDefault
returnUrlstringThe url that is used in some places in the widget once the user is redirected to a specific external page of BTC Direct.The url of the page that the widget is loaded in.
useSameWindowForPaymentbooleanSetting this to false opens the IBAN verification page in a new window instead of navigating the current window to the IBAN verification page.true

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.

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

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.

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

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

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”.

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

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.

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

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

StatusDescription
successThe order has been processed successfully.
expiredThe order’s payment window has expired. Therefore the order is stopped.
cancelledThe order has been canceled by the user.
deniedThe order has been denied by the payment provider. This is usually when a user tries to pay for an order with insufficient funds.
failedThe order has failed for unknown reasons.

Transaction confirmation ​

This call is needed in order to fully complete the order. When the user has provided the needed data in the widget, an event is emitted from the widget to your application with data to create a transaction on the selected chain. This emitted event is described in the next chapter. Once the transaction is broadcasted and a transaction ID is available, it can be supplied to the widget which will add it to the order to finalize the process. More on the emitted event can be found in Events emitted by the widget.

js
btcdirect('transaction-id-confirmation', {
    orderId: '123456',
    transactionId: 'abcdef-123456789'
});

Canceling transaction confirmation ​

If for some reason the transaction cannot be continued (for example when the wallet doesn’t have enough funds) or the user cancels the process the transaction can be canceled.

js
btcdirect('coin-to-fiat-order-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 requested ​

When a user confirms his order in the order form, the widget provides the order details so that an actual transaction on the chain can be created.

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

js
// event.detail:
{
    currency: 'BTC',            // The cryptocurrency ticker
    amount : 0.1,               // The crypto amount that will be sold
    walletAddress: 'abc12',     // The address to send the coins to
    destinationTag: '123456',   // Optional destination tag (only for XRP orders)
    orderId: 123456,            // The ID of the order
    userWalletAddress: 'def34'; // The wallet address of the user
}

Made with ❤ by BTC Direct

Copyright © 2013-present BTC Direct Europe B.V.