---
url: https://game-engine-io.github.io/enginex-frontend-sdk/flows/withdrawal.md
---
# Withdrawal

The demo above runs the real SDK with `createMockFetch({ withdrawalOtp: true })`: no call goes out to
the network. Pick a saved PIX key (`pixKeys.list`) or the CPF from sign-up, request the withdrawal,
type the "SMS" code and see the receipt with the `id` and `amount` returned by `confirmOtp`; then
cancel and watch the amount return to the balance. The scenarios show the operator without OTP and the
business errors, which arrive in `confirmOtp`: `INSUFFICIENT_BALANCE`, `WITHDRAWAL_LIMIT_EXCEEDED` and
`KYC_REQUIRED`. In the **Under the hood** panel, the OTP code appears masked; the request's
`idempotencyKey` stays visible (it is not a secret): it is only repeated on the retry after a **network
failure** (its own scenario); coming back after an answered request generates a new key.

The `withdrawals` namespace requests the withdrawal via PIX and, when the operator requires it, confirms
it with a code (OTP) sent to the player. All methods require login. Amounts are in **minor units** of
the operator's currency (see [Money](/concepts/money)). The destination is a saved PIX key
([PIX keys](/flows/pix-keys)) or one provided on the spot.

## Does the operator require OTP?

The operator's config decides: the `withdraw_money` flow in `config.otp.flows`. Use it to prepare the
screen (e.g. show the "we will send a code" notice up front), but **always** decide by the return value
of `request`, which tells you whether the code was actually sent:

```ts
const config = await enginex.config.get()
const expectsOtp = config.otp.enabled && config.otp.flows.includes('withdraw_money')
const { minWithdrawal = 0, maxWithdrawal = 0 } = config.limits // 0 in maxWithdrawal = no cap
```

## Request the withdrawal

`request` takes the amount and **one** form of PIX key: `pixKeyId` (saved key) or `pixKeyType` +
`pixKeyValue`. With `pixKeyType: 'cpf'`, the value is optional (the gateway uses the CPF from sign-up).
The type does not compile with both forms at once, nor with neither.

```ts
const result = await enginex.withdrawals.request(
  { amount: 5_000, pixKeyId: key.id },
  { idempotencyKey: withdrawalKey }, // crypto.randomUUID(), one per withdrawal
)

if (result.status === 'otp_required') {
  // the code was sent to the player; nothing has left yet
  showOtpForm({ expiresAt: result.expiresAt })
} else {
  // result.status === 'created': the operator does not require OTP and the withdrawal was already sent
  showReceipt(result.withdrawal) // { id, status: 'pending', amount }
}
```

`request` is **idempotent** (the same `Idempotency-Key` after a network failure does not request another
withdrawal) and its response is always validated in strict mode: the app never receives an ambiguous
result.

Reuse the `Idempotency-Key` **only** to repeat the same request after a non-definitive failure
(`NETWORK_ERROR`, `TIMEOUT`, `KEY_IN_USE`). After any definitive response, including
`otp_required`, generate a new key for the next request: the gateway stores the response for 72 hours
and, with the old key, would return the same `otp_required` for a code that has already expired (after
`expiresAt`), leaving the player stuck. See [Idempotency](/concepts/idempotency).

## Confirm with the code

```ts
try {
  const withdrawal = await enginex.withdrawals.confirmOtp({ otp: code })
  showReceipt(withdrawal) // show the RETURNED id and amount, not the amount typed on screen
} catch (e) {
  if (isEnginexError(e, 'INVALID_ARGUMENT')) showError(e.message) // no pending or expired request
  else if (isEnginexError(e, 'INSUFFICIENT_BALANCE')) showError('Insufficient balance')
  else throw e
}
```

How confirmation stays safe:

* **It only confirms the player's own withdrawal.** `confirmOtp` takes only the code: the gateway
  finds the pending request by the session (operator + token user), never by an id coming from the app.
  There is no parameter that points to someone else's withdrawal.
* **One pending request per player, never replaced.** Until its `expiresAt` (10 minutes after the
  request), repeating **the same** request (same `Idempotency-Key` and body) returns the same response,
  and any other request (another amount or destination, or a new key) is refused with
  `FAILED_PRECONDITION` (422) and the message `another withdrawal request is pending`. This holds **even
  after the code was confirmed**: the gateway keeps the confirmed request until its `expiresAt`, so the
  player's next withdrawal can only be requested after it. On that refusal, if the code was not
  confirmed yet, offer to confirm it; otherwise show until when the player has to wait (the `expiresAt`
  of the previous request), and do not request again before that. The pending
  request may come from another tab or device, so the receipt must use the `id` and `amount` that
  `confirmOtp` returns, never the amount the screen believes it requested. After `expiresAt`, request
  again, with a new `Idempotency-Key`.

  ```ts
  try {
    await enginex.withdrawals.request({ amount, pixKeyId }, { idempotencyKey: newKey })
  } catch (e) {
    if (isEnginexError(e, 'FAILED_PRECONDITION') && e.message === 'another withdrawal request is pending') {
      if (unconfirmed) showOtpForm() // the code of the pending request can still be confirmed
      else showRetryAfter(previous.expiresAt) // already confirmed: wait until the previous request expires
    } else throw e
  }
  ```
* **Idempotent end to end.** `confirmOtp` uses its own `Idempotency-Key`; and the gateway, after sending
  the withdrawal, returns the same result for a repeated confirmation, without consuming the code again
  or duplicating the withdrawal. If the payment service fails (e.g. `PAYMENT_FAILED`, 5xx), repeating
  `confirmOtp` does not ask for another code.

::: tip Mistyped code
Each typed code is a different operation: let the SDK generate the key (do not pass `idempotencyKey`) or
generate a new one for each code. Reusing the key with a different code returns `PAYLOAD_MISMATCH`; and,
if the gateway rejected the code with a 4xx error, repeating with the same key may return the stored
rejection instead of validating again. Reuse the key only to repeat **the same** confirmation after
`NETWORK_ERROR`/`TIMEOUT`.
:::

The withdrawal's business errors (`INSUFFICIENT_BALANCE`, `KYC_REQUIRED`, `WITHDRAWAL_LIMIT_EXCEEDED`,
`WITHDRAWAL_PENDING`, `PAYMENT_*`) only appear when the withdrawal is actually sent to the payment
service: **in `confirmOtp`** when there is OTP, or **already in `request`** when there is not.

## Track and cancel

```ts
const withdrawal = await enginex.withdrawals.get({ withdrawalId: receipt.id })
// withdrawal.status: 'pending' | 'approved' | 'processing' | 'completed' | 'failed' | 'cancelled' | 'rejected'

if (withdrawal.status === 'pending') await enginex.withdrawals.cancel({ withdrawalId: withdrawal.id })
```

`status` arrives normalized (`WITHDRAWAL_STATUS_PENDING` on the wire becomes `'pending'`); handle the
default case for new values. `cancel` is not idempotent in the gateway: after a network failure, check
with `get` before repeating.

::: warning Current state of the gateway
`withdrawals.list()` already exists in the SDK, but today the gateway always returns an empty list (the
payment service does not list withdrawals yet). Keep the `id` returned by `request`/`confirmOtp` and use
`get`, or show withdrawals through the statement (`wallet.listTransactions({ category: 'financial' })`).
:::

## Errors

| Code | When |
|---|---|
| `INVALID_ARGUMENT` (400) | Amount outside the limits, missing PIX key, payment not configured; in `confirmOtp`, empty code or nonexistent/expired request. `e.message` is already ready to display. |
| `INSUFFICIENT_BALANCE` (422) | Insufficient real balance. |
| `KYC_REQUIRED` (422) | The player must complete identity verification. |
| `WITHDRAWAL_LIMIT_EXCEEDED` (429) | Withdrawal limit reached. |
| `WITHDRAWAL_PENDING` | A withdrawal is already in progress. |
| `PAYMENT_FAILED` and other `PAYMENT_*` | Payment provider failure. |
| `RESOURCE_EXHAUSTED` (429) | OTP code sending limit or withdrawal request limit reached; see `e.retryAfter`. |
| `KEY_IN_USE` / `PAYLOAD_MISMATCH` | Idempotency: see [Idempotency](/concepts/idempotency). |

See all of them in [Error codes](/concepts/error-codes).
