---
url: >-
  https://game-engine-io.github.io/enginex-frontend-sdk/reference/api/@getenginex/sdk/interfaces/WithdrawalsApi.md
---
[Reference](../../../index.md) / [@getenginex/sdk](../index.md) / WithdrawalsApi

# WithdrawalsApi

Withdrawals via PIX, with OTP confirmation when the operator requires it. All methods require login.

## Methods

### cancel()

> **cancel**(`input`, `options?`): `Promise`<`void`>

Cancels a withdrawal that is still pending. It is not idempotent at the gateway: on a network failure, check the
state with [WithdrawalsApi.get](#get) before repeating.

#### Parameters

##### input

###### withdrawalId

`string`

##### options?

[`CallOptions`](CallOptions.md)

#### Returns

`Promise`<`void`>

#### Example

```ts
await enginex.withdrawals.cancel({ withdrawalId: withdrawal.id })
```

#### Throws

`NOT_FOUND` if the id does not exist; payment service error if the withdrawal
can no longer be cancelled; `UNAUTHENTICATED` without a session.

***

### confirmOtp()

> **confirmOtp**(`input`, `options?`): `Promise`<[`WithdrawalSubmission`](WithdrawalSubmission.md)>

Confirms the logged-in player's pending withdrawal request with the code (OTP) and sends the withdrawal. The
gateway finds the request by the session (operator + token user), never by an id coming from the
app: there is no way to confirm another player's or another account's withdrawal. **Idempotent**, with its own
key (independent from `request`'s); repeating the confirmation of a withdrawal already sent
returns the same withdrawal, without consuming the code again or duplicating the submission. The response is always
validated in strict mode.

Show the player the `id` and the `amount` **returned here**, not the amount the screen believes it
requested: the gateway confirms the player's pending request, which may have been made in another tab or
device (while it is pending, a different `request` is refused instead of replacing it).

`requestId`: the `requestId` returned by [WithdrawalsApi.request](#request). It does not go to the gateway; it enters the
attempt fingerprint in the mutations (`createMutations`, `useEnginexMutation`), and a new challenge
never reuses the previous one's key. Recommended.

#### Parameters

##### input

###### otp

`string`

###### requestId?

`string`

##### options?

[`CallOptions`](CallOptions.md)

#### Returns

`Promise`<[`WithdrawalSubmission`](WithdrawalSubmission.md)>

#### Example

```ts
const result = await enginex.withdrawals.request({ amount: 5_000, pixKeyId: key.id })
if (result.status === 'otp_required') {
  const withdrawal = await enginex.withdrawals.confirmOtp({ otp: '123456', requestId: result.requestId })
  console.log(withdrawal.id, withdrawal.status) // 'wd-…', 'pending'
}
```

#### Throws

`INVALID_ARGUMENT` (400) without a code, without a pending request or with the request
expired (request the withdrawal again); authentication service error for an invalid code;
`INSUFFICIENT_BALANCE`, `KYC_REQUIRED`, `WITHDRAWAL_LIMIT_EXCEEDED`, `WITHDRAWAL_PENDING` and
`PAYMENT_*` from the payment service (after a transient failure, repeating does not ask for another
code); `KEY_IN_USE`/`PAYLOAD_MISMATCH` from idempotency; `UNAUTHENTICATED` without a session.

***

### get()

> **get**(`input`, `options?`): `Promise`<[`Withdrawal`](Withdrawal.md)>

A player's withdrawal.

#### Parameters

##### input

###### withdrawalId

`string`

##### options?

[`CallOptions`](CallOptions.md)

#### Returns

`Promise`<[`Withdrawal`](Withdrawal.md)>

#### Example

```ts
const withdrawal = await enginex.withdrawals.get({ withdrawalId: 'wd-1' })
```

#### Throws

`NOT_FOUND` if the id does not exist (or belongs to another player);
`UNAUTHENTICATED` without a session; `VALIDATION_ERROR`, also in `'warn'`, with money or currency outside
the format.

***

### list()

> **list**(`input?`, `options?`): `Promise`<[`Page`](Page.md)<[`Withdrawal`](Withdrawal.md)>>

The player's withdrawals, paginated. **Today the gateway always returns an empty list** (the payment
service does not list withdrawals yet); the SDK already exposes the contract. Use [WithdrawalsApi.get](#get)
with the id returned by `request`/`confirmOtp`, or the statement (`wallet.listTransactions`).

#### Parameters

##### input?

[`ListWithdrawalsInput`](ListWithdrawalsInput.md)

##### options?

[`CallOptions`](CallOptions.md)

#### Returns

`Promise`<[`Page`](Page.md)<[`Withdrawal`](Withdrawal.md)>>

#### Example

```ts
const page = await enginex.withdrawals.list({ page: 1 })
```

#### Throws

`UNAUTHENTICATED` without a session; `VALIDATION_ERROR`, also in `'warn'`, with
money or currency outside the format.

***

### request()

> **request**(`input`, `options?`): `Promise`<[`WithdrawalRequestResult`](../type-aliases/WithdrawalRequestResult.md)>

Requests a withdrawal. **Idempotent**: sends `Idempotency-Key` (generated on each call, or the one from
`options.idempotencyKey`) and keeps it on the retry after renewing the session; to repeat after
`NETWORK_ERROR`/`TIMEOUT` without requesting another withdrawal, generate the key beforehand and pass the same one. The response is
always validated in strict mode: the app never receives an ambiguous union.

With an OTP (`status: 'otp_required'`), there is only **one** pending request per player, and it does not get
replaced: until its `expiresAt` (10 minutes after the request), repeating **the same** request (same 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 [WithdrawalsApi.confirmOtp](#confirmotp) (it confirms that pending request); otherwise show until when the
player has to wait (the `expiresAt` of the previous request), instead of requesting again.
Check `config.limits.minWithdrawal`/`maxWithdrawal` first: outside the limits, the gateway rejects
with `INVALID_ARGUMENT` and a ready-made message (e.g. `saque mínimo é 20.00 BRL`).

#### Parameters

##### input

[`RequestWithdrawalInput`](../type-aliases/RequestWithdrawalInput.md)

##### options?

[`CallOptions`](CallOptions.md)

#### Returns

`Promise`<[`WithdrawalRequestResult`](../type-aliases/WithdrawalRequestResult.md)>

#### Examples

```ts
const result = await enginex.withdrawals.request({ amount: 5_000, pixKeyId: key.id })
if (result.status === 'otp_required') {
  const code = await askOtp(result.expiresAt)
  const withdrawal = await enginex.withdrawals.confirmOtp({ otp: code, requestId: result.requestId })
} else {
  showReceipt(result.withdrawal)
}
```

```ts
// Recognizing the refusal while another request is still pending
try {
  await enginex.withdrawals.request({ amount: 8_000, pixKeyId: key.id })
} 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
}
```

#### Throws

`INVALID_ARGUMENT` (400) for an amount outside the limits or a missing PIX key;
`FAILED_PRECONDITION` (422) while another request is pending (see above, identify it by the message) and also,
with other messages, when PIX withdrawals are not available for the jurisdiction, the payment method is not
configured for the operator or a route-compatible identity document is required; `INSUFFICIENT_BALANCE` (422), `KYC_REQUIRED` (422),
`WITHDRAWAL_LIMIT_EXCEEDED` (429), `WITHDRAWAL_PENDING` and `PAYMENT_FAILED`/`PAYMENT_*`,
passed through from the payment service — without an OTP, already in this call; with an OTP, in `confirmOtp`;
`RESOURCE_EXHAUSTED` (429) when the code-sending limit was exceeded; `KEY_IN_USE` (409) if the
same key is still being processed; `PAYLOAD_MISMATCH` (422) if the key was already used with
another body; `VALIDATION_ERROR` if the response comes outside the format (the withdrawal may have been
requested: check the balance); `UNAUTHENTICATED` without a session.
