> ## Documentation Index
> Fetch the complete documentation index at: https://docs.whitebit.com/llms.txt
> Use this file to discover all available pages before exploring further.
# Create express withdraw token
> Create a single-use Express Withdraw payment token that charges a WhiteBIT user's balance to the partner's Main balance instantly and off-chain via the V4 API.
The endpoint is available only for B2B partner services and requires a separate approval process. Request access at [https://institutional.whitebit.com/](https://institutional.whitebit.com/).
## Payment flow
The partner integrates one endpoint; WhiteBIT hosts everything the paying user sees.
1. The partner creates a payment token with the currency, the amount, and a partner-side `externalId`.
2. The partner presents the returned `url` to the user — redirect, deep link, or QR code.
3. The user opens the URL while authenticated on WhiteBIT and confirms the displayed [ticker](/glossary#ticker) and amount on the WhiteBIT-hosted confirmation surface.
4. WhiteBIT debits the user's balance and credits the partner's Main balance in a single internal, off-chain, zero-fee transfer, then marks the token used.
Each token expires 90 seconds after creation — `expireAt` in the response carries the authoritative expiry. Create the token as close as possible to the moment of presenting the URL to the user; after expiry, re-create the token with the same `externalId` to receive a fresh one.
Each payment is capped at the equivalent of 10,000 USDT, enforced at token creation and re-enforced at confirmation. Requests above the cap return error code `191`.
## Notes
* For the full integration walkthrough — token lifecycle, idempotency, and limits — see the [Express Withdraw section of the Payment Integration guide](/guides/payment-integration#express-withdraw-payments).
* The endpoint does not support pagination.
## OpenAPI
````yaml openapi/private/main_api_v4.yaml POST /api/v4/main-account/express-withdraw/token
openapi: 3.0.3
info:
title: WhiteBIT Private HTTP API V4
description: |
WhiteBIT Private HTTP API V4 for Main balance changes.
Base URL: https://whitebit.com
All endpoints return time in Unix-time format.
All endpoints return either a JSON object or array.
For receiving responses from API calls please use http method POST.
version: 4.0.0
contact:
name: WhiteBIT Support
email: support@whitebit.com
url: https://whitebit.com
servers:
- url: https://whitebit.com
description: WhiteBIT Global Server
- url: https://whitebit.eu
description: WhiteBIT EU Server
security:
- ApiKeyAuth: []
PayloadAuth: []
SignatureAuth: []
tags:
- name: Main Account
description: Main account balance and operations
- name: Deposit
description: Cryptocurrency and fiat deposit operations
- name: Withdraw
description: Cryptocurrency and fiat withdrawal operations
- name: Transfer
description: Balance transfer operations
- name: Codes
description: WhiteBIT codes operations
- name: Crypto Lending - Fixed
description: Fixed crypto lending plans
- name: Crypto Lending - Flex
description: Flexible crypto lending plans
- name: Fees
description: Fee information
- name: Sub-Account
description: Sub-account management
- name: Sub-Account API Keys
description: Sub-account API key management
- name: Mining Pool
description: Mining pool operations
- name: Credit Line
description: Credit line information
- name: JWT
description: JWT token management
- name: Travel Rule
description: Travel Rule compliance endpoints for deposits and withdrawals
paths:
/api/v4/main-account/express-withdraw/token:
post:
tags:
- Withdraw
summary: Create express withdraw token
description: >
The endpoint creates a signed, single-use Express Withdraw payment token
that charges a specific amount from a WhiteBIT user's balance to the
partner's [Main balance](/glossary#balance-main) in an instant,
off-chain, zero-[fee](/glossary#fee) internal transfer. The response
returns a URL that embeds the token; the paying user confirms the exact
[ticker](/glossary#ticker) and amount on the WhiteBIT-hosted
confirmation surface.
Token and payment constraints:
- Each token is single-use: WhiteBIT marks the token used at
confirmation and rejects any replay.
- Each token expires 90 seconds after creation; the `expireAt` response
field carries the authoritative expiry timestamp. Generate the token as
close as possible to the moment of presenting the URL to the user.
- The [ticker](/glossary#ticker) must be a withdrawal-enabled
cryptocurrency; the endpoint rejects [fiat](/glossary#fiat) tickers.
- Each payment is capped at the equivalent of 10,000 USDT; WhiteBIT
enforces the cap at token creation and re-enforces the cap at
confirmation.
- WhiteBIT rejects self-payments: the paying user and the token creator
must be different WhiteBIT accounts.
- The endpoint is idempotent per `externalId`: re-submitting the same
`externalId` with an identical `ticker` and `amount` while the token is
still valid returns the same token instead of creating a duplicate
charge. After the token expires, the same `externalId` receives a fresh
token.
Standard private-API rate limits apply — see [Rate
limits](/api-reference/rate-limits). The endpoint carries no
endpoint-specific limit.
operationId: createExpressWithdrawToken
requestBody:
required: true
content:
application/json:
schema:
type: object
required:
- ticker
- amount
- externalId
- request
- nonce
properties:
ticker:
type: string
description: >
Currency [ticker](/glossary#ticker) to charge. Example: USDT
⚠️ The ticker must be a withdrawal-enabled cryptocurrency;
the endpoint rejects [fiat](/glossary#fiat) tickers. Use
[Asset Status endpoint](/public/http-v4/asset-status-list)
to check the withdrawal status of a currency.
example: USDT
amount:
type: string
description: >
Amount to charge in the specified
[ticker](/glossary#ticker). Numeric string.
⚠️ The amount converted to USDT-equivalent must not exceed
10,000; the endpoint rejects larger amounts with error code
`191`.
example: '25.50'
externalId:
type: string
description: >
Partner-side reference for the payment (order or invoice
identifier), unique per partner account. The identifier
powers idempotency and replay protection: a pending
`externalId` with an identical `ticker` and `amount` returns
the same token; the endpoint rejects an already-paid
`externalId` with error code `19`.
example: order-100294
request:
type: string
description: Request signature
example: '{{request}}'
nonce:
type: integer
description: Unique request identifier
example: 1594297865000
examples:
expressWithdraw:
summary: Express Withdraw payment token
value:
ticker: USDT
amount: '25.50'
externalId: order-100294
request: '{{request}}'
nonce: 1594297865000
responses:
'201':
description: >-
Token created. Present the returned URL to the paying user before
the expiry in `expireAt`.
content:
application/json:
schema:
type: object
properties:
url:
type: string
description: >
URL to present to the paying user (redirect, deep link, or
QR code). The value is the WhiteBIT-hosted web
confirmation page by default, or a mobile deep link when
one is configured for the partner at onboarding; in both
cases the unique token travels in the `token` query
parameter. Treat the value as opaque.
example: https://whitebit.com/express-withdraw?token=8f3c0a7d4e21
expireAt:
type: string
description: >
Absolute token expiry timestamp in `YYYY-MM-DD HH:MM:SS`
format (UTC). The authoritative expiry: each token expires
90 seconds after creation.
example: '2026-07-10 12:34:56'
example:
url: https://whitebit.com/express-withdraw?token=8f3c0a7d4e21
expireAt: '2026-07-10 12:34:56'
'403':
description: >
The account does not have the Express Withdraw permission. WhiteBIT
grants the permission through the B2B partner approval process —
request access at https://institutional.whitebit.com/.
'422':
description: >
Inner validation failed.
Business-rule codes (returned with HTTP 422):
- 18 - token invalid: a pending `externalId` re-submitted with a
different `ticker` or `amount`. Parameters of a pending payment
cannot change — use a new `externalId`.
- 19 - token already used: the `externalId` belongs to a payment the
user already confirmed.
- 191 - amount exceeds the limit: the amount converts to more than
the 10,000 USDT-equivalent per-payment cap.
Additional outcomes returned with HTTP 422:
- **Currency not allowed** — the [ticker](/glossary#ticker) is
[fiat](/glossary#fiat) or not withdrawal-enabled; the error is keyed
to the currency field.
- **Unexpected server-side error** — a generic "Please try again
later" message; retry the request.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorInner'
components:
schemas:
ErrorInner:
type: object
properties:
code:
type: integer
message:
type: string
errors:
type: object
additionalProperties:
type: array
items:
type: string
securitySchemes:
ApiKeyAuth:
type: apiKey
in: header
name: X-TXC-APIKEY
description: The public WhiteBIT API key.
PayloadAuth:
type: apiKey
in: header
name: X-TXC-PAYLOAD
description: Base64-encoded JSON request body.
SignatureAuth:
type: apiKey
in: header
name: X-TXC-SIGNATURE
description: >-
HMAC-SHA512 signature of the payload, hex-encoded. Computed as
hex(HMAC-SHA512(payload, api_secret)).
````