Managing merchants

The admin merchant queue — approving and suspending accounts, verifying business details, overriding fees and limits per merchant, and which of those limits the platform actually enforces.

4 min readUpdated 3 August 2026admin, merchants, fees, limits, verification

Merchant accounts are reviewed by hand. A new registration lands at status = PENDING and stays there — its API keys exist but every call they make is refused — until someone opens Extensions → Payment Gateway → Merchants and decides.

The screen is at /admin/gateway/merchant and needs access.gateway.merchant to open plus view.gateway.merchant to load anything into it.

The queue

The list is the gateway_merchant table with the owning user joined in, paginated, filterable and sortable. Newest first by default. What to look at on each row:

Status — PENDING is your inbox. ACTIVE, SUSPENDED and REJECTED are outcomes.
Verification — PENDING on every new account, whether or not you approved the status.
The owning user — the merchant is a facade on a real platform account. Their KYC record, their wallets and their history are all one click away, and they are the right thing to judge.

The merchant list, the merchant detail view and the payment list all declare demoMask on personal fields. On a demo install you will see placeholders, not missing data.

Two decisions, two buttons

Sets a merchant PENDING, ACTIVE, SUSPENDED or REJECTED

Sets verification to UNVERIFIED, PENDING or VERIFIED

Status is the switch that controls money.

ACTIVE — API keys authenticate, payments can be created, the checkout will confirm. This is the only state in which the merchant can trade.
PENDING — the default. Every API call gets 403 Merchant account is not active.
SUSPENDED — same effect as PENDING, different meaning to whoever reads the row next. Use it for accounts you have stopped, not accounts you have not started.
REJECTED — a refusal.

Setting a merchant SUSPENDED stops new payments. It does not touch their gateway balance, and it does not stop the payout job from creating new payout records against the balance they already hold. If you are suspending an account because you suspect fraud, reject its open payouts as well — see Payouts and refunds.

Verification is the record that you checked who they are. It gates two much smaller things: the merchant may not create additional API keys until it reads VERIFIED, and their own identity fields (name, email, phone, website, business type, address) freeze the moment it does.

That freeze is the reason to verify late rather than early. Up to VERIFIED the merchant can correct their own details; after it, every correction is a support request that lands on this screen.

Editing a merchant

Updates business details, fee structure, limits and payout settings

The per-merchant overrides are the reason this endpoint exists. Every one of them was seeded from your platform settings at registration and is independent of them afterwards — changing a platform default does not move an existing merchant.

Field	Effect
`feeType`	`PERCENTAGE`, `FIXED` or `BOTH`. New merchants get `BOTH`
`feePercentage`	Percent of the payment amount, e.g. `2.9`
`feeFixed`	Flat amount added per payment
`transactionLimit`	Enforced. A payment above it is rejected at creation
`dailyLimit` · `monthlyLimit`	Stored and shown. Not enforced anywhere
`payoutSchedule`	`INSTANT`, `DAILY`, `WEEKLY` or `MONTHLY`
`payoutThreshold`	Payouts below this are not created
`allowedCurrencies` · `allowedWalletTypes`	The merchant's half of the two-list currency check
`defaultCurrency`	Display default on their dashboard
`testMode`	The merchant's own flag; the key prefix is what actually decides mode

dailyLimit and monthlyLimit are written at registration, editable here, displayed on both dashboards — and read by no enforcement code. Nothing sums a merchant's daily volume and compares it. The only volume ceilings that bite are the per-payment transactionLimit and the platform-wide gatewayMaxPaymentAmount. If you are relying on a daily cap to contain risk, you do not have one.

Fees are worth thinking about before you set them. With feeType: BOTH and the defaults, a payment of 49.99 carries 49.99 × 2.9% + 0.30 = 1.75, leaving the merchant 48.24. The fee is charged in the currency the buyer actually paid in and split proportionally across the wallets they used, so a fixed fee on a merchant who mostly takes small crypto payments is a much larger percentage than the number suggests.

Deleting a merchant

Soft-deletes a merchant account

The table is paranoid — the row is soft-deleted, not removed, and its payments, refunds, payouts and balances remain. Prefer REJECTED or SUSPENDED for anything you might have to explain later. Deleting does not release, refund or claw back a gateway balance.

Reading a merchant's numbers

Full merchant record with balances and activity

The detail view carries the merchant's gateway balances, one row per currency and wallet type, with four columns that answer four different questions:

pending — earned, not yet paid out. This is what a payout draws from.
available — moved out of pending by an approved payout. Historical.
totalReceived / totalFees / totalRefunded / totalPaidOut — cumulative counters for reporting.

A merchant asking "where is my money" is asking about pending, and the answer is on the payout queue.

A workable review policy

Check the owning user first. Registration age, KYC state, whether they have ever had a withdrawal reversed. The merchant record itself is self-reported.
Approve status before verification. Set ACTIVE so they can test with their sk_test_ key, and leave verification at PENDING so they can still fix their own details.
Set the fee and the transaction limit deliberately. The defaults were copied from your platform settings and may not suit this merchant. The per-transaction limit is your only real ceiling.
Verify once you have the documents. From then on, every identity change is your job.
Watch the first payout. It is the first time real money leaves your custody on this merchant's behalf.

Next: Payouts and refunds.