This version (v0.7) has not been published to npm yet.
Skip to content

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:

ts
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 cap

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

ts
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 ​

ts
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. confirmOtp takes 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 (same Idempotency-Key and body) returns the same response, and any other request (another amount or destination, or a new key) is refused with FAILED_PRECONDITION (422) and the message another withdrawal request is pending. This holds even after the code was confirmed: the gateway keeps the confirmed request until its expiresAt, 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 (the expiresAt of 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 the id and amount that confirmOtp returns, never the amount the screen believes it requested. After expiresAt, request again, with a new Idempotency-Key.

    ts
    try {
      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. confirmOtp uses its own Idempotency-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), repeating confirmOtp does 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 ​

ts
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 ​

CodeWhen
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_PENDINGA 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_MISMATCHIdempotency: see Idempotency.

See all of them in Error codes.