Withdrawal
Loading the interactive demo…
The demo above runs the real SDK with createMockFetch({ withdrawalOtp: true }): no call goes out to the network. Pick a saved PIX key (pixKeys.list) or the CPF from sign-up, request the withdrawal, type the "SMS" code and see the receipt with the id and amount returned by confirmOtp; then cancel and watch the amount return to the balance. The scenarios show the operator without OTP and the business errors, which arrive in confirmOtp: INSUFFICIENT_BALANCE, WITHDRAWAL_LIMIT_EXCEEDED and KYC_REQUIRED. In the Under the hood panel, the OTP code appears masked; the request's idempotencyKey stays visible (it is not a secret): it is only repeated on the retry after a network failure (its own scenario); coming back after an answered request generates a new key.
The withdrawals namespace requests the withdrawal via PIX and, when the operator requires it, confirms it with a code (OTP) sent to the player. All methods require login. Amounts are in minor units of the operator's currency (see Money). The destination is a saved PIX key (PIX keys) or one provided on the spot.
Does the operator require OTP?
The operator's config decides: the withdraw_money flow in config.otp.flows. Use it to prepare the screen (e.g. show the "we will send a code" notice up front), but always decide by the return value of request, which tells you whether the code was actually sent:
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 capRequest the withdrawal
request takes the amount and one form of PIX key: pixKeyId (saved key) or pixKeyType + pixKeyValue. With pixKeyType: 'cpf', the value is optional (the gateway uses the CPF from sign-up). The type does not compile with both forms at once, nor with neither.
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 is idempotent (the same Idempotency-Key after a network failure does not request another withdrawal) and its response is always validated in strict mode: the app never receives an ambiguous result.
Reuse the Idempotency-Key only to repeat the same request after a non-definitive failure (NETWORK_ERROR, TIMEOUT, KEY_IN_USE). After any definitive response, including otp_required, generate a new key for the next request: the gateway stores the response for 72 hours and, with the old key, would return the same otp_required for a code that has already expired (after expiresAt), leaving the player stuck. See Idempotency.
Confirm with the code
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
}How confirmation stays safe:
It only confirms the player's own withdrawal.
confirmOtptakes only the code: the gateway finds the pending request by the session (operator + token user), never by an id coming from the app. There is no parameter that points to someone else's withdrawal.One pending request per player, never replaced. Until its
expiresAt(10 minutes after the request), repeating the same request (sameIdempotency-Keyand body) returns the same response, and any other request (another amount or destination, or a new key) is refused withFAILED_PRECONDITION(422) and the messageanother withdrawal request is pending. This holds even after the code was confirmed: the gateway keeps the confirmed request until itsexpiresAt, so the player's next withdrawal can only be requested after it. On that refusal, if the code was not confirmed yet, offer to confirm it; otherwise show until when the player has to wait (theexpiresAtof the previous request), and do not request again before that. The pending request may come from another tab or device, so the receipt must use theidandamountthatconfirmOtpreturns, never the amount the screen believes it requested. AfterexpiresAt, request again, with a newIdempotency-Key.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 }Idempotent end to end.
confirmOtpuses its ownIdempotency-Key; and the gateway, after sending the withdrawal, returns the same result for a repeated confirmation, without consuming the code again or duplicating the withdrawal. If the payment service fails (e.g.PAYMENT_FAILED, 5xx), repeatingconfirmOtpdoes not ask for another code.
Mistyped code
Each typed code is a different operation: let the SDK generate the key (do not pass idempotencyKey) or generate a new one for each code. Reusing the key with a different code returns PAYLOAD_MISMATCH; and, if the gateway rejected the code with a 4xx error, repeating with the same key may return the stored rejection instead of validating again. Reuse the key only to repeat the same confirmation after NETWORK_ERROR/TIMEOUT.
The withdrawal's business errors (INSUFFICIENT_BALANCE, KYC_REQUIRED, WITHDRAWAL_LIMIT_EXCEEDED, WITHDRAWAL_PENDING, PAYMENT_*) only appear when the withdrawal is actually sent to the payment service: in confirmOtp when there is OTP, or already in request when there is not.
Track and cancel
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 arrives normalized (WITHDRAWAL_STATUS_PENDING on the wire becomes 'pending'); handle the default case for new values. cancel is not idempotent in the gateway: after a network failure, check with get before repeating.
Current state of the gateway
withdrawals.list() already exists in the SDK, but today the gateway always returns an empty list (the payment service does not list withdrawals yet). Keep the id returned by request/confirmOtp and use get, or show withdrawals through the statement (wallet.listTransactions({ category: 'financial' })).
Errors
| Code | When |
|---|---|
INVALID_ARGUMENT (400) | Amount outside the limits, missing PIX key, payment not configured; in confirmOtp, empty code or nonexistent/expired request. e.message is already ready to display. |
INSUFFICIENT_BALANCE (422) | Insufficient real balance. |
KYC_REQUIRED (422) | The player must complete identity verification. |
WITHDRAWAL_LIMIT_EXCEEDED (429) | Withdrawal limit reached. |
WITHDRAWAL_PENDING | A withdrawal is already in progress. |
PAYMENT_FAILED and other PAYMENT_* | Payment provider failure. |
RESOURCE_EXHAUSTED (429) | OTP code sending limit or withdrawal request limit reached; see e.retryAfter. |
KEY_IN_USE / PAYLOAD_MISMATCH | Idempotency: see Idempotency. |
See all of them in Error codes.