Depósito PIX
Cargando la demo interactiva…
La demo de arriba ejecuta el SDK real (createEnginexClient) con fetch: createMockFetch(...) de @getenginex/sdk/testing: ninguna llamada sale a la red y el código QR es ilustrativo. El valor digitado pasa por toMinorUnits (un valor ambiguo como 1.000 se rechaza antes de la red), el cobro se crea con una Idempotency-Key por intención de depósito y el botón Simulate payment hace el papel del banco. Cambia el escenario para ver Network failure (el nuevo intento reutiliza la clave y recibe el mismo cobro), DEPOSIT_LIMIT_EXCEEDED y RESOURCE_EXHAUSTED con retryAfter; después de una respuesta definitiva (el cobro o un error), el siguiente intento usa una clave nueva. El panel Under the hood muestra cada llamada con las CallOptions (la clave de idempotencia no es un secreto: queda visible), los requests vistos por los hooks, el resultado o el EnginexError, la sesión y el saldo, releído con wallet.getBalance() después de cada llamada.
El namespace deposits crea el cobro PIX y sigue el pago; wallet muestra el saldo y el extracto. Todos los métodos requieren inicio de sesión. Los valores son siempre unidades menores de la moneda del operador (centavos en BRL): convierte lo que el jugador digitó con toMinorUnits y muéstralo con formatMoney (consulta Dinero). En pruebas, el createMockFetch de @getenginex/sdk/testing ya responde a todas estas rutas, con saldo en memoria.
Antes: límites y saldo
Los límites vienen de la config pública. Valida en el formulario: fuera de ellos, el gateway rechaza con INVALID_ARGUMENT (400) y un mensaje ya listo en portugués (p. ej., 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() trae los mismos saldos con el valor reservado en reserved; wallet.getBalance() lo llama pendingWithdrawals (retiros en curso).
Crear el cobro
createPix es idempotente: el SDK envía una Idempotency-Key por llamada y la mantiene en el reintento interno tras renovar la sesión. Para que un segundo clic o un nuevo intento después de un fallo de red no cree otro cobro, genera la clave una vez por intención de depósito y reutilízala solo para repetir después de un fallo no definitivo (NETWORK_ERROR, TIMEOUT, KEY_IN_USE). Después de cualquier respuesta definitiva (el cobro, o un error con cuerpo), genera una clave nueva para el siguiente cobro: el gateway guarda la respuesta de cada clave por 72 horas y, con la clave antigua, devolvería el mismo cobro, con el QR ya vencido después de expiresAt (consulta Idempotencia):
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 oneLa respuesta se valida siempre en modo estricto, incluso con validation: 'warn' en el cliente: la app nunca recibe un cobro a medias. Si llega VALIDATION_ERROR, el cobro puede haberse creado: consulta deposits.list() antes de volver a intentar.
Formato del qrCode
El gateway reenvía el código QR del proveedor de pagos del operador sin convertirlo. Confirma con tu proveedor si es una imagen en base64 o el propio payload (en ese caso, genera la imagen a partir de qrCodeText con una biblioteca de códigos QR).
Seguir el pago
El saldo solo cambia cuando el banco confirme el PIX. Consulta el depósito (o el saldo) en intervalos cortos mientras el código QR esté en pantalla:
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
}El SDK normaliza status (DEPOSIT_STATUS_COMPLETED en la red pasa a 'completed') y method (PAYMENT_METHOD_PIX pasa a 'pix'). Un valor nuevo que el SDK aún no conoce llega en el mismo formato (minúsculas, sin prefijo): maneja siempre el caso por defecto.
Historial
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 acepta category: all (por defecto), financial (depósitos, retiros, bonos, cashback, reversos, ajustes, comisiones), casino, sports o predictions. En los dos listados, perPage va de 1 a 100 (fuera de eso, el gateway usa 20); consulta Paginación.
Errores
| Código | Cuándo |
|---|---|
INVALID_ARGUMENT (400) | Valor fuera de los límites de la config, o pago no configurado en el operador. e.message ya viene lista para mostrar. |
DEPOSIT_LIMIT_EXCEEDED (429) | Se alcanzó el límite de depósito de juego responsable. |
KYC_REQUIRED (422) | El jugador debe completar la verificación de identidad. |
PAYMENT_FAILED y otros PAYMENT_* | Fallo en el proveedor de pagos. |
RESOURCE_EXHAUSTED (429) | Se alcanzó el límite de requests de depósito por jugador; espera e.retryAfter segundos. |
KEY_IN_USE (409) | La misma clave aún se está procesando (doble clic): repite con la misma clave. |
PAYLOAD_MISMATCH (422) | La clave ya se usó con otro valor: genera una clave nueva para un depósito nuevo. |
Consulta todos en Códigos de error.