Working the withdrawal queue

The queue is Admin → Finance → Withdrawal Management → Withdrawal Records (/admin/finance/withdraw/log). It opens filtered to PENDING, sorted oldest first — the row that has waited longest is the one to decide next.

The columns are the four facts a payout decision needs: who, how much, where to, and how long it has waited. The Age column is the same number the Operations inbox badge is computed from, so the two cannot disagree. Fee, reference id, transaction hash, description and the raw metadata are available in the expanded row.

Opening a row gives you /admin/finance/withdraw/log/[id], with five tabs: Details, User, Wallet, Manage and Audit Trail. The audit tab is the record of who decided what, and it is append-only.

Approve does three different things

Note the shape of that path: the {id} is the transaction id, even though the route sits under wallet. What happens next is decided by the type of the wallet the transaction belongs to, and the three behaviours have almost nothing in common.

SPOT — the one that moves money

The row is claimed with an atomic compare-and-set from PENDING to PROCESSING before exchange.withdraw() is called. Only the request that wins that transition is allowed to contact the exchange.

Before the claim, the route checks the row carries no sign of a dispatch (an exchange reference, an on-chain hash, a dispatched-but-unconfirmed marker). A row that does is refused with a 409 rather than sent a second time.

What is sent is read off the row: the wallet's currency, the destination and network the customer entered, and the amount they asked for, with the network fee applied under the same withdrawChainFee policy the request was quoted with. (Until Core 6.7.6 this route read a currency field the request never wrote, so every manual spot approval failed with This withdrawal has no currency recorded on it; behind that error it would have sent the gross debit plus the chain fee and refused any customer whose balance was below the withdrawal it had already been debited for.)

If the exchange rejects the withdrawal, or returns no id, or returns FAILED or CANCELLED, the customer is automatically refunded exactly what the request debited (metadata.totalDebit, under idempotency key withdraw_approve_refund_<id>), the transaction is set to REJECTED with the failure reason in its metadata, and you get a 500 whose message says the user has been refunded. A timeout on the exchange call is not a failure: the coins may have left, so the row stays PROCESSING for the reconciler and nothing is refunded. On success the transaction takes the exchange's status (pending at the exchange is stored as PROCESSING, never PENDING), stores the exchange's withdrawal id in referenceId, the on-chain hash in trxId when the exchange returns one, and books the platform fee.

FIAT — recording a payment you already made

A manual fiat payout is bookkeeping. The customer's wallet was debited when they requested the withdrawal; you have since moved the money by bank transfer; Approve records that. It flips the status to COMPLETED and books the platform fee.

ECO — refused, and correctly so

Ecosystem withdrawals are settled on-chain by the ecosystem queue and cannot be approved here.

The ecosystem's own withdrawal queue owns the nonce and the broadcast. Approving from the admin panel would mark the withdrawal paid without anything leaving the wallet. Rejection, however, works for ECO — see below.

The platform fee is booked at settlement

Never at request time. The withdrawal route records the platform's portion in the transaction's metadata.fee and takes nothing; collectWithdrawalFeeOnSettlement credits it when the withdrawal actually completes.

That ordering exists because the alternative minted money: taking the fee up front meant a later rejection refunded the customer the full debit — including the fee — while the fee sat credited to the platform. Every rejection created currency out of nothing.

Rejecting

Rejection is the same for every wallet type, and it is the action that un-freezes a stuck payout.

• A reason is mandatory, minimum 3 characters. It is emailed to the customer and stored on the transaction's metadata as note. An empty reason produces the "my withdrawal was declined with no explanation" support ticket the whole reason-capture rule exists to prevent. Approval, by contrast, takes an optional note.
• The customer is refunded, amount plus fee, capped at what the request actually debited (metadata.totalDebit), because amount is editable on the transaction screen and an inflated figure must not credit more than was taken. SPOT and FIAT go through a standard credit; ECO goes through ecoRefund, which updates the chain balance as well as the wallet balance.
• The status flip and the refund happen in one database transaction. The flip is a compare-and-set against the status the screen showed you, so if the withdrawal queue claimed the row in the meantime the reject answers 409 and nothing moves. Before Core 6.7.6 the status was written first and the refund after, outside any transaction, so a refund that failed left the row REJECTED with the money still debited and no way to retry.
• It refuses anything a chain or provider may already have. A row that is PROCESSING or TIMEOUT, or that carries an on-chain hash, a pending hash or a provider reference, answers 409. TIMEOUT in particular is what the Solana, TRON and Monero senders write when the transaction was broadcast and its outcome could not be read, so rejecting it used to refund a payout that was landing on-chain. Those rows belong to the withdrawal queue's recovery and the reconciler; rejection is for rows that never left.

Deciding in bulk

Body: { ids, status, reason }, where status is COMPLETED or REJECTED. A reason of at least 3 characters is required for REJECTED, and it is shared across the whole selection.

Two things make this safe to use:

It delegates. Each id is handed to the very same single-row handler you would have used, so the wallet-type routing, the atomic claim, the auto-refund, the fee accounting and the customer email all come along and cannot drift from the single-row behaviour.

Partial success is reported, not rolled back. Approving forty withdrawals is forty independent money movements. If three fail on exchange balance, the thirty-seven that already left must not be undone — and pretending the whole batch failed would send you to re-approve payouts that have been made. The response is:

{
  "message": "37 of 40 processed. 3 could not be: …",
  "succeeded": 37,
  "failed": 3,
  "failures": [{ "id": "…", "error": "…" }]
}

If nothing succeeded, the whole call returns a 400 instead, so a green toast can never mean "no money moved".

Do not use the bookkeeping PUT to approve

There is a second route, PUT /api/admin/finance/withdraw/log/{id}, that also sets a status. It is bookkeeping: it flips the status and books the fee without sending anything anywhere, and it accepts PENDING only. Using it to "approve" a SPOT withdrawal marks the customer paid while no funds move, which is how payouts end up being executed by hand outside the product.

Its REJECTED branch refuses, with a 409, any row that a provider has already been handed (an exchange reference, an on-chain hash, a dispatched marker). Until Core 6.7.6 it checked only that the row was PENDING, and the spot route used to store the exchange's own pending as PENDING with the exchange's id attached, so an operator could refund a payout the exchange was in the middle of broadcasting. Such rows are now written PROCESSING and belong to the reconciler.

The detail screen already routes correctly for you — its Approve button calls the exchange path for SPOT, the bookkeeping path for FIAT, and refuses ECO with an explanation. This note is for anyone driving the API directly.

The daily routine

The Operations inbox in the admin header gives withdrawals a 7-day budget and turns the queue amber at half of it. See The admin panel for how the inbox is built.

Related

• Withdrawal approval and two-factor policy — whether rows reach this queue at all, and what a customer had to prove to create one.
• The admin panel — the Operations inbox and the shared queue decision controls.