---
url: https://game-engine-io.github.io/enginex-frontend-sdk/flows/pix-deposit.md
---
# PIX deposit

The demo above runs the real SDK (`createEnginexClient`) with `fetch: createMockFetch(...)` from
[`@getenginex/sdk/testing`](/guide/testing): no call goes out to the network and the QR code is
illustrative. The typed amount goes through `toMinorUnits` (an ambiguous value such as `1.000` is
rejected before the network), the charge is created with one `Idempotency-Key` per deposit intent and
the **Simulate payment** button plays the role of the bank. Switch the scenario to see the **network
failure** (the retry reuses the key and receives the same charge), `DEPOSIT_LIMIT_EXCEEDED` and
`RESOURCE_EXHAUSTED` with `retryAfter`; after a definitive response (the charge or an error), the next
attempt uses a new key. The **Under the hood** panel shows each call with its `CallOptions` (the
idempotency key is not a secret: it is visible), the requests seen by the
[hooks](/concepts/extensibility), the result or the `EnginexError`, the session and the balance, re-read
with `wallet.getBalance()` after each call.

The `deposits` namespace creates the PIX charge and follows the payment; `wallet` shows the balance and
the statement. All methods require login. Amounts are always **minor units** of the operator's currency
(cents in BRL): convert what the player typed with `toMinorUnits` and display it with `formatMoney`
(see [Money](/concepts/money)). In tests, the `createMockFetch` from
[`@getenginex/sdk/testing`](/guide/testing) already answers all of these routes, with in-memory balance.

## First: limits and balance

The limits come from the public config. Validate in the form: outside them, the gateway rejects with
`INVALID_ARGUMENT` (400) and a ready-made message in Portuguese (e.g. `depósito mínimo é 10.00 BRL`).

```ts
import { formatMoney, toMinorUnits } from '@getenginex/sdk'

const config = await enginex.config.get()
const { minDeposit = 0, maxDeposit = 0 } = config.limits // 0 in maxDeposit = no cap

const amount = toMinorUnits(input.value, config.currency) // '50,00' -> 5000
if (amount < minDeposit) showError(`Minimum: ${formatMoney(minDeposit, config.currency)}`)

const balance = await enginex.wallet.getBalance()
formatMoney(balance.realBalance, config.currency) // 'R$ 1.500,00'
```

`wallet.get()` returns the same balances with the reserved amount in `reserved`; `wallet.getBalance()`
calls it `pendingWithdrawals` (withdrawals in progress).

## Create the charge

`createPix` is **idempotent**: the SDK sends an `Idempotency-Key` per call and keeps it in the internal
retry after refreshing the session. So that a second click, or a new attempt after a network failure,
does not create another charge, generate the key once per deposit intent and reuse it **only** to
repeat after a non-definitive failure (`NETWORK_ERROR`, `TIMEOUT`, `KEY_IN_USE`). After any definitive
response, whether the charge or an error with a body, generate a new key for the next charge: the gateway
stores the response for each key for 72 hours and, with the old key, would return the same charge, with
the QR already expired after `expiresAt` (see [Idempotency](/concepts/idempotency)):

```ts
import { isEnginexError } from '@getenginex/sdk'

const key = crypto.randomUUID() // one per deposit, created when the player confirms the amount

async function deposit() {
  try {
    return await enginex.deposits.createPix({ amount }, { idempotencyKey: key })
  } catch (e) {
    if (isEnginexError(e, 'NETWORK_ERROR') || isEnginexError(e, 'TIMEOUT') || isEnginexError(e, 'KEY_IN_USE')) {
      return enginex.deposits.createPix({ amount }, { idempotencyKey: key }) // does not duplicate
    }
    throw e
  }
}

const pix = await deposit()
pix.qrCode // QR code, as the operator's payment provider delivers it
pix.qrCodeText // PIX copy-and-paste
pix.expiresAt // expiry (ISO 8601), absent when the provider reports none; after it, create another charge (with a new key)
pix.redirectUrl // the provider's payment page, only when it offers one
```

The response is always validated in strict mode, even with `validation: 'warn'` on the client: the app
never receives a half-formed charge. If `VALIDATION_ERROR` comes back, the charge may have been
created: check `deposits.list()` before trying again.

::: tip `qrCode` format
The gateway passes the QR code from the operator's payment provider through without converting it. Check
with your provider whether it is a base64 image or the payload itself (in that case, generate the image
from `qrCodeText` with a QR code library).
:::

## Follow the payment

The balance only changes when the bank confirms the PIX. Check the deposit (or the balance) at short
intervals while the QR code is on screen:

```ts
const deposit = await enginex.deposits.get({ depositId: pix.id })
switch (deposit.status) {
  case 'completed':
    showSuccess() // credited
    break
  case 'expired':
  case 'failed':
  case 'cancelled':
    showRetry()
    break
  default:
    // 'pending' / 'processing': keep waiting
}
```

The SDK normalizes `status` (`DEPOSIT_STATUS_COMPLETED` on the wire becomes `'completed'`) and `method`
(`PAYMENT_METHOD_PIX` becomes `'pix'`). A new value the SDK does not know yet arrives in the same
format (lowercase, no prefix): always handle the default case.

## History

```ts
const page = await enginex.deposits.list({ page: 1, perPage: 10 })
page.items // [{ id, amount, status, createdAt }]

const statement = await enginex.wallet.listTransactions({ category: 'financial', perPage: 20 })
```

`wallet.listTransactions` accepts `category`: `all` (default), `financial` (deposits, withdrawals,
bonuses, cashback, chargebacks, adjustments, fees), `casino`, `sports` or `predictions`. In both
listings, `perPage` ranges from 1 to 100 (outside that, the gateway uses 20); see
[Pagination](/concepts/pagination).

## Errors

| Code | When |
|---|---|
| `INVALID_ARGUMENT` (400) | Amount outside the config limits, or payment not configured for the operator. `e.message` is already ready to display. |
| `DEPOSIT_LIMIT_EXCEEDED` (429) | Responsible gaming deposit limit reached. |
| `KYC_REQUIRED` (422) | The player must complete identity verification. |
| `PAYMENT_FAILED` and other `PAYMENT_*` | Payment provider failure. |
| `RESOURCE_EXHAUSTED` (429) | Per-player deposit request limit reached; wait `e.retryAfter` seconds. |
| `KEY_IN_USE` (409) | The same key is still being processed (double click): repeat with the same key. |
| `PAYLOAD_MISMATCH` (422) | The key was already used with a different amount: generate a new key for a new deposit. |

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