Payouts (Withdrawals / Saque)

O termo de produto é Saque (payout); o endpoint atual /v1/withdrawals é o nome de fio (wire format) em uso hoje e ainda não foi renomeado para /v1/payouts.

Move balance out of your Demo Pay wallet to a real-world destination — a PIX key (Brazil), a bank account (TED), or a crypto address. This is the inverse of PIX payments: payments credit your wallet, payouts debit it.

#Flow at a glance

1. POST /v1/withdrawals/validate-pix-key   (optional — pre-flight)
2. POST /v1/withdrawals                    (creates request, debits wallet on approval)
3. Demo Pay approves / acquirer settles
4. Webhook withdrawal.completed (or .failed) hits your endpoint

Payouts require JWT-authenticated users (the dashboard or your back-office), not the public apikey. They debit the merchant's Demo Pay wallet directly and are subject to admin approval — they aren't a customer-facing flow.

#1. Validate a PIX key (recommended)

Before creating the payout, check the destination key is well-formed.

POST /v1/withdrawals/validate-pix-key

{
  "key": "12345678909",
  "type": "CPF"
}

Response 200 OK

{
  "valid": true,
  "type": "CPF",
  "normalised": "12345678909"
}

Supported type values

Failure

{
  "valid": false,
  "type": "CPF",
  "errors": ["invalid CPF checksum"]
}

#2. Create the payout

POST /v1/withdrawals

Example — PIX payout

curl -X POST https://demo.zentry.cloud/v1/withdrawals \
  -H "Authorization: Bearer $JWT" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "PIX",
    "amount": 50000,
    "currency": "BRL",
    "pixKey": "12345678909",
    "pixKeyType": "CPF",
    "description": "Weekly payout — week 17",
    "idempotencyKey": "payout-2026-W17"
  }'

Response 201 Created

{
  "id": "f6a7b8c9-d0e1-4234-9f01-234567890123",
  "status": "PENDING",
  "type": "PIX",
  "amount": 50000,
  "currency": "BRL",
  "pixKey": "12345678909",
  "pixKeyType": "CPF",
  "fee": 100,
  "netAmount": 49900,
  "description": "Weekly payout — week 17",
  "createdAt": "2026-04-25T16:10:00.000Z"
}

The wallet is not debited yet — that happens on approval.

When a payout doesn't go through. The full refusal contract — the error.code for an immediate balance refusal, the provider failure codes, and which of them refund automatically — is in Payout failures.

#3. Lifecycle

PENDING  ─▶  APPROVED  ─▶  PROCESSING  ─▶  COMPLETED   ✓ funds delivered
                                                ─▶  FAILED      acquirer rejected, wallet auto-refunded
                  ─▶  REJECTED                                  admin denied — never debited
                  ─▶  CANCELLED                                 you cancelled before approval

#4. Webhooks

Subscribe to withdrawal.completed and withdrawal.failed (same events array used for payments) to track payout outcomes. The legacy alias withdrawal.status_changed is also accepted at registration and expands to both:

{
  "event": "withdrawal.completed",
  "data": {
    "withdrawalId": "f6a7b8c9-d0e1-4234-9f01-234567890123",
    "amount": 50000,
    "fee": 100,
    "netAmount": 49900,
    "status": "COMPLETED",
    "previousStatus": "PROCESSING",
    "type": "PIX",
    "occurredAt": "2026-04-25T16:11:42.000Z"
  }
}

Other events:

• withdrawal.failed — data.status ∈ FAILED, REJECTED, CANCELLED. Wallet has already been auto-refunded for FAILED.

#5. List your payouts

GET /v1/withdrawals?page=1&limit=20&status=COMPLETED

Auth: same JWT as the create endpoint.

{
  "data": [
    {
      "id": "wd_...",
      "status": "COMPLETED",
      "type": "PIX",
      "amount": 50000,
      "fee": 100,
      "netAmount": 49900,
      "completedAt": "2026-04-25T16:11:42.000Z",
      "...": "..."
    }
  ],
  "total": 17,
  "page": 1,
  "limit": 20
}

#6. Limits & rules

• Per-transaction PIX cap — R$ 100.000,00 by default (your contract may extend).
• Daily cap — 5× per-transaction by default.
• Wallet must cover amount + fee — partial debits never happen; the request is rejected outright.
• Approval — by default, every payout needs admin approval. Merchants in good standing can request the auto-approval flag (withdrawals_auto_approve) for amounts under a configured threshold.
• TED — restricted to Brazilian banks (Bacom-listed bankCode). Settlement: same business day if approved before 16:30 BRT.
• Crypto — payouts settle in USDT on BSC (BEP-20) only. cryptoNetwork must be BSC and cryptoCurrency must be USDT; the destination must be a valid BEP-20 (0x…) address, validated server-side before any wallet debit — an unsupported network/token/address is rejected outright and never moves funds. Wrong-network sends are not recoverable, by design.

#FAQ

Q: I created a payout but it's stuck on PENDING. A: Admin approval is required by default. Either approve via the dashboard or enable auto-approval (contact support).

Q: My payout FAILED — was I charged the fee? A: No. FAILED triggers an automatic, atomic wallet refund of amount + fee.

Q: Can I cancel a payout? A: Only while PENDING. Once approved, the funds are in flight.

Q: My CNPJ key was rejected as invalid even though my bank accepts it. A: Mod-11 checksums fail when the key was issued before 2014. We accept the value with ?strictCnpj=false query parameter — contact support to enable.

Q: TED bank not in my dropdown. A: We use the Bacen FEBRABAN code list. Open a ticket if a code is missing — usually fixed within 24h.