---
title: "Read withdrawal status"
method: GET
path: "/api/withdrawals/{id}"
tags: ["pay"]
---

# Read withdrawal status

`GET /api/withdrawals/{id}`

## Request

- Base URL: `https://api.depixapp.com`
- URL: `https://api.depixapp.com/api/withdrawals/{id}`
- Auth: HTTP bearer

Pay-side status read (ownership enforced — foreign ids are 404). Poll every 5–15 s until a terminal status; `sent` is terminal success. With sk_test_, sandbox_* ids return the fixed synthetic sandbox-only state `confirmed`; any other id is 404.

## Path parameters

- `id` string, required

## Response `200`

Withdrawal status.

- union: Withdrawal status read (stable English subset of the row). Live rows and the fixed synthetic sandbox variant.
  - object: Live withdrawal row (JWT or sk_live_).
    - `id` string, required: Withdrawal id (the withdrawalId returned by POST /api/withdraw).
    - `type` 'withdraw', required: Resource discriminator — always "withdraw" here.
    - `amount_cents` integer, required: Provider-side deposit amount in cents (what the caller sends) — consistent with the per-key daily accumulator.
    - `status` union, required: Withdrawal lifecycle status — the enum below is the complete, closed set. `sent` is the terminal SUCCESS state. Sandbox status reads return the sandbox-only synthetic value `confirmed` instead (see the sandbox response variant). Terminal states (safe to stop polling): sent, refunded, cancelled, expired.
      - 'unsent': Created; DePix not yet received by the provider.
      - 'sending': DePix received; PIX payout in flight.
      - 'error': The DePix arrived and the PIX payout failed. NOT terminal — the provider holds the funds and still owes an outcome, so keep polling: the withdrawal can still reach `sent` (payout retried) or `refunded`.
      - 'sent': TERMINAL — success: PIX delivered to the target key.
      - 'refunded': TERMINAL — refunded.
      - 'cancelled': TERMINAL — cancelled.
      - 'expired': TERMINAL — DePix never arrived (swept by cron).
    - `created_at` string, required: Creation timestamp (RFC 3339 UTC, `YYYY-MM-DDTHH:MM:SS.sssZ`).
    - `updated_at` string, required: Last update timestamp (RFC 3339 UTC). No per-status timestamps exist on withdrawals today, so this equals created_at.
    - `liquid_txid` string: Settlement Liquid txid (the provider-reported on-chain tx that funded the withdrawal) — present once the provider reports it.
  - object: Sandbox synthetic status (sk_test_ key + sandbox_* id): fixed, stateless terminal state for test-mode polling. Echoes amount_cents + deterministic timestamps so the shape matches the live variant.
    - `id` string, required: The sandbox_* id passed in the path.
    - `type` 'withdraw', required: Resource discriminator — always "withdraw" here.
    - `amount_cents` integer, nullable, required: Provider-side deposit amount in cents (what the caller sends), decoded from the sandbox_* id minted at creation — mirrors the live read. null only for legacy/malformed sandbox ids that carry no embedded amount.
    - `status` 'confirmed', required: Fixed synthetic sandbox-only state (always "confirmed").
    - `created_at` string, required: Deterministic synthetic creation timestamp (RFC 3339 UTC, `YYYY-MM-DDTHH:MM:SS.sssZ`) — fixed in sandbox (stateless).
    - `updated_at` string, required: Deterministic synthetic update timestamp (RFC 3339 UTC, `YYYY-MM-DDTHH:MM:SS.sssZ`) — equals created_at in sandbox.
    - `sandbox` true, required: Marks the synthetic sandbox response.

## Other responses

- `401`: Missing/invalid credentials. `invalid_api_key` for a failed sk_* lookup (revoked/expired/unknown); `invalid_token` for a bad or missing JWT/Authorization header.
- `403`: The API key lacks the `wallet_read` scope required by this operation. May also be `account_blocked`, or an operation-specific 403 — see the error catalog.
- `404`: Withdrawal not found — includes rows owned by another account (ownership is never disclosed).
- `429`: Rate limited (per-IP, per-key or per-merchant window). Retry after `retry_after` seconds (also in the Retry-After header).

---

[API](https://skmtc.dev/depixapp/apis/depix-api.md) · [All operations](https://skmtc.dev/depixapp/apis/depix-api/llms.txt) · [OpenAPI document](https://skmtc.dev/depixapp/apis/depix-api/revisions/04094536dd0f?raw)