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

Reference / @getenginex/sdk / WithdrawalsApi

WithdrawalsApi ​

Withdrawals via PIX, with OTP confirmation when the operator requires it. All methods require login.

Methods ​

cancel() ​

cancel(input, options?): Promise<void>

Cancels a withdrawal that is still pending. It is not idempotent at the gateway: on a network failure, check the state with WithdrawalsApi.get before repeating.

Parameters ​

input ​
withdrawalId ​

string

options? ​

CallOptions

Returns ​

Promise<void>

Example ​

ts
await enginex.withdrawals.cancel({ withdrawalId: withdrawal.id })

Throws ​

NOT_FOUND if the id does not exist; payment service error if the withdrawal can no longer be cancelled; UNAUTHENTICATED without a session.


confirmOtp() ​

confirmOtp(input, options?): Promise<WithdrawalSubmission>

Confirms the logged-in player's pending withdrawal request with the code (OTP) and sends the withdrawal. The gateway finds the request by the session (operator + token user), never by an id coming from the app: there is no way to confirm another player's or another account's withdrawal. Idempotent, with its own key (independent from request's); repeating the confirmation of a withdrawal already sent returns the same withdrawal, without consuming the code again or duplicating the submission. The response is always validated in strict mode.

Show the player the id and the amount returned here, not the amount the screen believes it requested: the gateway confirms the player's pending request, which may have been made in another tab or device (while it is pending, a different request is refused instead of replacing it).

requestId: the requestId returned by WithdrawalsApi.request. It does not go to the gateway; it enters the attempt fingerprint in the mutations (createMutations, useEnginexMutation), and a new challenge never reuses the previous one's key. Recommended.

Parameters ​

input ​
otp ​

string

requestId? ​

string

options? ​

CallOptions

Returns ​

Promise<WithdrawalSubmission>

Example ​

ts
const result = await enginex.withdrawals.request({ amount: 5_000, pixKeyId: key.id })
if (result.status === 'otp_required') {
  const withdrawal = await enginex.withdrawals.confirmOtp({ otp: '123456', requestId: result.requestId })
  console.log(withdrawal.id, withdrawal.status) // 'wd-…', 'pending'
}

Throws ​

INVALID_ARGUMENT (400) without a code, without a pending request or with the request expired (request the withdrawal again); authentication service error for an invalid code; INSUFFICIENT_BALANCE, KYC_REQUIRED, WITHDRAWAL_LIMIT_EXCEEDED, WITHDRAWAL_PENDING and PAYMENT_* from the payment service (after a transient failure, repeating does not ask for another code); KEY_IN_USE/PAYLOAD_MISMATCH from idempotency; UNAUTHENTICATED without a session.


get() ​

get(input, options?): Promise<Withdrawal>

A player's withdrawal.

Parameters ​

input ​
withdrawalId ​

string

options? ​

CallOptions

Returns ​

Promise<Withdrawal>

Example ​

ts
const withdrawal = await enginex.withdrawals.get({ withdrawalId: 'wd-1' })

Throws ​

NOT_FOUND if the id does not exist (or belongs to another player); UNAUTHENTICATED without a session; VALIDATION_ERROR, also in 'warn', with money or currency outside the format.


list() ​

list(input?, options?): Promise<Page<Withdrawal>>

The player's withdrawals, paginated. Today the gateway always returns an empty list (the payment service does not list withdrawals yet); the SDK already exposes the contract. Use WithdrawalsApi.get with the id returned by request/confirmOtp, or the statement (wallet.listTransactions).

Parameters ​

input? ​

ListWithdrawalsInput

options? ​

CallOptions

Returns ​

Promise<Page<Withdrawal>>

Example ​

ts
const page = await enginex.withdrawals.list({ page: 1 })

Throws ​

UNAUTHENTICATED without a session; VALIDATION_ERROR, also in 'warn', with money or currency outside the format.


request() ​

request(input, options?): Promise<WithdrawalRequestResult>

Requests a withdrawal. Idempotent: sends Idempotency-Key (generated on each call, or the one from options.idempotencyKey) and keeps it on the retry after renewing the session; to repeat after NETWORK_ERROR/TIMEOUT without requesting another withdrawal, generate the key beforehand and pass the same one. The response is always validated in strict mode: the app never receives an ambiguous union.

With an OTP (status: 'otp_required'), there is only one pending request per player, and it does not get replaced: until its expiresAt (10 minutes after the request), repeating the same request (same 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 WithdrawalsApi.confirmOtp (it confirms that pending request); otherwise show until when the player has to wait (the expiresAt of the previous request), instead of requesting again. Check config.limits.minWithdrawal/maxWithdrawal first: outside the limits, the gateway rejects with INVALID_ARGUMENT and a ready-made message (e.g. saque mínimo é 20.00 BRL).

Parameters ​

input ​

RequestWithdrawalInput

options? ​

CallOptions

Returns ​

Promise<WithdrawalRequestResult>

Examples ​

ts
const result = await enginex.withdrawals.request({ amount: 5_000, pixKeyId: key.id })
if (result.status === 'otp_required') {
  const code = await askOtp(result.expiresAt)
  const withdrawal = await enginex.withdrawals.confirmOtp({ otp: code, requestId: result.requestId })
} else {
  showReceipt(result.withdrawal)
}
ts
// Recognizing the refusal while another request is still pending
try {
  await enginex.withdrawals.request({ amount: 8_000, pixKeyId: key.id })
} 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
}

Throws ​

INVALID_ARGUMENT (400) for an amount outside the limits or a missing PIX key; FAILED_PRECONDITION (422) while another request is pending (see above, identify it by the message) and also, with other messages, when PIX withdrawals are not available for the jurisdiction, the payment method is not configured for the operator or a route-compatible identity document is required; INSUFFICIENT_BALANCE (422), KYC_REQUIRED (422), WITHDRAWAL_LIMIT_EXCEEDED (429), WITHDRAWAL_PENDING and PAYMENT_FAILED/PAYMENT_*, passed through from the payment service — without an OTP, already in this call; with an OTP, in confirmOtp; RESOURCE_EXHAUSTED (429) when the code-sending limit was exceeded; KEY_IN_USE (409) if the same key is still being processed; PAYLOAD_MISMATCH (422) if the key was already used with another body; VALIDATION_ERROR if the response comes outside the format (the withdrawal may have been requested: check the balance); UNAUTHENTICATED without a session.