Saque
Carregando a demo interativa…
A demo acima roda o SDK de verdade com createMockFetch({ withdrawalOtp: true }): nenhuma chamada sai para a rede. Escolha uma chave PIX salva (pixKeys.list) ou o CPF do cadastro, peça o saque, digite o código do "SMS" e veja o comprovante com o id e o amount devolvidos por confirmOtp; depois, cancele e veja o valor voltar ao saldo. Os cenários mostram o operador sem OTP e os erros de negócio, que chegam em confirmOtp: INSUFFICIENT_BALANCE, WITHDRAWAL_LIMIT_EXCEEDED e KYC_REQUIRED. No painel Under the hood, o código OTP aparece mascarado; a idempotencyKey do pedido fica visível (não é segredo): ela só se repete na nova tentativa depois de uma falha de rede (cenário Network failure); voltar depois de um pedido respondido gera chave nova.
O namespace withdrawals pede o saque via PIX e, quando o operador exige, confirma com um código (OTP) enviado ao jogador. Todos os métodos exigem login. Valores em unidades menores da moeda do operador (veja Dinheiro). O destino é uma chave PIX salva (Chaves PIX) ou informada na hora.
O operador exige OTP?
Quem decide é a config do operador: o fluxo withdraw_money em config.otp.flows. Use isso para preparar a tela (ex.: já mostrar o aviso "enviaremos um código"), mas sempre decida pelo retorno de request — é ele que diz se o código foi de fato enviado:
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 capPedir o saque
request recebe o valor e uma forma de chave PIX: pixKeyId (chave salva) ou pixKeyType + pixKeyValue. Com pixKeyType: 'cpf', o valor é opcional (o gateway usa o CPF do cadastro). O tipo não compila com as duas formas ao mesmo tempo, nem sem nenhuma.
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 é idempotente (a mesma Idempotency-Key depois de uma falha de rede não pede outro saque) e sua resposta é validada sempre em modo estrito: o app nunca recebe um resultado ambíguo.
Reuse a Idempotency-Key só para repetir o mesmo pedido depois de uma falha não definitiva (NETWORK_ERROR, TIMEOUT, KEY_IN_USE). Depois de qualquer resposta definitiva — inclusive o otp_required — gere uma chave nova para o próximo pedido: o gateway guarda a resposta por 72 horas e, com a chave antiga, devolveria o mesmo otp_required de um código que já expirou (depois de expiresAt), deixando o jogador sem saída. Veja Idempotência.
Confirmar com o 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
}Como a confirmação é segura:
Só confirma o saque do próprio jogador.
confirmOtprecebe apenas o código: o gateway localiza o pedido pendente pela sessão (operador + usuário do token), nunca por um id vindo do app. Não há parâmetro que aponte para o saque de outra pessoa.Um pedido pendente por jogador, nunca substituído. Até o
expiresAtdele (10 minutos depois do pedido), repetir o mesmo pedido (mesmaIdempotency-Keye mesmo corpo) devolve a mesma resposta, e qualquer outro pedido (outro valor ou destino, ou uma chave nova) é recusado comFAILED_PRECONDITION(422) e a mensagemanother withdrawal request is pending. Isso vale mesmo depois de o código ser confirmado: o gateway mantém o pedido confirmado até oexpiresAtdele, então o próximo saque do jogador só pode ser pedido depois disso. Nessa recusa, se o código ainda não foi confirmado, ofereça confirmá-lo; senão, mostre até quando o jogador precisa esperar (oexpiresAtdo pedido anterior) e não peça de novo antes disso. O pedido pendente pode vir de outra aba ou outro dispositivo; por isso, o comprovante deve usar oide oamountqueconfirmOtpdevolve, nunca o valor que a tela acredita ter pedido. Depois deexpiresAt, peça de novo — com umaIdempotency-Keynova.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 ponta a ponta.
confirmOtpusa umaIdempotency-Keyprópria; e o gateway, depois de enviar o saque, devolve o mesmo resultado para uma confirmação repetida — sem consumir o código de novo nem duplicar o saque. Se o serviço de pagamento falhar (ex.:PAYMENT_FAILED, 5xx), repetirconfirmOtpnão pede outro código.
Código digitado errado
Cada código digitado é outra operação: deixe o SDK gerar a chave (não passe idempotencyKey) ou gere uma nova a cada código. Reusar a chave com outro código devolve PAYLOAD_MISMATCH; e, se o gateway tiver recusado o código com um erro 4xx, repetir com a mesma chave pode devolver a recusa guardada em vez de validar de novo. Reuse a chave só para repetir a mesma confirmação depois de NETWORK_ERROR/TIMEOUT.
Os erros de negócio do saque (INSUFFICIENT_BALANCE, KYC_REQUIRED, WITHDRAWAL_LIMIT_EXCEEDED, WITHDRAWAL_PENDING, PAYMENT_*) só aparecem quando o saque é de fato enviado ao serviço de pagamento: em confirmOtp quando há OTP, ou já em request quando não há.
Acompanhar e 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 chega normalizado (WITHDRAWAL_STATUS_PENDING no fio vira 'pending'); trate o caso padrão para valores novos. cancel não é idempotente no gateway: depois de uma falha de rede, confira com get antes de repetir.
Estado atual do gateway
withdrawals.list() já existe no SDK, mas hoje o gateway sempre devolve a lista vazia (o serviço de pagamento ainda não lista saques). Guarde o id retornado por request/confirmOtp e use get, ou mostre os saques pelo extrato (wallet.listTransactions({ category: 'financial' })).
Erros
| Código | Quando |
|---|---|
INVALID_ARGUMENT (400) | Valor fora dos limites, chave PIX ausente, pagamento não configurado; em confirmOtp, código vazio ou pedido inexistente/expirado. e.message já vem pronta para exibir. |
INSUFFICIENT_BALANCE (422) | Saldo real insuficiente. |
KYC_REQUIRED (422) | O jogador precisa concluir a verificação de identidade. |
WITHDRAWAL_LIMIT_EXCEEDED (429) | Limite de saque atingido. |
WITHDRAWAL_PENDING | Já existe um saque em andamento. |
PAYMENT_FAILED e outros PAYMENT_* | Falha no provedor de pagamento. |
RESOURCE_EXHAUSTED (429) | Limite de envio de códigos OTP ou de pedidos de saque atingido; veja e.retryAfter. |
KEY_IN_USE / PAYLOAD_MISMATCH | Idempotência: veja Idempotência. |
Veja todos em Códigos de erro.