Withdrawal statuses

Use these statuses to track Pix cashouts. All endpoints require headers Content-Type: application/json, x-api-key: <MY_API_KEY>, and x-token: <MY_TOKEN>.

Looking for transaction statuses? See Transaction statuses.

Status reference

Name
CREATED
Type
status
Description
Withdrawal request accepted and queued.
Keep the request visible; show pending state to the user; avoid duplicate submissions.
Name
PROCESSING
Type
status
Description
Bank transfer is being executed.
Do not retry; monitor via query/webhook; show "processing" in UI.
Name
CONFIRMED
Type
status
Description
Transfer completed successfully.
Confirm payout to the user; reconcile with identifier/external_ref.
Name
FAILED
Type
status
Description
Transfer failed (invalid key, insufficient funds, or bank error).
Surface reason if provided; allow resubmission with corrected data; notify finance/support.
Name
CANCELED
Type
status
Description
Request canceled before completion.
Confirm cancellation to the user; ensure no duplicate retry; log who/why canceled.
Name
REFUNDED
Type
status
Description
Funds returned after a completed transfer (reversal).
Update ledger; notify the user; investigate cause; consider reissuing if appropriate.

Example withdrawal

{
  "magic_id": "9Wlp_2kGy4t9",
  "fee": 1,
  "amount": 100.00,
  "currency": "BRL",
  "status": "CONFIRMED",
  "end_to_end": "E36216020251211195427687",
  "transfer_method": "Pix",
  "external_ref": "external_ref",
  "movement": {
    "payer": {
      "name": "Company Name",
      "document": "12345678000190",
      "bank": "001",
      "agency": "0001",
      "account": "123456-7"
    },
    "payee": {
      "name": "John Doe",
      "document": "12345678901",
      "bank": "260",
      "agency": "0001",
      "account": "98765-4"
    }
  },
  "created_at": "2025-12-11 19:54:27.687",
  "updated_at": "2025-12-11 19:55:00.000"
}

Operational tips

Reconcile using magic_id or external_ref from creation.

Avoid manual retries while status is PROCESSING; wait for CONFIRMED/FAILED.
Subscribe to webhooks for near-real-time status; make handlers idempotent using magic_id or external_ref.
Keep audit logs for CANCELED and REFUNDED to support compliance and customer support.