docs
Español

Esta página aún no está traducida y se muestra en inglés.

En esta página

Withdrawals (payouts) — /v1/withdrawals

Pay USDT out of your business's Hot Wallet to a customer's or partner's address from your server, e.g. a player cash-out or a refund. The API uses the same engine as the dashboard: every limit, approval and safety check below applies to API withdrawals too.

Requirements

WhatWhere
Business in Full mode with a verified Hot WalletDashboard → Businesses (polysiad business full-mode)
API withdrawals switched on (default off)Dashboard → Businesses → Withdrawals → Allow withdrawals through the merchant API (admin; audited)
An API key with scope withdrawals:write (and withdrawals:read for GET)Dashboard → API → New API key, or polysiad apikey create … -scopes withdrawals:read,withdrawals:write -ip 203.0.113.10
The key must have an IP allowlistRefused at creation without one; a key without one gets 403 ip_allowlist_required

Withdrawal scopes are never part of the default scopes — an invoice key cannot move money. Use a separate key for payouts, kept on the server that sends them, and restrict it to that server's IP address(es).

Optional per-key limits (set when the key is created): max per withdrawal and daily limit (UTC day). They are checked in addition to the business limits.

Create — POST /v1/withdrawals

FieldType
tostringPolygon address (0x…, 40 hex). Checksum is not required
amountstringUSDT decimal, max 6 decimals ("25.50"). Not a JSON number
customer_idstring, optionalYour user id (≤ 128 printable characters). Enables the per-customer daily limit
referencestring, optionalYour own reference (≤ 128), e.g. your cash-out id. Returned in the object and webhooks

Idempotency-Key header is required (1–64 visible ASCII characters). Retrying with the same key and body returns the same withdrawal (200, header Idempotent-Replayed: true) — never a second payout. The same key with a different body is 422 idempotency_key_reused. Generate the key when you create the cash-out on your side and store it with it.

curl -sS "$API/v1/withdrawals" \
  -H "Authorization: Bearer $POLYSIA_PAYOUT_KEY" \
  -H "Idempotency-Key: cashout-88213" \
  -H "Content-Type: application/json" \
  -d '{"to":"0xCustomerPolygonAddress","amount":"25.50","customer_id":"user-7","reference":"cashout-88213"}'
{ "object": "withdrawal", "id": "wd_8f2c0a1b9d3e4f5a6b7c8d9e0f1a2b3c", "status": "approved",
  "to": "0xCustomerPolygonAddress", "amount": "25.500000", "amount_units": "25500000",
  "customer_id": "user-7", "reference": "cashout-88213", "idempotency_key": "cashout-88213",
  "approvals_required": 0, "reason": null, "tx_hash": null, "source": "api",
  "created_at": "2026-11-19T10:00:00Z", "sent_at": null, "completed_at": null }

201 = created. The payout is sent by the running Polysia daemon a few seconds later; follow it with webhooks or GET.

Status

StatusMeaningFinal?
awaiting_approvalAbove the manual threshold, auto withdrawals off, or a possible address-poisoning match — an admin must approve in the dashboard (2FA; maker ≠ checker)no
approvedWill be sent by the daemonno
waiting_fundsHot Wallet balance too low; a sweep was forced and it is re-checked every 5 sno
broadcastTransaction sent, not mined yetno
minedPaid on-chain, waiting for finality (withdrawal.sent)no (practically paid)
completedFinalized (withdrawal.completed, tx_hash set)yes
cancelledCancelled by you, an admin, or the timeout (default 24 h, reason) — nothing was paidyes
rejectedAn approver rejected it — nothing was paidyes
failedCould not be sent (simulation failed, e.g. the destination is blocked by the token) — needs review, not retried automaticallyyes
cancellingA cancel of an in-flight tx is pending (dashboard only); ends as cancelled or completedno

Your balance bookkeeping: take the amount off the user's balance when you create the withdrawal. On cancelled, rejected or failed you must give it back — Polysia keeps no user balances. On completed the money has left for good.

Get / list — GET /v1/withdrawals/{id}, GET /v1/withdrawals

Scope withdrawals:read. List parameters: limit (1–100, default 50), starting_after (a wd_ id), status. Newest first; has_more tells you to page on. Ids of another business answer 404.

Cancel — POST /v1/withdrawals/{id}/cancel

Scope withdrawals:write. Only while nothing was broadcast (awaiting_approval, approved, waiting_funds); afterwards 409 withdrawal_not_cancellable (an in-flight payout can only be cancelled by an admin in the dashboard, which replaces the transaction). Cancelling a cancelled withdrawal returns it again (200).

Limits and checks (all enforced server-side)

CheckError
Business switch off403 api_withdrawals_disabled
Destination = zero address, the USDT contract, the factory, your own Hot Wallet or one of your deposit addresses400 destination_not_allowed
Destination not on the whitelist (when the business whitelist is on)400 destination_not_allowed
Amount > business max per withdrawal, or > this key's max per withdrawal400 amount_over_limit
Daily limit exceeded — business, customer (customer_id) or this key (UTC day; cancelled / rejected give the amount back)400 daily_limit_exceeded
Above the manual threshold (default 500 USDT) or poisoning suspectcreated as awaiting_approval
Request rate429 (the API's per-key create limit)

Every create / cancel is in the dashboard audit log as api:<key id>.

Webhooks

Subscribe the endpoint to withdrawal.* explicitly (not part of "all events"). data is the withdrawal object above, plus withdrawal_id (the dashboard number) and user_ref (= customer_id).

EventWhen
withdrawal.createdCreated (any source)
withdrawal.approvedReady to send (auto or after approval)
withdrawal.sentMined (tx_hash) — not final yet
withdrawal.completedFinalized (tx_hash) — final, paid
withdrawal.cancelledCancelled (reason: by you / an admin / timeout) — give the balance back
withdrawal.failedFailed, needs review (reason) — give the balance back (or retry with a new Idempotency-Key after fixing the cause)

As with all events: verify the signature, de-duplicate on the event id, do not rely on order — call GET /v1/withdrawals/{id} when in doubt.

Safety checklist

  • One payout key per server, IP-restricted, per-key daily limit set, stored like a password.
  • Set a business daily limit and keep the manual threshold low; large payouts then need a human with 2FA.
  • Turn on the destination whitelist if you only pay known addresses (e.g. your exchange).
  • Validate the user's address in your app before sending (Polygon, not an exchange deposit memo address).
  • Watch the withdraw_pending, withdraw_failed and withdraw_limit alerts.