Z Zise Developers
/
简体中文
Stablecoin Account › API Reference › Withdrawals

Debit a withdrawal (available → withdrawing)

POST /v1/withdrawals scope: withdrawals:write
On behalf of a member · x-on-behalf-of required Requires x-idempotency-key Moves funds · Decreases member available balance and increases withdrawing by the same amount; merchant.custody is unchanged.
This endpoint moves funds

See the response table below for failure handling. Retry timeouts (504) with the same idempotency key — we may already have processed the request; use a new key after a business failure; the same key replays that failure.

Moves member funds from available into withdrawing. They are no longer spendable, but merchant.custody does not change: you still hold the funds and still owe them to the member.

This must happen before sending on-chain because the member's balance must actually decrease in our ledger; otherwise the same funds could be spent again on our remittance, exchange, card, or wealth products. After successful on-chain payment, call POST /v1/withdrawals/{id}/confirm; on failure, call .../fail to return funds to available. There is no third path. Funds never leave withdrawing on their own; without your action they remain there indefinitely.

⚠⚠ Known discrepancy: do not base your product design on it

This endpoint currently accepts to_address directly from the body, without checking the address book, enforcing a 24-hour cooling period, or requiring step-up authentication. The design rules for the main member flow instead state that the address book is the sole source of withdrawal addresses and the flow has no free-address input. The implementation and those rules differ here.

The owner has decided to remove member deposits and withdrawals from the merchant-facing surface, so this endpoint may be retired. Until then, call GET /v1/withdraw-addresses yourself to obtain a registered member address with usable=true, then use it as to_address. Do not treat this endpoint as permission to enter any arbitrary address.

── We may disable this business line ──

This endpoint follows your withdraw business-line switch, the same one shown in GET /v1/merchant/lines. If it is not enabled, manually halted, or automatically halted because prepayment falls below the low-balance threshold, returns 400 service_unavailable and does not queue. This is an immediate-execution line with no automatic continuation after you replenish funds; the debit either succeeds or fails immediately.

Check GET /v1/merchant/lines first. halted=true clears in the next sweep after replenishing prepayment; enabled=false requires your account manager. ⚠ Already locked orders are unaffected: confirm / fail remain callable. Halting prevents new orders; it does not trap existing orders in withdrawing.

Prerequisites

  • The asset is in the platform catalog and enabled.
  • The member's available balance in this asset ≥ amount.
  • The member is not banned, blocklisted, or frozen.
  • Your withdraw business line is enabled and not halted, and the merchant's asset account is in normal status.
FieldTypeRequiredDescription
x-on-behalf-of string Required The member whose balance to debit.
x-idempotency-key string Required UUID. This key is the only protection against duplicate debits. Unlike deposits, this endpoint has no business reference like reference. Retrying with a new key creates a second actual debit.

Request Body

FieldTypeRequiredDescription
asset string Required Asset code, automatically uppercased. Outside the catalog returns asset_not_allowed.
amount string Required Amount to debit, required to be > 0. Fixed-point string using the asset's ledger_scale; excess decimal places with any excess digit other than 0 immediately return 400.For USDT (ledger_scale=6), for example 200.000000.
to_address string Required Destination address, ≤ 200 characters. Snapshotted unchanged into the order row; subsequent queries return that immutable version. ⚠ This endpoint does not validate address format, check the address book, or enforce cooling periods; see Known discrepancy above. Validation is your responsibility.

Response

201Debited; awaiting your on-chain payment.
{
  "id": "wdr_9f1c0b2a-4d33-4a51-9f2e-7c1b0a5d6e88",
  "status": "locked",
  "asset": "USDT",
  "amount": "200.000000",
  "ledger_scale": 6,
  "to_address": "0x5aAeb6053F3E94C9b9A09f33669435E7Ef1BeAed"
}
400invalid_request: missing fields, invalid amount, or address longer than 200 characters. asset_not_allowed: asset outside the catalog. insufficient_balance: insufficient member available balance. limit_exceeded: member-level limit reached (limit_scope = member). request_rejected: blocked by platform eligibility checks; reason is not disclosed. service_unavailable: your withdraw line is disabled or halted, or the merchant's asset account is restricted. Retrying unchanged will not help; inspect GET /v1/merchant/lines first.
409idempotency_key_reused · idempotency_in_progress
Request 
curl -X POST 'https://api.zinfra.vip/v1/withdrawals' \
  -H 'x-auth-token: Bearer $TOKEN' \
  -H 'x-on-behalf-of: $MEMBER_ID' \
  -H 'x-idempotency-key: $IDEMPOTENCY_KEY' \
  -H 'content-type: application/json' \
  -d '{
    "asset": "USDT",
    "amount": "200.000000",
    "to_address": "0x5aAeb6053F3E94C9b9A09f33669435E7Ef1BeAed"
  }'
const res = await fetch("https://api.zinfra.vip/v1/withdrawals", {
  method: "POST",
  headers: {
    "x-auth-token": "Bearer $TOKEN",
    "x-on-behalf-of": "$MEMBER_ID",
    "x-idempotency-key": "$IDEMPOTENCY_KEY",
    "content-type": "application/json",
  },
  body: JSON.stringify({
    "asset": "USDT",
    "amount": "200.000000",
    "to_address": "0x5aAeb6053F3E94C9b9A09f33669435E7Ef1BeAed"
  }),
});
// Keep monetary amounts as strings, never numbers.
const data = await res.json();
import requests

res = requests.post(
    "https://api.zinfra.vip/v1/withdrawals",
    headers={
        "x-auth-token": "Bearer $TOKEN",
        "x-on-behalf-of": "$MEMBER_ID",
        "x-idempotency-key": "$IDEMPOTENCY_KEY",
        "content-type": "application/json",
    },
    json={
      "asset": "USDT",
      "amount": "200.000000",
      "to_address": "0x5aAeb6053F3E94C9b9A09f33669435E7Ef1BeAed"
    },
)
# Use Decimal(str(...)) for amounts, not float.
data = res.json()
req, _ := http.NewRequest("POST", "https://api.zinfra.vip/v1/withdrawals",
    strings.NewReader(`{
  "asset": "USDT",
  "amount": "200.000000",
  "to_address": "0x5aAeb6053F3E94C9b9A09f33669435E7Ef1BeAed"
}`))
req.Header.Set("x-auth-token", "Bearer $TOKEN")
req.Header.Set("x-on-behalf-of", "$MEMBER_ID")
req.Header.Set("x-idempotency-key", "$IDEMPOTENCY_KEY")
req.Header.Set("content-type", "application/json")
res, err := http.DefaultClient.Do(req)
// Decode amount fields as string, not float64.
HttpRequest req = HttpRequest.newBuilder()
    .uri(URI.create("https://api.zinfra.vip/v1/withdrawals"))
    .header("x-auth-token", "Bearer $TOKEN")
    .header("x-on-behalf-of", "$MEMBER_ID")
    .header("x-idempotency-key", "$IDEMPOTENCY_KEY")
    .header("content-type", "application/json")
    .method("POST", HttpRequest.BodyPublishers.ofString("""
{
  "asset": "USDT",
  "amount": "200.000000",
  "to_address": "0x5aAeb6053F3E94C9b9A09f33669435E7Ef1BeAed"
}
"""))
    .build();
// Use String / BigDecimal for amounts, not double.
$ch = curl_init('https://api.zinfra.vip/v1/withdrawals');
curl_setopt_array($ch, [
  CURLOPT_CUSTOMREQUEST => 'POST',
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_HTTPHEADER => [
    'x-auth-token: Bearer $TOKEN',
    'x-on-behalf-of: $MEMBER_ID',
    'x-idempotency-key: $IDEMPOTENCY_KEY',
    'content-type: application/json',
  ],
  CURLOPT_POSTFIELDS => <<<'JSON'
{
  "asset": "USDT",
  "amount": "200.000000",
  "to_address": "0x5aAeb6053F3E94C9b9A09f33669435E7Ef1BeAed"
}
JSON,
]);
$res = curl_exec($ch);
// Use bcmath / strings for amounts, not floatval.
201 
{
  "id": "wdr_9f1c0b2a-4d33-4a51-9f2e-7c1b0a5d6e88",
  "status": "locked",
  "asset": "USDT",
  "amount": "200.000000",
  "ledger_scale": 6,
  "to_address": "0x5aAeb6053F3E94C9b9A09f33669435E7Ef1BeAed"
}