Gateway settings

Every platform-wide gateway setting — what each one does, which ones only apply to merchants registering from now on, and the four that are stored and never read.

4 min readUpdated 3 August 2026admin, settings, fees, limits, kyc

Extensions → Payment Gateway → Settings (/admin/gateway/settings). Five tabs: General, Wallets, Fees & Limits, Security and Webhooks. Opening it needs access.gateway.settings.

The screen writes through the platform settings endpoint (edit.settings), not the gateway-specific one. edit.gateway.settings guards a second, parallel endpoint that the UI does not call. A staff role with only the gateway keys can open the page and cannot save it.

Two things to hold in mind while you read the list.

Most of these are defaults, not rules. Fees, limits, payout schedule and payout threshold are copied onto a merchant's row at registration. Changing them here changes what the next merchant gets. Existing merchants keep the values they were created with, and you change those on the merchant screen.

A setting you never touch has no row at all. The platform persists changed keys only, so an untouched setting falls back to its coded default rather than to empty. That is deliberate — it is why an operator who has never opened this page still has a working gateway.

Wallets — the one that gates everything

Which wallet types may be used for payments, and the exact currency codes enabled under each. A JSON map of type to { enabled, currencies }

The default is an empty map, and an empty map enables nothing. Until you configure this:

Every POST /v1/payment/create fails with "Wallet type FIAT is not enabled for payments".
The checkout page offers the buyer no wallets.
New merchants are seeded with the FIAT / USD fallback, which then fails the same check.

The tab builds its picker from what your platform actually has: fiat currencies if fiat wallets are on, exchange currencies if spot wallets are on, and ecosystem tokens if the Ecosystem addon is installed. A wallet type you have switched off platform-wide does not appear here at all.

Enabling ECO currencies is possible only when Ecosystem is installed, but a platform that later disables or loses the addon keeps the saved map. Pricing an ECO currency goes through the ecosystem matching engine; without it the price resolves to zero and the buyer sees "Could not determine price for …" at the moment of payment.

Remember the two-list rule: a currency must be enabled here and be on the merchant's own allowedCurrencies. The error message tells you which list is short — "not enabled for payments" is this page, "not supported by this merchant" is theirs.

General

Master switch. Off blocks merchant registration and every payment, and makes the payout job skip its entire run

How long an unpaid checkout session survives, in minutes. Used when the merchant does not send expiresIn

Default payout schedule for newly registered merchants, and the fallback for a merchant with none: INSTANT, DAILY, WEEKLY or MONTHLY

Global test mode. Stored, exposed in the settings object, and read by no code path

gatewayTestMode is on the General tab and is inert. What decides whether a payment is live or test is the prefix of the API key that created it — sk_test_ produces a test payment, sk_live_ a live one. There is no switch that forces an entire platform into test mode. If you need that, disable the gateway.

The payout schedule dropdown offers BIWEEKLY and MANUAL alongside the four real values. Neither is implemented: the payout job understands INSTANT, DAILY, WEEKLY and MONTHLY, and anything else falls through to daily behaviour. Do not pick them.

Fees and limits

Default percentage fee for new merchants, e.g. 2.9 for 2.9%

Default fixed fee per payment for new merchants, in USD

Smallest payment the platform will accept, checked on every create call

Largest payment the platform will accept, and the per-transaction limit new merchants are seeded with

Daily volume ceiling copied onto new merchants. Never enforced

Monthly volume ceiling copied onto new merchants. Never enforced

Default payout threshold for new merchants — a payout below this is not created

gatewayMinPaymentAmount and gatewayMaxPaymentAmount are the two that bite on every single payment, for every merchant, regardless of their own configuration. They are the real ceiling and floor.

Both are described as USD on the settings screen and compared directly against the payment's amount in whatever currency the merchant chose. A maximum of 10000 therefore rejects a payment of 10,001 JPY (about $65) and allows one of 9,999 BTC. If your merchants price in anything other than a dollar-like unit, set these deliberately — or set them wide and rely on the per-merchant transactionLimit, which has the same unit problem but at least is per merchant.

The daily and monthly limits are copied to gateway_merchant.dailyLimit and .monthlyLimit, displayed in both dashboards, and read by nothing. There is no rolling-volume check anywhere in the product.

Security

Require the applicant to pass the use_gateway KYC feature before they may register as a merchant

Create merchants ACTIVE instead of PENDING — but only when gatewayRequireKyc is also on

The KYC check goes through the platform's shared feature gate for use_gateway, so which verification level satisfies it is decided by your KYC level configuration, not here. A refusal is a 403 with the reason, not a generic error.

gatewayAutoApproveVerified on its own does nothing. Merchants are created ACTIVE only when both switches are on — the rule reads "auto-approve the people we made pass KYC". And even then verificationStatus is still written as PENDING, so an auto-approved merchant can trade immediately and still cannot mint an additional API key until a human verifies them.

Webhooks

Intended retry count for failed webhook deliveries. Stored and never read

Intended delay between retries, in seconds. Stored and never read

Delivery is fixed in code: five attempts, with a backoff ladder of 1 minute, 5 minutes, 30 minutes, 2 hours and 24 hours, and a 30-second timeout per attempt. Changing either field on this tab changes nothing. See Webhooks.

Checkout appearance

Five checkout designs ship — Starter, Dark Premium, Purple Glass, Luxury Gold and CyberTech — and there is a preview tool at /admin/gateway/settings/design that renders any of them against nine simulated states (not signed in, loading wallets, sufficient balance, insufficient balance, no wallet, multi-wallet, processing, success, error) at mobile, tablet, desktop and full width.

The live design is chosen by the gatewayCheckoutDesign setting, which defaults to v2 (Dark Premium) and has no field on the settings screen. The preview page has no Save button — it is a viewer. To change the live checkout you set that key through the platform settings, and an unrecognised value falls back to v2 rather than erroring.

Settings that live elsewhere

Two things people look for on this page and will not find:

APP_PUBLIC_URL is an environment variable, not a setting. It is what makes the checkout URL reachable, and unset it points every merchant at localhost. See Install.
Per-merchant fees and limits are on the merchant record. This page only seeds new registrations.

Next: API and data model.