On/Off-Ramp Integration Guide

​

Prerequisites

• Completed institutional onboarding with approved fiat access — a separate, non-automatic phase after KYB; see How to get started on the overview page.
• Per-account enablement gates — the fiat deposit invoice endpoint, API deposits for each provider on the bank-details route, dedicated deposit addresses, and Express Withdraw are enabled per account. Confirm the invoice endpoint, the provider access, and Express Withdraw with the account manager; for dedicated deposit addresses, see Unique address per user. Express Withdraw is optional. It applies only when a WhiteBIT user pays a crypto amount from a WhiteBIT balance, and the amount settles off-chain in the partner’s Main balance — see Express Withdraw payments.
• API access — HMAC-signed requests on the main account.
• Convert terms — before the first conversion, the account owner accepts the Convert terms once on whitebit.com. See Convert.

​

On-ramp flow: fiat in, crypto out

# Generate a fiat deposit invoice (provider value from Asset Status)
curl -X POST "https://whitebit.com/api/v4/main-account/fiat-deposit-url" \
  -H "Content-Type: application/json" \
  -H "X-TXC-APIKEY: YOUR_API_KEY" \
  -H "X-TXC-PAYLOAD: YOUR_PAYLOAD" \
  -H "X-TXC-SIGNATURE: YOUR_SIGNATURE" \
  -d '{
    "ticker": "EUR",
    "provider": "PROVIDER",
    "amount": "100",
    "uniqueId": "deposit-2026-000123",
    "request": "/api/v4/main-account/fiat-deposit-url",
    "nonce": 1594297865000
  }'

import base64, hashlib, hmac, json, time, requests

API_KEY, API_SECRET = "YOUR_API_KEY", "YOUR_SECRET"
endpoint = "/api/v4/main-account/fiat-deposit-url"
# provider value from the Asset Status response
body = json.dumps({
    "ticker": "EUR",
    "provider": "PROVIDER",
    "amount": "100",
    "uniqueId": "deposit-2026-000123",
    "request": endpoint,
    "nonce": int(time.time() * 1000),
})
payload = base64.b64encode(body.encode()).decode()
signature = hmac.new(API_SECRET.encode(), payload.encode(), hashlib.sha512).hexdigest()
response = requests.post(
    "https://whitebit.com" + endpoint,
    headers={"Content-Type": "application/json", "X-TXC-APIKEY": API_KEY,
             "X-TXC-PAYLOAD": payload, "X-TXC-SIGNATURE": signature},
    data=body,
)
print(response.json())  # {"url": "..."}

• SEPA payment reference. WhiteBIT accepts bank transfers only from the partner’s own KYB’d bank account. The uniqueId of the fiat-deposit-url request must appear in the SEPA payment-reference field of the transfer. A transfer without the reference, or with an altered one, may settle unmatched — see SEPA payment reference.
• Redirect links. successLink and failureLink require feature activation through the account manager, and WhiteBIT validates the destination domain; returnLink needs no activation.
• Card flows. Card funding in USD or EUR (the VISAMASTER provider) requires a customer billing block, and the browser must send the Referer header when opening the invoice link — messengers and email clients often strip it. See Card-provider flows.
• Web-only currencies. Not every fiat ticker is depositable via API; confirm can_deposit in the Asset Status response before generating an invoice, and route unsupported tickers through the WhiteBIT web interface.

​

SEPA deposit from the partner’s bank account

​

Off-ramp flow: crypto in, fiat out

{
  "ticker": "EUR",
  "amount": "500",
  "address": "DE89370400440532013000",
  "bankBic": "DEUTDEFF",
  "beneficiary": {
    "firstName": "Firstname",
    "lastName": "Lastname"
  },
  "provider": "SEPA_BCB_GROUP",
  "uniqueId": "24529046",
  "request": "/api/v4/main-account/withdraw",
  "nonce": 1594297865000
}

• Partial withdrawals. partialEnable: true raises the maximum limit for fiat withdrawals; the application must then handle the Partially successful status (18) and reconcile requestAmount against processedAmount in the history record.
• KYC. Fiat withdrawals require KYC verification. In exceptional, documented cases the institutional team can arrange a per-account override — see Fiat withdrawal.

​

Reconciliation and monitoring

​

Failure and exception paths

​

What’s next