Documentação

English

Português
Español

English

Português
Español

Appearance

Manage Withdrawals ​

Access prerequisites

  • Permission (module): viewWithdrawals (to view the listing). The approve/reject actions also require the approveWithdrawal and cancelWithdrawal modules.
  • License/Feature: WITHDRAWAL_HANDLING. The Digital Bank tab (internal fiat withdrawal) only appears when the DIGITAL_BANKING feature is also enabled.
  • Menu container: GENERAL → Operations group

What it is / when to use ​

Central screen for approving withdrawals requested by users. Requests are separated by destination type in tabs: Fiduciary (FIAT — external bank withdrawal), Digital Bank (INTERNAL_FIAT — internal transfer between digital accounts) and Bitcoin/ETH (on-chain crypto). The operator reviews the request data (destination account, PIX key, wallet address and token-specific custom fields), approves — which triggers the actual outflow of funds — or rejects, returning the reserved amount.

Prerequisites ​

  • Permission: viewWithdrawals to view; approveWithdrawal / cancelWithdrawal to act (dual permission — CPM enum + dynamic module in DB).
  • License/Feature: WITHDRAWAL_HANDLING enabled; DIGITAL_BANKING for the Digital Bank tab.
  • Dependencies on other screens: the target user must be APPROVED (KYC) and have a reserved balance. Withdrawals from wallets in fundraising state (IN_CAPTATION) are blocked by the reservation itself. Actions can only be taken on requests that are Pending.

Step by step ​

  1. Go to the Operations → Manage withdrawals menu.
  2. Choose the destination tab: Fiduciary, Digital Bank or Bitcoin/ETH (the selected tab is stored in the session).
  3. Filter by status (All, Approved, Cancelled, Pending) and search by name.
  4. Click the details (info) icon to open the modal with all request data, including token-specific custom fields and masked sensitive values.
  5. Approve to release the funds or reject to return the amount to the wallet. Confirm in the bottom-sheet.

Filters and columns ​

Filter/ColumnWhat it showsData source
Tab (type)FIAT / INTERNAL_FIAT / BTC-ETHtype of the request; tab persisted in MANAGE_WITHDRAWAL_TABLETYPE
SearchLocal filter by requester namename
StatusPending / Approved / Cancelled / Allstatus
DateDate of the requestwhen (ordered DESC)
ID / IdentifierRequest ID and CPF/CNPJ/passportid / identifier (resolved by userId)
AmountRequested amountamount (BigNumber)
StatusRequest statestatus

Details modal ​

Shows: name, amount + unit, bank, branch, account, PIX key, identifier, status, date and the list of custom fields defined by the token. Fields marked as secure appear masked (••••••); booleans become Yes/No; dates are formatted. These fields come from the token's withdrawal_custom_fields schema and are revalidated on the backend (type, regex, ranges, select options).

Actions and modals ​

  • Approve: confirmation bottom-sheet → updateWithdrawal(id, 'APPROVED'). The backend (FMS – Withdrawal) executes the actual outflow of funds (bank transfer, internal transfer or on-chain broadcast depending on the type). The page reloads.
  • Reject: bottom-sheet → updateWithdrawal(id, 'CANCELLED'). Returns the reserved amount to the user's wallet.
  • Open user: navigates to the user's details by email.
  • Help guide (auto_stories): opens the screen troubleshooting modal.

Business rules / cautions ​

Attention

  • Approve/reject is only available for requests that are Pending.
  • The Digital Bank tab depends on the DIGITAL_BANKING feature; without it, only Fiduciary and Bitcoin/ETH appear.
  • Check the custom fields (e.g.: external wallet address, PIX key) before approving — they carry the actual destination of the funds.

Irreversible

  • Approving triggers the actual outflow of funds (bank transfer / on-chain). Once confirmed, there is no rollback — an on-chain send or a bank transfer cannot be undone by the platform.
  • Financial values: treated as BigNumber — no rounding; verify the decimal places of the token/currency.
  • Idempotency: the withdrawal settlement in FinLib is idempotent by externalId. If the backend returns E00021 "already processed" (e.g.: retry after timeout/crash), the withdrawal has already been processed — treat it as success, do not resend.
  • Status APPROVED: the target user must be APPROVED.

Examples ​

Scenario 1 — Fiduciary withdrawal (FIAT) via PIX to an external bank
  1. Fiduciary tab, status Pending.
  2. Open the details and verify name, amount, bank, branch, account and PIX key.
  3. Compare the account holder's name with the user's (prevents withdrawal to third parties).
  4. Approve → FMS triggers the external bank transfer. Result: status becomes APPROVED, the amount leaves the house and the reservation is consumed.
Scenario 2 — Internal withdrawal between digital accounts (Digital Bank)
  1. Digital Bank tab (requires DIGITAL_BANKING).
  2. The destination is another digital account in the ecosystem — there is no external bank transfer.
  3. Approve → FMS performs the internal INTERNAL_FIAT transfer. Immediate settlement, no banking window.
Scenario 3 — Crypto withdrawal (BTC/ETH) with address in a custom field
  1. Bitcoin/ETH tab.
  2. In the details, the destination wallet address appears in the custom fields defined by the token (validated by regex in the token schema).
  3. Check the address carefully — on-chain sends are final.
  4. Approve → on-chain broadcast. If there is a retry and the backend returns E00021, the transaction has already been sent; do not resend.