Payments

Learn about Stripe payments, the append-only transaction ledger, and dispute tracking.

Payments settle into your own Stripe account, using your own keys.

Every capture, refund, dispute and adjustment is written to a payment ledger the database refuses to edit or delete.

That ledger is the point of this page. Order totals are a summary, and summaries can be wrong; the ledger is the list of things that actually happened to the money, and it is built so that it cannot quietly become a different list later.

Stripe is the only wired provider. The Manual bank-transfer row on the settings page is never enabled.

Two records carry all of this:

PaymentTransaction
PaymentDispute

PaymentTransaction is the ledger row. PaymentDispute stores a chargeback.

What the ledger records

Every ledger row is one of five types:

authorization
capture
refund
dispute
adjustment

Between them they cover every direction money can move on an order: held, taken, given back, reversed by a bank, or corrected.

Append-only

The database rejects any attempt to change or delete a ledger row.

A correction is a new row. It is never an edit to an old one.

This is worth understanding rather than just accepting, because it is the difference between records you can reconcile and records you can only hope are right.

An editable ledger cannot answer the question "what happened to this order?" — only "what does someone currently say happened to this order?" Those are the same answer right up until the moment they matter.

So the ledger keeps mistakes as well as money. A wrong amount and the adjustment that corrected it both stay visible, in order, with the times they were written.

An order's financial history stays whole, and it stays whole without depending on anyone's discipline.

Duplicate-proof rows

Each row is unique on three things together:

The provider
The provider reference
The type

So a payment confirmation Stripe sends twice is counted once.

This is not a rare edge case. Payment providers retry confirmations they are not sure you received, which is the correct thing for them to do — and it means your ledger has to be able to see the same event twice and record it once.

The uniqueness includes the type deliberately. A capture and a refund can share a provider reference without one being mistaken for a duplicate of the other.

Currency locked to the order

The database rejects a ledger row whose currency does not match the order's.

A ledger mixing currencies is worse than a ledger missing rows, because the totals still add up — they just add up to a meaningless number. Refusing the row keeps every sum on an order a sum of one currency.

The ceiling on refunds

Refunds are capped at the order total

As each refund row is written, the store recounts every refund already on the order and rejects the write if the running total would pass the order total. A second protection blocks edits and deletes on ledger rows and enforces the currency match.

The recount is what makes this hold. The check is not "is this refund smaller than the order total?" — it is "would every refund on this order, together, come to more than the order was billed?"

That is why refunds issued days apart, by different people, through different routes, still cannot add up past what the customer paid.

Base-currency totals

Each order also stores its total converted to your store's base currency at purchase time.

Revenue figures read that stored value, rather than falling back to the order currency total.

Storing the converted figure at the moment of sale is what keeps reporting consistent as exchange rates move. A quarter's revenue does not change because a currency moved afterwards, and last year's numbers stay the numbers you reported last year.

Drift alarms

An order carries cached totals, and so does a customer. Those cached figures should always agree with what the database computes from the underlying records.

If they ever disagree, a drift row is written for you to act on.

Caching totals is what keeps lists and dashboards fast. Checking them is what keeps them true. A cached figure that has drifted is reported rather than trusted, so a reconciliation problem finds you instead of waiting to be found.

Dispute records

A chargeback is stored with:

Its reason
Its status
Its amount
Its evidence deadline
Whether evidence was submitted
The staff member handling it

That is enough to work a dispute queue without leaving the admin to find out what is outstanding — though the evidence itself is filed with your provider.

Setting it up

Set your Stripe secret key and webhook secret. Settings → Payments verifies the connection when the page loads and shows what Stripe reports back.
Captures, refunds and disputes write ledger rows as they happen.
Reconcile from the ledger, and watch the drift alarms for orders whose cached totals no longer agree with it.

Settings → Payments also holds the checkout trust badges. The day-to-day money work happens on the Refunds and Disputes queues instead.

Which number do I trust

When an order's totals and its ledger disagree, the ledger is the answer. The totals are a cached summary of it, which is exactly why the drift alarm compares one against the other.

For revenue reporting, use the stored base-currency total, since that is the figure recorded at the time of sale and the one the reports read.

For "did this money actually move?", read the ledger row rather than the order status. A row exists because something happened at the provider.

For a disagreement you cannot resolve, remember that nothing has been erased. Every capture, refund, dispute and adjustment is still there in the order it was written.

The reason all of this is built the way it is:

A summary can be recalculated, but a history that was allowed to be edited can never be recovered.