Esta versión (v0.7) todavía no se publicó en npm.
Ir al contenido

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).

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() 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):

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

La 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:

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
}

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 ​

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 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ódigoCuá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.