PIX deposit
Loading the interactive demo…
The demo above runs the real SDK (createEnginexClient) with fetch: createMockFetch(...) from @getenginex/sdk/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, 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). In tests, the createMockFetch from @getenginex/sdk/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).
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):
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 oneThe 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.
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:
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
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.
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.