Retiro
Cargando la demo interactiva…
La demo de arriba ejecuta el SDK real con createMockFetch({ withdrawalOtp: true }): ninguna llamada sale a la red. Elige una clave PIX guardada (pixKeys.list) o el CPF del registro, solicita el retiro, digita el código del "SMS" y mira el comprobante con el id y el amount devueltos por confirmOtp; después, cancela y mira cómo el valor vuelve al saldo. Los escenarios muestran al operador sin OTP y los errores de negocio, que llegan en confirmOtp: INSUFFICIENT_BALANCE, WITHDRAWAL_LIMIT_EXCEEDED y KYC_REQUIRED. En el panel Under the hood, el código OTP aparece enmascarado; la idempotencyKey de la solicitud queda visible (no es un secreto): solo se repite en el nuevo intento después de un fallo de red (escenario Network failure); volver después de una solicitud respondida genera una clave nueva.
El namespace withdrawals solicita el retiro vía PIX y, cuando el operador lo exige, lo confirma con un código (OTP) enviado al jugador. Todos los métodos requieren inicio de sesión. Los valores van en unidades menores de la moneda del operador (consulta Dinero). El destino es una clave PIX guardada (Claves PIX) o indicada en el momento.
¿El operador exige OTP?
Lo decide la config del operador: el flujo withdraw_money en config.otp.flows. Úsalo para preparar la pantalla (p. ej., mostrar de antemano el aviso "enviaremos un código"), pero decide siempre por el retorno de request, que es el que indica si el código se envió de verdad:
const config = await enginex.config.get()
const expectsOtp = config.otp.enabled && config.otp.flows.includes('withdraw_money')
const { minWithdrawal = 0, maxWithdrawal = 0 } = config.limits // 0 in maxWithdrawal = no capSolicitar el retiro
request recibe el valor y una forma de clave PIX: pixKeyId (clave guardada) o pixKeyType + pixKeyValue. Con pixKeyType: 'cpf', el valor es opcional (el gateway usa el CPF del registro). El tipo no compila con las dos formas a la vez, ni con ninguna.
const result = await enginex.withdrawals.request(
{ amount: 5_000, pixKeyId: key.id },
{ idempotencyKey: withdrawalKey }, // crypto.randomUUID(), one per withdrawal
)
if (result.status === 'otp_required') {
// the code was sent to the player; nothing has left yet
showOtpForm({ expiresAt: result.expiresAt })
} else {
// result.status === 'created': the operator does not require OTP and the withdrawal was already sent
showReceipt(result.withdrawal) // { id, status: 'pending', amount }
}request es idempotente (la misma Idempotency-Key después de un fallo de red no solicita otro retiro) y su respuesta se valida siempre en modo estricto: la app nunca recibe un resultado ambiguo.
Reutiliza la Idempotency-Key solo para repetir la misma solicitud después de un fallo no definitivo (NETWORK_ERROR, TIMEOUT, KEY_IN_USE). Después de cualquier respuesta definitiva, incluido otp_required, genera una clave nueva para la siguiente solicitud: el gateway guarda la respuesta por 72 horas y, con la clave antigua, devolvería el mismo otp_required de un código que ya expiró (después de expiresAt), dejando al jugador sin salida. Consulta Idempotencia.
Confirmar con el código
try {
const withdrawal = await enginex.withdrawals.confirmOtp({ otp: code })
showReceipt(withdrawal) // show the RETURNED id and amount, not the amount typed on screen
} catch (e) {
if (isEnginexError(e, 'INVALID_ARGUMENT')) showError(e.message) // no pending or expired request
else if (isEnginexError(e, 'INSUFFICIENT_BALANCE')) showError('Insufficient balance')
else throw e
}Cómo es de segura la confirmación:
Solo confirma el retiro del propio jugador.
confirmOtprecibe únicamente el código: el gateway localiza la solicitud pendiente por la sesión (operador + usuario del token), nunca por un id que venga de la app. No hay ningún parámetro que apunte al retiro de otra persona.Una solicitud pendiente por jugador, nunca reemplazada. Hasta su
expiresAt(10 minutos después de la solicitud), repetir la misma solicitud (mismaIdempotency-Keyy mismo cuerpo) devuelve la misma respuesta, y cualquier otra solicitud (otro monto o destino, o una clave nueva) se rechaza conFAILED_PRECONDITION(422) y el mensajeanother withdrawal request is pending. Esto vale incluso después de confirmar el código: el gateway mantiene la solicitud confirmada hasta suexpiresAt, así que el siguiente retiro del jugador solo puede solicitarse después. Ante ese rechazo, si el código aún no se confirmó, ofrece confirmarlo; si no, muestra hasta cuándo debe esperar el jugador (elexpiresAtde la solicitud anterior) y no solicites de nuevo antes. La solicitud pendiente puede venir de otra pestaña u otro dispositivo; por eso, el comprobante debe usar elidy elamountque devuelveconfirmOtp, nunca el valor que la pantalla cree haber solicitado. Después deexpiresAt, solicita de nuevo, con unaIdempotency-Keynueva.tstry { await enginex.withdrawals.request({ amount, pixKeyId }, { idempotencyKey: newKey }) } catch (e) { if (isEnginexError(e, 'FAILED_PRECONDITION') && e.message === 'another withdrawal request is pending') { if (unconfirmed) showOtpForm() // the code of the pending request can still be confirmed else showRetryAfter(previous.expiresAt) // already confirmed: wait until the previous request expires } else throw e }Idempotente de punta a punta.
confirmOtpusa unaIdempotency-Keypropia; y el gateway, después de enviar el retiro, devuelve el mismo resultado para una confirmación repetida, sin consumir el código de nuevo ni duplicar el retiro. Si el servicio de pagos falla (p. ej.,PAYMENT_FAILED, 5xx), repetirconfirmOtpno pide otro código.
Código digitado incorrectamente
Cada código digitado es otra operación: deja que el SDK genere la clave (no pases idempotencyKey) o genera una nueva con cada código. Reutilizar la clave con otro código devuelve PAYLOAD_MISMATCH; y, si el gateway rechazó el código con un error 4xx, repetir con la misma clave puede devolver el rechazo guardado en lugar de validar de nuevo. Reutiliza la clave solo para repetir la misma confirmación después de NETWORK_ERROR/TIMEOUT.
Los errores de negocio del retiro (INSUFFICIENT_BALANCE, KYC_REQUIRED, WITHDRAWAL_LIMIT_EXCEEDED, WITHDRAWAL_PENDING, PAYMENT_*) solo aparecen cuando el retiro se envía de verdad al servicio de pagos: en confirmOtp cuando hay OTP, o ya en request cuando no la hay.
Seguir y cancelar
const withdrawal = await enginex.withdrawals.get({ withdrawalId: receipt.id })
// withdrawal.status: 'pending' | 'approved' | 'processing' | 'completed' | 'failed' | 'cancelled' | 'rejected'
if (withdrawal.status === 'pending') await enginex.withdrawals.cancel({ withdrawalId: withdrawal.id })status llega normalizado (WITHDRAWAL_STATUS_PENDING en la red pasa a 'pending'); maneja el caso por defecto para valores nuevos. cancel no es idempotente en el gateway: después de un fallo de red, confirma con get antes de repetir.
Estado actual del gateway
withdrawals.list() ya existe en el SDK, pero hoy el gateway siempre devuelve la lista vacía (el servicio de pagos aún no lista retiros). Guarda el id devuelto por request/confirmOtp y usa get, o muestra los retiros por el extracto (wallet.listTransactions({ category: 'financial' })).
Errores
| Código | Cuándo |
|---|---|
INVALID_ARGUMENT (400) | Valor fuera de los límites, clave PIX ausente, pago no configurado; en confirmOtp, código vacío o solicitud inexistente/expirada. e.message ya viene lista para mostrar. |
INSUFFICIENT_BALANCE (422) | Saldo real insuficiente. |
KYC_REQUIRED (422) | El jugador debe completar la verificación de identidad. |
WITHDRAWAL_LIMIT_EXCEEDED (429) | Se alcanzó el límite de retiro. |
WITHDRAWAL_PENDING | Ya existe un retiro en curso. |
PAYMENT_FAILED y otros PAYMENT_* | Fallo en el proveedor de pagos. |
RESOURCE_EXHAUSTED (429) | Se alcanzó el límite de envío de códigos OTP o de solicitudes de retiro; consulta e.retryAfter. |
KEY_IN_USE / PAYLOAD_MISMATCH | Idempotencia: consulta Idempotencia. |
Consulta todos en Códigos de error.