Quick start: buy (F2C)

This guide walks you through creating your first fiat-to-coin checkout session. By the end, you will have a working checkout URL that redirects users to the BTC Direct payment page.

Prerequisites

• API credentials (username and password) from your account manager.
• A backend environment where you can make HTTP requests (Node.js, PHP, Python, etc.).
• A valid cryptocurrency wallet address for the selected coin.

Step 1: Authenticate

Call the POST /api/v1/authenticate endpoint with your partner credentials to get a JWT token.

curl -X POST https://api-sandbox.btcdirect.eu/api/v1/authenticate \
  -H "Content-Type: application/json" \
  -d '{"username": "YOUR_USERNAME", "password": "YOUR_PASSWORD"}'

Response:

{
  "token": "eyJ...",
  "refreshToken": "abc123..."
}

The token is valid for 1 hour. Use POST /api/v1/refresh to get a new token before it expires.

Try it out

Authenticate with your partner credentials to get a JWT token.

Request body { "username": "YOUR_USERNAME", "password": "YOUR_PASSWORD" }

POST /api/v1/authenticate Copy as curl

Response

Caution

Always authenticate from your backend. Never expose your credentials in frontend code.

Step 2: Create a checkout session

Call the POST /api/v2/buy/checkout endpoint with your JWT token and the order details.

curl -X POST https://api-sandbox.btcdirect.eu/api/v2/buy/checkout \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -d '{
    "baseCurrency": "BTC",
    "quoteCurrency": "EUR",
    "paymentMethod": "creditCard",
    "quoteCurrencyAmount": 50,
    "walletAddress": "bc1...",
    "returnUrl": "https://example.com/return"
  }'

Response:

{
  "checkoutUrl": "https://checkout.btcdirect.eu?...",
  "signature": "abc123...",
  "partner": "your-partner-slug",
  "baseCurrency": "BTC",
  "quoteCurrency": "EUR",
  "paymentMethod": "creditCard",
  "quoteCurrencyAmount": 50
}

Try it out

Create a checkout session. Replace the token and wallet address with your own values.

Authorization (partner JWT token) Request body { "baseCurrency": "BTC", "quoteCurrency": "EUR", "paymentMethod": "creditCard", "quoteCurrencyAmount": 50, "walletAddress": "bc1...", "returnUrl": "https://example.com/return" }

POST /api/v2/buy/checkout Copy as curl

Response

Required fields

Field	Description
baseCurrency	The cryptocurrency code (e.g. BTC, ETH). See supported currencies.
quoteCurrency	The fiat currency code. Currently only EUR.
paymentMethod	Case-sensitive payment method code. See payment methods.
quoteCurrencyAmount or baseCurrencyAmount	The order amount. Use one or the other, not both.
walletAddress	The destination wallet address. Required. Must be a mainnet address in all environments, including sandbox. See wallet addresses.

Note

The OpenAPI specification also accepts sourceCurrency and targetCurrency (CAIP-19 identifiers) as an alternative to baseCurrency and quoteCurrency. Use one pair or the other, not both. For most integrations, baseCurrency/quoteCurrency is the simplest option. See CAIP-19 support for details.

Optional fields

The checkout endpoint accepts several optional fields for common integration scenarios:

• Need to redirect users back to your app after checkout? See returnUrl.
• Want to link checkout sessions to records in your own system? See partnerOrderIdentifier.
• Can your product recognise the same person across visits (by user account, wallet, device, or any stable per-user reference)? See Linking your users to BTC Direct accounts so returning users skip the sign-in step on every checkout.
• Need users to act on a quote within a tighter window than the default? See expireTime.
• Already showed the quote in your own UI and want to skip the confirmation screen? See attemptDirectConfirm.

For the full list, see the checkout endpoint specification. To receive order status updates, set up webhooks.

Step 3: Redirect the user

Redirect your user to the checkoutUrl from the response. The BTC Direct hosted checkout page handles the rest: payment processing, user verification, and order completion.

After the user completes (or cancels) payment, they are redirected back to your returnUrl.

The checkout URL is valid for the duration of the selected payment method’s expiration period. After that, the URL expires and a new checkout session must be created.

Response fields

Field	Description
checkoutUrl	The URL to redirect your user to.
signature	A server-generated HMAC signature that protects the checkout URL against tampering (e.g. modified wallet address or amount). Generated automatically by the server. If the signature does not match on our end, the checkout is rejected.
partner	Your partner identifier, derived from your authenticated session.

Tip

Your API key is embedded in the checkout URL automatically by the server. You do not need to pass it as a request parameter.

Code examples

PHP

<?php
$authEndpoint = 'https://api-sandbox.btcdirect.eu/api/v1/authenticate';
$checkoutEndpoint = 'https://api-sandbox.btcdirect.eu/api/v2/buy/checkout';

// Step 1: Authenticate
$authData = json_encode(['username' => 'USERNAME', 'password' => 'PASSWORD']);
$authOptions = [
    'http' => [
        'header'  => "Content-type: application/json\r\n",
        'method'  => 'POST',
        'content' => $authData,
    ],
];
$authResponse = json_decode(file_get_contents($authEndpoint, false, stream_context_create($authOptions)), true);
$token = $authResponse['token'];

// Step 2: Create checkout
$checkoutData = json_encode([
    'baseCurrency' => 'BTC',
    'quoteCurrency' => 'EUR',
    'paymentMethod' => 'creditCard',
    'quoteCurrencyAmount' => 50,
    'walletAddress' => 'bc1...',
    'returnUrl' => 'https://example.com/return',
]);
$checkoutOptions = [
    'http' => [
        'header'  => "Content-type: application/json\r\nAuthorization: Bearer $token\r\n",
        'method'  => 'POST',
        'content' => $checkoutData,
    ],
];
$checkoutResponse = json_decode(file_get_contents($checkoutEndpoint, false, stream_context_create($checkoutOptions)), true);

// Step 3: Redirect
header('Location: ' . $checkoutResponse['checkoutUrl']);

Node.js

const AUTH_ENDPOINT = 'https://api-sandbox.btcdirect.eu/api/v1/authenticate';
const CHECKOUT_ENDPOINT = 'https://api-sandbox.btcdirect.eu/api/v2/buy/checkout';

// Step 1: Authenticate
const authResponse = await fetch(AUTH_ENDPOINT, {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify({ username: 'USERNAME', password: 'PASSWORD' }),
});
const { token } = await authResponse.json();

// Step 2: Create checkout
const checkoutResponse = await fetch(CHECKOUT_ENDPOINT, {
    method: 'POST',
    headers: {
        'Content-Type': 'application/json',
        'Authorization': `Bearer ${token}`,
    },
    body: JSON.stringify({
        baseCurrency: 'BTC',
        quoteCurrency: 'EUR',
        paymentMethod: 'creditCard',
        quoteCurrencyAmount: 50,
        walletAddress: 'bc1...',
        returnUrl: 'https://example.com/return',
    }),
});
const { checkoutUrl } = await checkoutResponse.json();

// Step 3: Redirect
res.redirect(checkoutUrl);