Linking your users to BTC Direct accounts

Pass an optional identifier on the checkout call to link the user in your system to their BTC Direct account. Once linked, returning users skip the BTC Direct sign-in screen on every following checkout, and orders, callbacks, and user-level API calls trace back to the same person on your side.

What you get

• No re-login. Returning users skip the BTC Direct sign-in screen on every checkout. They go from your app straight to the payment step.
• Traceability. Orders, status callbacks, and follow-up API calls map cleanly back to the same person in your system.
• One-step setup. No separate register-identifier call needed; pass the identifier on the checkout request you’re already making.

When to use this

Pass an identifier whenever you can recognise the same person across visits. The recogniser does not have to be a user account in the traditional sense. Anything stable per user works.

Example	What you pass as identifier
Platforms with user accounts (exchanges, custodial services, brokers)	Your user UUID, account ID, or opaque user reference from your auth system.
Hardware wallet apps	A hash of the user’s XPUB, device serial, or wallet UUID. You may have no name and no email on your side, and that’s fine: BTC Direct collects the user details on signup, you only need to provide the recogniser.
Self-custodial wallets and dapps	A wallet address, public key, or session-bound wallet identifier. The user owns the wallet across visits, so the identifier stays stable.
Repeat customers	Whatever identifier you already have. The user buys BTC today, ETH next month, sells ETH next year, and every checkout opens straight to their BTC Direct account with no sign-in.
Affiliate or loyalty tracking	A user or wallet reference. You can tie purchase volume to a specific person without joining on email or name.
Customer support and reporting	The same record key you already use. Support agents and dashboards see BTC Direct orders mapped to the user record they already know.

The point: the identifier is your side’s recogniser, not the user’s identity. BTC Direct still collects email and KYC on signup; you don’t need to know any of that.

If your product genuinely can’t recognise the same person across visits (a pure embedded widget on an anonymous landing page, for example), omit the field. Users sign in or sign up on the BTC Direct page as before and the checkout still works.

How it works

1. Pick an identifier per user. 36 to 255 characters. Use something stable for the lifetime of the user (a UUID, hashed wallet key, or opaque user reference) and unique per user. It travels in the checkout URL in clear text, so don’t use anything sensitive on its own.
2. Pass it as identifier on POST /api/v2/buy/checkout.
3. BTC Direct embeds it in the returned checkoutUrl.
4. On the checkout page:
   • First-time user: they sign up on the checkout page. The identifier is linked to their new BTC Direct account during signup.
   • Returning user: the identifier is already linked, so the sign-in screen is skipped and they continue straight to checkout.
5. For any later direct API call on behalf of that user, authenticate them with the same identifier in the User-Identifier header. See User authentication, Option 2.

Example

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...",
    "identifier": "partner-unique-user-id-at-least-36-characters-long"
  }'

Try it out

Create a checkout session linked to a partner-supplied user identifier.

Authorization (partner JWT token) Request body { "baseCurrency": "BTC", "quoteCurrency": "EUR", "paymentMethod": "creditCard", "quoteCurrencyAmount": 50, "walletAddress": "bc1...", "identifier": "partner-unique-user-id-at-least-36-characters-long" }

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

Response

Constraints

Rule	Detail
Length	36 to 255 characters. Shorter values return ER102.
Type	String. Other types return ER053.
Empty string	Treated as invalid (returns ER053 / ER102). Omit the field if you have no identifier for this user.
Stability	Must be stable for the lifetime of the user. Changing it for the same person creates a new, unlinked BTC Direct account.
Uniqueness	Must be unique per user. Reusing the same identifier across different users would point them all at the same BTC Direct account.

After checkout: calling user endpoints

Once the identifier is linked, you can call user-level endpoints (order history, user info, payment accounts) by sending the identifier as a header. The full pattern is documented under User authentication, Option 2; the short version is:

Authorization: Bearer {partner_token}
User-Identifier: {identifier}

No separate user-login token round-trip needed.

Common pitfalls

Caution

Don’t regenerate identifiers per checkout. A fresh identifier per checkout creates a fresh BTC Direct account each time and defeats the auto-login. Persist one identifier per user on your side and reuse it forever.

Caution

Don’t put PII (emails, names, IBANs) directly in the identifier. It travels in the checkout URL. Hash, encrypt, or use an opaque reference.

Note

The identifier is not part of the signed checkout fields. The cryptographic signature protects the financial parameters (amount, currencies, wallet address); the identifier is the partner-side user link and is intentionally outside that scope.

Migrating from register-identifier

If your integration today calls POST /api/v1/user/register-identifier before redirecting the user to checkout, you can drop that call and pass the same identifier directly on POST /api/v2/buy/checkout. Behaviour for new and returning users is identical; the only difference is one fewer round-trip.

The legacy register-identifier endpoint stays available and continues to work for non-checkout flows.