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.

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

Key	Type	Description	Default value
`returnUrl`	`string`	The 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.
`useSameWindowForPayment`	`boolean`	Setting this to `false` opens the payment page in a new window instead of navigating the current window to the payment page.	`true`
`walletConfirmationRequired`	`boolean`	If the order needs to be confirmed via a wallet. If set to true, a message will be emitted from the widget when the user confirms the order. This needs to be caught and additional information has to be provided to the widget after confirmation on your wallet. See Events emitted by the widget for more information.	`false`

All widgets support selector, debug, locale and theme.

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.

Set parameters

This call enables you to prefill all that is needed to make a fiat to coin order. All parameters are optional so you only have to add the information you want to have prefilled.

btcdirect('set-parameters', {
    baseCurrency: 'BTC',
    quoteCurrency: 'EUR',
    baseCurrencyAmount: 0.001,
    quoteCurrencyAmount: 123,
    paymentMethod: 'creditCard',
    walletAddress: '3FZbgi29cpjq2GjdwV8eyHuJJnkLtktZc5',
    walletAddressTag: '1513155290',
    signature: '67890fghij',
    returnUrl: 'https://btcdirect.eu',
    callbackUrl: 'https://btcdirect.eu',
    partnerOrderIdentifier: '12345abcde',
    fee: 0.5,
    expiryDateTime: 1701423182,
    fixedAmount: true,
    fixedCurrency: true,
    fixedPaymentMethod: true,
    showWalletAddress: true
});

The below table provides more information about each parameter that can be set.

Key	Type	Description
`baseCurrency`	`string`	The cryptocurrency to preselect
`quoteCurrency`	`string`	The fiat currency to preselect
`baseCurrencyAmount`	`number`	The crypto amount to prefill
`quoteCurrencyAmount`	`number`	The fiat amount to prefill
`paymentMethod`	`string`	The payment method to preselect
`walletAddress`	`string`	The wallet address of the user
`walletAddressTag`	`string`	The destination tag of the wallet (if applicable)
`signature`	`string`	See sub-chapter "Offer API call parameters" below for more information
`returnUrl`	`string`	The url to return to when clicking the "Back to partner" buttons in the flow
`callbackUrl`	`string`	The url where updates on the order will be sent to
`partnerOrderIdentifier`	`string`	Your order ID (if applicable)
`fee`	`number`	A specific fee for this order (as a percentage)
`expiryDateTime`	`string`	See sub-chapter "Offer API call parameters" below for more information
`fixedAmount`	`boolean`	Lock the amounts so they cannot be changed
`fixedCurrency`	`boolean`	Lock the currencies so they cannot be changed
`fixedPaymentMethod`	`boolean`	Lock the payment method so it cannot be changed
`showWalletAddress`	`boolean`	Show or hide the wallet address of the user

TIP

Note that when providing one of the following parameters, the signature becomes a required field:

walletAddress
fee
returnUrl
callbackUrl :::

INFO

Note that if both baseCurrencyAmount and quoteCurrencyAmount are set, only the quoteCurrencyAmount will be used to prevent mismatch between these when quoting.

Offer API call parameters

The following parameters are mainly used for the Unified checkout flow, but can also be provided to the widget to trigger certain settings or functionalities.

Signature

When using the API to create an offer, the response contains a signature. This signature can be sent to the widget to make sure the same offer will be used for this order.

ExpiryDateTime

When using the API to create an offer, the response contains an expiry date. This Unix timestamp value is used to determine if the offer is not expired.

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' });

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

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.

Payment method	Value to add
Bancontact	bancontact
Bank transfer	bankTransfer
Credit card	creditCard
Giropay	giropay
iDeal	iDeal
Sofort Banking	sofort
Apple Pay	applepay

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:

Status	Description
success	The order has been processed successfully.
expired	The order’s payment window has expired. Therefore the order is stopped.
cancelled	The order has been canceled by the user.
denied	The order has been denied by the payment provider. This is usually when a user tries to pay for an order with insufficient funds.
failed	The order has failed for unknown reasons.

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 wallet 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');

Skip the order form

To shorten the payment flow for users, you can call attempt-direct-confirm with enableAttemptDirectConfirm set to True. This checks whether the widget has received all the required data to skip the initial order form. The following values must be provided to the widget:

A fiat or crypto amount
A supported crypto currency
A valid wallet address
A supported payment method

If any of these values are incorrect or missing, the widget will be unable to skip the order form. In such cases, the user will be notified about the fields that are invalid.

btcdirect('attempt-direct-confirm', {
    enableAttemptDirectConfirm: true
});

Show additional fees

By default, the following fees are visible to users:

Payment fees
Network fees

To display additional partner fees, such as:

BTC Direct fees
Partner fees (your fees)

You can use the following configuration:

btcdirect('show-additional-fees', {
    show: true
});

Include DCA

The feature below adds an additional tab to the Fiat to Coin widget, which includes the full Dollar Cost Averaging (DCA) widget.

btcdirect('include-dca', {
    include: true
});

By default, the Fiat to Coin widget opens with the "Fiat to Coin" tab active. However, you can override this behavior by using the ?recurring=true parameter in the widget URL.

The widget also emits events. Listening to these events enables you 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.

Buy Order Form (F2C)

Introduction

Implementing the widget

Important: Provide wallet address(es)

Optional init call parameters

Additional calls to the widget

Set parameters

Offer API call parameters

Signature

ExpiryDateTime

Locale

Currencies

Order information

Payment method

Callback url

Wallet address confirmation

Canceling wallet address confirmation

Skip the order form

Show additional fees

Include DCA

Events emitted by the widget

Order confirmation

Wallet confirmation requested

Buy Order Form (F2C) ​

Introduction ​

Implementing the widget ​

Important: Provide wallet address(es) ​

Optional init call parameters ​

Additional calls to the widget ​

Set parameters ​

Offer API call parameters ​

Signature ​

ExpiryDateTime ​

Locale ​

Currencies ​

Order information ​

Payment method ​

Callback url ​

Wallet address confirmation ​

Canceling wallet address confirmation ​

Skip the order form ​

Show additional fees ​

Include DCA ​

Events emitted by the widget ​

Order confirmation ​

Wallet confirmation requested ​

Buy Order Form (F2C)

Introduction

Implementing the widget

Important: Provide wallet address(es)

Optional init call parameters

Additional calls to the widget

Set parameters

Offer API call parameters

Signature

ExpiryDateTime

Locale

Currencies

Order information

Payment method

Callback url

Wallet address confirmation

Canceling wallet address confirmation

Skip the order form

Show additional fees

Include DCA

Events emitted by the widget

Order confirmation

Wallet confirmation requested