Gateways
Gateways
Gateways keeps a pool of payment processor accounts (merchant accounts) for your shops and decides which one takes live payments. When a gateway reaches its daily cap, fails too often or has served long enough, payments move to the next one in line by themselves.
In the sidebar under Commerce → Gateways. Handles money: when an agent tries to change anything here, a person is asked to approve it first (Agents and approvals).
The Gateways screen
The page lists the pool in the order gateways would be failed over to. One gateway per store is live at a time.
- Counters at the top: Gateways (still in the pool, retired ones left out), Live (taking payments now, at most one per store) and In reserve (held back on purpose and never rotated to).
- A Processor filter (Stripe or PayPal) and a search box.
- Each row shows the gateway and its account reference, the processor, its State (live or standby), whether it is in reserve, its store ("every store" when none is set), how it Rotates (by hand, on time, on amount or on errors), what it took Today, its Daily cap, its errors and calls, and its place in the Order.
- New gateway adds a payment account. It starts in reserve, so adding one never moves a buyer's payment. Edit gateway renames it or changes its account reference.
- Make live makes a gateway the one taking payments for its store, from now. Retire takes a gateway out of service and hands its live payments on first. Both need
gateways:rotate.
Rotation history, recent errors, checkout endpoints, alert rules and processor events are read through the API and agent tools.
What you can do
Add a gateway
- Choose New gateway and give its name, store, processor and account reference. It starts in reserve and takes no payments.
- Set its processor keys (secret key, publishable key and webhook secret). This needs
gateways:keysand is done through the API only. Keys are never offered to agents. - Put it into rotation by changing its rotation settings, or press Make live.
Decide when payments move
Each gateway has rotation settings:
- Method: by hand (it leaves only when someone makes another one live), on time (after a number of minutes), on amount (once the day's volume reaches a figure) or on errors (once failures pass a percentage).
- Daily cap: a gateway at its daily cap always hands over, whatever its method. 0 means no cap.
- Priority and weight: who takes over first. Weight only breaks ties.
- Reserve: a gateway in reserve is never picked.
A successor must be able to serve: same store, not in reserve, not at its own cap and not the gateway being left. The error rate counts only failures in a recent window, and only once there are at least 20 calls in it. Daily volume resets each day.
Record payments and processor calls
The payment path tells this module what happened, through the API with gateways:record: each processor call (which feeds the error rate) and each payment taken (which counts towards the daily cap). Sending the same reference twice records it once. Recording moves no money by itself.
Processor events (webhooks) arrive at an address per gateway. Each is checked against that gateway's webhook secret, and a redelivered event is recognised rather than counted twice.
Watch checkout endpoints
Add each checkout endpoint as a node. It is health-checked every minute; any answer counts as alive. Disable a node to take it out of rotation.
Set alert thresholds
Set one threshold per metric: error rate, daily volume, no live gateway or node down, each with a severity. Setting a metric again edits its rule.
Who can do what
| Permission | What it lets you do |
|---|---|
gateways:read | See the pool, what is live, rotations, errors, nodes, alert rules and processor events. |
gateways:write | Add gateways in reserve, rename them, and add or change nodes and alert rules. |
gateways:rotate | Choose which gateway takes live payments and what decides it: Make live, Retire and the rotation settings. |
gateways:record | Record payments and calls against a gateway. Moves nothing by itself. Meant for the payment path's own key. |
gateways:keys | Replace a gateway's processor keys. After a change, money arrives in a different merchant account. |
Roles are explained in People, roles and permissions.
What happens on its own
| Job | When | What it does |
|---|---|---|
rotate | Every minute | Resets daily volume and old error counts, then moves payments off every gateway that is due to rotate, to the best one able to take over. A store with nothing able to take over is logged as a warning. |
alerts | Every 5 minutes | Checks each alert rule against the pool and nodes. A breach is written to the server log; it is not sent to your notifications. |
nodes | Every minute | Asks each enabled checkout endpoint whether it answers, and records what it found. |
Needs
Nothing else switched on. Gateways does not post to Books. Shops keep their own payment settings on the Shops page.
What agents can do
This module handles money. Every change an agent asks for goes to a person for approval first.
Read (read-only): gateways.overview, gateways.list, gateways.get, gateways.live, gateways.rotations, gateways.errors, gateways.nodes, gateways.alertRules, gateways.webhooks.
Set up the pool: gateways.create (add in reserve), gateways.update (rename or change account reference), gateways.createNode, gateways.updateNode, gateways.setAlertRule.
Move payments (outside acts, approval): gateways.rotate (make one live), gateways.setRotation (cap, method, priority, reserve, store or processor), gateways.retire (take out of service; destructive).
Replacing keys and recording payments or calls are not agent tools.