Skip to main content
Answers to common questions on the WhiteBIT on/off-ramp integration. For the flows and code, see the Integration guide; for access, onboarding, and positioning, see the Overview.

​
Access and activation

The POST /api/v4/main-account/fiat-deposit-url endpoint requires per-account activation and is not enabled by default. Request access through the account manager and provide the API key. Fiat operations also depend on completed Phase 2 institutional onboarding — see How to get started.
Fiat withdrawals require KYC verification; an account without KYC verification cannot process a fiat withdrawal. In exceptional, documented cases the institutional team can arrange a per-account override that permits fiat withdrawal without standard KYC. The override is exception-only, not a default capability — contact institutional@whitebit.com with the documented case. See Fiat withdrawal.

​
Fiat deposits

The uniqueId submitted in the fiat-deposit-url request must appear in the SEPA payment-reference field of the bank transfer. The transfer comes only from the partner’s own KYB’d bank account. WhiteBIT uses that string to match the incoming settlement to the original deposit request. A transfer without the reference, or with an altered one, may settle unmatched. See SEPA payment reference.
Take the request provider value from the Asset Status response, and confirm the enabled provider for SEPA EUR deposits on the account with the account manager.
The exact provider value for SEPA EUR deposits is confirmed per account during onboarding; read the current options from the Asset Status response rather than hardcoding a value.
For the VISAMASTER provider, the browser must send the Referer header when opening the invoice link. Messengers and email clients often strip the header, and without it WhiteBIT redirects the end user to the homepage instead of the payment provider. Test the redirect in the real delivery surface — mobile app, email link, or in-app web view — before go-live. See Card-provider flows.
Not every fiat ticker is depositable via API. Check can_deposit in the Asset Status response before generating an invoice; tickers without API deposit support run through the WhiteBIT web interface.

​
Fiat withdrawals

Both endpoints submit a withdrawal but differ in fee handling. POST /api/v4/main-account/withdraw treats amount as including the fee, so the recipient receives amount - fee. POST /api/v4/main-account/withdraw-pay charges the fee on top, so the recipient receives the exact amount specified. Select the endpoint that matches whether the specified amount is the debit or the credit.
Setting partialEnable: true raises the maximum limit for fiat withdrawals. Part of the withdrawal can then succeed, surfacing as the Partially successful status (18). The application must reconcile requestAmount against processedAmount in the history record and surface the remainder to operations. See the failure and exception paths.

​
Reconciliation and monitoring

Treat webhook delivery as best-effort. Failed deliveries are retried a small number of times spaced roughly an hour apart over a window of about one day, and there is no replay mechanism once that window closes. Pair webhooks with polling: query POST /api/v4/main-account/history (transactionMethod: 1 for deposits, 2 for withdrawals) on a regular cycle, and deduplicate against received events. See Webhooks and the reconciliation pattern.
The identifier is named differently across the API surface:Match on the correct casing per surface when reconciling across webhooks, history, and refunds.
Configure the webhook endpoint over HTTPS and authenticate each delivery by verifying the HMAC-SHA512 signature. See Webhooks for the verification flow.
WhiteBIT delivers webhooks from a fixed IP range. The account manager provides the range for allowlisting; the portal does not publish it.
Settlement windows and cutoff behavior depend on the fiat rail in use, including weekends and holidays. The account manager confirms the applicable windows for the account during onboarding.
No fixed settlement time is published; the timing for the specific rails enabled on the account is confirmed by the account manager.

​
Conversion

In both on/off-ramp flows, fiat enters and exits through the fiat deposit and withdrawal endpoints, and Convert converts between fiat and crypto — request a quote with POST /api/v4/convert/estimate, then execute it with POST /api/v4/convert/confirm before the quote expires. Convert through the API uses the Trade balance: transfer the funds from Main to Trade before the conversion, and transfer the converted amount back to Main before the withdrawal. See Convert balances.
Convert accepts the supported fiat currencies as either leg of a conversion.

​
Compliance

Inbound crypto deposits for EEA and Turkey accounts are held until Travel Rule verification completes — status 27 (awaiting originator data) and status 28 (data submitted, under review). No webhook fires for Travel Rule transitions, so the hold surfaces via history polling. Where the Travel Rule API is enabled, submit originator data through the deposit verification endpoint; otherwise notify the account holder to complete verification at whitebit.com. At status 28, wait while the data is under review. See Travel Rule.
Under MiCA, EEA accounts cannot deposit, withdraw, or create WhiteBIT Codes in USDT since December 30, 2024. Use USDC or EURI for the crypto leg. See Regulatory Compliance.

​
What’s next

Overview

Positioning, the two-phase access model, enablement gates, and how to apply.

Integration

The on-ramp and off-ramp flows, code, reconciliation, and failure paths.

Payment Integration

Endpoint-level lifecycle reference: statuses, fees, fiat operations, refunds.