Depósito PIX
Carregando a demo interativa…
A demo acima roda o SDK de verdade (createEnginexClient) com fetch: createMockFetch(...) de @getenginex/sdk/testing: nenhuma chamada sai para a rede e o QR code é ilustrativo. O valor digitado passa por toMinorUnits (um valor ambíguo como 1.000 é recusado antes da rede), a cobrança é criada com uma Idempotency-Key por intenção de depósito e o botão Simulate payment faz o papel do banco. Troque o cenário para ver Network failure (a nova tentativa reusa a chave e recebe a mesma cobrança), DEPOSIT_LIMIT_EXCEEDED e RESOURCE_EXHAUSTED com retryAfter; depois de uma resposta definitiva (a cobrança ou um erro), a próxima tentativa usa chave nova. O painel Under the hood mostra cada chamada com as CallOptions (a chave de idempotência não é segredo: fica visível), os requests vistos pelos hooks, o resultado ou o EnginexError, a sessão e o saldo, relido com wallet.getBalance() depois de cada chamada.
O namespace deposits cria a cobrança PIX e acompanha o pagamento; wallet mostra o saldo e o extrato. Todos os métodos exigem login. Valores são sempre unidades menores da moeda do operador (centavos no BRL): converta o que o jogador digitou com toMinorUnits e exiba com formatMoney (veja Dinheiro). Em testes, o createMockFetch de @getenginex/sdk/testing já responde a todas estas rotas, com saldo em memória.
Antes: limites e saldo
Os limites vêm da config pública. Valide no formulário: fora deles, o gateway recusa com INVALID_ARGUMENT (400) e uma mensagem pronta em português (ex.: 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() traz os mesmos saldos com o valor reservado em reserved; wallet.getBalance() o chama de pendingWithdrawals (saques em andamento).
Criar a cobrança
createPix é idempotente: o SDK manda uma Idempotency-Key por chamada e a mantém no retry interno após renovar a sessão. Para que um segundo clique ou uma nova tentativa depois de uma falha de rede não crie outra cobrança, gere a chave uma vez por intenção de depósito e reuse-a só para repetir depois de uma falha não definitiva (NETWORK_ERROR, TIMEOUT, KEY_IN_USE). Depois de qualquer resposta definitiva — a cobrança, ou um erro com corpo — gere uma chave nova para a próxima cobrança: o gateway guarda a resposta de cada chave por 72 horas e, com a chave antiga, devolveria a mesma cobrança, com o QR já vencido depois de expiresAt (veja Idempotência):
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 oneA resposta é validada sempre em modo estrito, mesmo com validation: 'warn' no cliente: o app nunca recebe uma cobrança pela metade. Se vier VALIDATION_ERROR, a cobrança pode ter sido criada — consulte deposits.list() antes de tentar de novo.
Formato do qrCode
O gateway repassa o QR code do provedor de pagamento do operador sem converter. Confira com o seu provedor se é uma imagem em base64 ou o próprio payload (neste caso, gere a imagem a partir de qrCodeText com uma biblioteca de QR code).
Acompanhar o pagamento
O saldo só muda quando o banco confirmar o PIX. Consulte o depósito (ou o saldo) em intervalos curtos enquanto o QR code estiver na tela:
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
}O SDK normaliza status (DEPOSIT_STATUS_COMPLETED no fio vira 'completed') e method (PAYMENT_METHOD_PIX vira 'pix'). Um valor novo que o SDK ainda não conhece chega no mesmo formato (minúsculas, sem prefixo): trate sempre o caso padrão.
Histórico
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 aceita category: all (padrão), financial (depósitos, saques, bônus, cashback, estornos, ajustes, taxas), casino, sports ou predictions. Nas duas listagens, perPage vai de 1 a 100 (fora disso, o gateway usa 20); veja Paginação.
Erros
| Código | Quando |
|---|---|
INVALID_ARGUMENT (400) | Valor fora dos limites da config, ou pagamento não configurado no operador. e.message já vem pronta para exibir. |
DEPOSIT_LIMIT_EXCEEDED (429) | Limite de depósito de jogo responsável atingido. |
KYC_REQUIRED (422) | O jogador precisa concluir a verificação de identidade. |
PAYMENT_FAILED e outros PAYMENT_* | Falha no provedor de pagamento. |
RESOURCE_EXHAUSTED (429) | Limite de requests de depósito por jogador atingido; espere e.retryAfter segundos. |
KEY_IN_USE (409) | A mesma chave ainda está em processamento (clique duplo): repita com a mesma chave. |
PAYLOAD_MISMATCH (422) | A chave já foi usada com outro valor: gere uma chave nova para um depósito novo. |
Veja todos em Códigos de erro.