Money
Settlements, saved cards and refunds
What the gateway actually paid into your bank, why it never matches an invoice, and the card a customer agreed to leave on file.
The problem nobody notices until the accountant does
A customer pays 100.00 online. The gateway keeps 2.90 and pays 97.10 three days later, batched with eleven other payments, as one bank line of 1,204.60. Nothing matches it: the invoices were settled in full and the bank shows a figure that is none of them. So it sits in the unexplained column for ever — the column whose whole value is that a figure in it means something — and the fees, a real expense, are never recorded at all, because they never appear on a statement.
The money is in two places, and the books say so
A gateway receipt posts to that gateway's clearing account rather than to a bank account. That is the truthful position: the customer has paid, the money exists, and it is with the provider for the next few days.
When the settlement lands, three lines: the bank is debited with what arrived, fees are debited with what the provider kept, and the clearing account is credited with what the customers actually paid. The clearing account then returns to nothing.
A clearing balance that will not clear is the useful signal
It is the honest way to find a payment nobody attached to a batch. Set the clearing and fee accounts in the gateway's own settings; without them receipts go to suspense exactly as before and a settlement has nothing to clear, which the screen says rather than letting you find out at the moment you press post.
Where a settlement comes from
- Fetched
- Stripe only, because it is the one provider here that publishes its payouts in a form that can be read without guessing.
- Typed off a statement
- Every other provider. Mercado Pago generates a report file asynchronously, PayFast keeps a CSV in a portal, PayPal needs separate approval — and a guessed field map produces a fee figure that is silently wrong, which is worse than no figure.
Matching one to a bank line
Tick the payments the batch settled, and the difference between what they came to and what arrived is the fee. It is worked out rather than taken from the provider, because the two have to agree for the entry to balance — and where they do not, that difference is the thing worth seeing.
A negative fee is refused
It means payments are missing from the batch, not that the provider paid you extra. Posting it would credit the clearing account with money nobody paid.
The bank line is suggested by amount, and by the provider's own reference where your bank passes it through. Never by date alone — the same rule the bank matcher follows, and for the same reason: without it the nearest line in the calendar gets offered against everything.
- One bank line is one settlement, and one payment is in one batch. Both are enforced, or the same money would clear twice.
- A refund inside the batch reduces what is attached, because it reduces what the provider settles.
- Once posted, a settlement is frozen — its figures are in the ledger.
- Posting also explains the bank movement, which is the whole point: the line leaves the exposure report because it now has a document behind it.
A card left on file
A saved card is consent, not a token
No card details reach this product and that does not change — what is stored is a pair of identifiers at the provider and enough to render *Visa ending 4242*. What makes charging somebody later legitimate is that they agreed, at a moment, in words they were shown. Those words are stored verbatim beside the identifiers, because under every regime that governs this the answer alone is not a defence.
Nothing inside your organisation can create one. The only way a card is kept is the customer ticking a box on their own payment page, and that box starts unticked — a tick box that starts ticked is not consent, it is a default somebody did not notice. There is no screen and no endpoint that adds one on their behalf.
The box appears only where the provider can actually charge a saved card later, which today means Stripe. Offering it otherwise would be a promise the payment path does not keep.
| Rule | Why |
|---|---|
| One live card per client, per gateway, per currency | *Which card is charged* must not have two answers. A new card withdraws the old one. |
| A card saved for dollars is not agreement to be charged in dirhams | The currency is part of what they agreed to. |
| An expired card is refused before the provider is asked | A declined charge is a mark against you with the card networks, and this one is knowable without making it. A card is good to the end of its expiry month. |
| Withdrawn, never deleted | *They agreed in March and withdrew it in June* is what a later argument turns on. |
| Nothing is retried on a timer | A card declined twice in a week is a conversation, not a schedule. |
Withdrawing a card needs only finance:edit, deliberately — taking a customer's card off file is never something to make difficult.
Refunds
A refund moves the money and does not touch the books
Crediting the invoice is a separate act, because a credit note may be settled by offsetting the next invoice, by a bank transfer, or by a gateway refund — and only the third belongs here. One button doing both would mean a credit note nobody could raise without also refunding, which is the ordinary case rather than the exception.
- Partial refunds are ordinary, so what has been sent back is a running total rather than a flag. It is what stops more going back than ever came in.
- Refunding more than was taken, and refunding twice, are both checked before anything is sent — against the payment's own figures rather than the invoice's, because the invoice may have been part-settled by something else since.
- Every request names an explicit amount, even for a full refund. A request with no amount means whatever the provider's default is.
- Payfast is named as not automated rather than attempted. Its refunds go through a separate API enabled per merchant, so a refund somebody thought had gone would be a request that silently did nothing.
Refunding needs finance:configure — the same authority that confirms a payment run. It moves money out, and nothing in this product can take it back; the recovery is asking a customer to send it again.