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. Contact WhiteBIT support and provide the API key to request access. 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. WhiteBIT uses that string to match the incoming settlement to the original deposit request. If the end user omits or alters the reference, the deposit may settle unmatched and require manual reconciliation through institutional support. Validate the reference field in the payment UX. 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. The withdrawal can then complete partially, 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 rather than by source IP. See Webhooks for the verification flow.
Whether the outbound delivery IP addresses are stable and publishable for allowlisting is confirmed with the account manager; the portal does not publish a fixed list.
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 conversion runs on the crypto side of the balance — request a quote with POST /api/v4/convert/estimate, then execute it with POST /api/v4/convert/confirm before the quote expires. The convert service routes balances internally; no manual Main↔Trade transfers are required. See Convert.
Whether Convert accepts a fiat ticker directly as the conversion leg is confirmed per account; the conversion pairs available to the account are set with the account manager.

​
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 complete verification on the platform. 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.