Working the deposit queue

The deposit queue is Finance → Payment Systems → Deposit Records (/admin/finance/deposit/log). It lists every DEPOSIT transaction on the platform, and it opens filtered to PENDING, sorted oldest first.

What Approve actually does

One button, three consequences, in this order and inside one database transaction:

1. The wallet is credited with amount − fee through walletService.credit, under the idempotency key admin_deposit_approve_<transactionId>. That key is why a double-click, a retried request or a re-run of a bulk batch cannot credit twice.
2. The platform fee is booked — but only if fee is greater than zero. collectPlatformFee credits the Super Admin's wallet in the same currency and wallet type, writes a PLATFORM_FEE transaction, and inserts an adminProfit row. That row is what Finance → Revenue Analytics (/admin/finance/profit) reports.
3. The customer is emailed the new status and their new balance.

The fee is collected at settlement, not at request. A deposit that is created and never approved — or is rejected — books no profit at all, so your revenue figures only ever contain money that actually arrived.

The balance quoted in that email is re-read from the database after the credit commits, so it is the figure the credit produced rather than the pre-credit one.

Which rows you can decide

Only PENDING. That is enforced in three places and it is deliberate — the single-row endpoint answers Only pending transactions can be updated, the bulk endpoint refuses per id, and a settled row simply gets no Approve/Reject entries in its ⋯ menu.

The status column carries ten values, most of which you will never decide:

A stale selection does not fail the batch

Bulk Approve and bulk Reject send PUT /api/admin/finance/deposit/log/status with the selected ids. Each id is evaluated on its own:

• a row that is no longer PENDING is reported as Already COMPLETED (or whatever it now is) and skipped;
• an id that is not a DEPOSIT transaction is reported as Not a deposit transaction;
• everything else is decided.

The response says 12 of 15 processed. 3 could not be: … and names the failures. Do not re-run the whole batch — the twelve that went through are already credited, and only the three named ones need attention. The request only fails outright when nothing succeeded.

What the endpoint sends for you

A bulk decision changes the status and nothing else. The handler reads amount, fee, description and referenceId off the stored row and passes them straight back to the single-row update, rather than re-deriving them. Your rejection reason is nested at metadata.message, which is the field the customer's rejection email is composed from.

A rejection reason must be at least 3 characters, in the dialog, in the bulk endpoint and in the JSON schema. There is no default text: the Confirm button stays disabled until you type something. That is because the field used to be pre-filled with the prompt, and clicking straight through emailed the customer "Please provide a reason for rejection." as the explanation for their refused deposit.

The refusals you will meet

Approve does not always go through. Both of these leave the row PENDING so you can fix the cause and try again.

Where the rows come from

Three pipelines write type: "DEPOSIT" rows, and they reach the queue in very different states.

A manual deposit method. The customer picks a method you defined on /admin/finance/deposit/method, fills in whatever custom fields it asks for, and POST /api/finance/deposit/fiat creates a PENDING row against their FIAT wallet with the method's fees already computed. These are the rows the queue exists for. Nothing else will ever settle them; they wait for you.

A fiat gateway. Starting a gateway payment also creates a PENDING row, but the vendor's webhook or the customer's return normally completes it within seconds and credits the wallet without you. A gateway row that is still pending an hour later means the callback never arrived — check the gateway's readiness before you approve it by hand.

An on-chain spot deposit. The customer submits a transaction hash, which creates a PENDING row with amount: 0 and the hash in referenceId. A verification worker fills in the amount and completes it. Approving one by hand is almost never right.

Ecosystem (ECO) deposits are the exception that does not appear here at all while they are unconfirmed: they are tracked in Redis until the confirmation depth is reached and only then written as an already-COMPLETED row carrying the chain hash in trxId.

The detail screen

/admin/finance/deposit/log/[id] opens one deposit with five tabs — Details, User, Wallet, Manage and Audit. It needs edit.deposit to open at all.

Manage is editable only while the row is PENDING. You can correct amount, fee, referenceId and description before deciding, which is the supported way to fix a fee that is blocking approval. Reference ID is optional: a bank transfer entered by hand has no processor reference and never gets one.

Audit is two append-only records side by side: every administrative action taken against this transaction (who, when, what they typed), and the wallet balance ledger for the wallet it moved — one row per balance change with previousBalance, newBalance, previousInOrder, newInOrder and the idempotency key. Nothing on that tab can write. It is the answer to "prove this customer was credited once".

Payment gateways are a readiness console, not a table

Finance → Payment Systems → Gateways (/admin/finance/deposit/gateway) looks nothing like the other Finance screens, on purpose. There are a fixed sixteen gateways, they are installed by the platform rather than created by you, and none of the questions you actually have about one is answerable from a database column:

• Can it take a payment right now? → the environment, not the row.
• If not, why? → which environment variable is unset.
• Am I pointed at test or live? → a key prefix.
• Where do I paste the webhook? → derived from your public URL.

GET /api/admin/finance/deposit/gateway/config answers all four. For each gateway it reports which variables the bundled integration reads, which of them are set, the leading marker of a prefixed key (sk_live, pk_test, AQE) and nothing more of it, the webhook and return URLs the vendor should be given, and a test/live verdict.

The sixteen bundled profiles, keyed by alias (the folder name under api/finance/deposit/fiat/, and the only stable join between a row and its integration — the seeder gives some rows a literal id and mints a UUID for others):

Opening one gives you its setup steps in order, the vendor dashboard links, its known traps, the exact webhook URL to paste, and a Test credentials form.

Prove a gateway before a customer does. The test call is read-only — it asks the vendor a question that only a valid credential can answer, and creates nothing. For the six gateways marked format only, the vendor exposes no such endpoint, so the check confirms presence and shape and you prove the credential with a sandbox deposit instead.

Credentials live in .env, never in the database row, and the backend reads them at request time. Correcting a variable requires a backend restart before this screen or a customer sees the change — and any NEXT_PUBLIC_* variable (PayPal's client id is one) needs a frontend rebuild, not just a restart.

The gateway edit page is gated on edit.deposit.gateway; the list is access.deposit.gateway. Reading which gateways exist and rewriting their fee and currency configuration are deliberately different rights.

The routine