Payments

Litestore takes payments through Stripe and records every money movement in a ledger. Read this page to set up payments and to know which figure to trust when totals don't agree.

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

Litestore writes every capture, refund, dispute and adjustment to a payment ledger. The database refuses to edit or delete anything in it.

The ledger is what this page is about. Order totals are a summary, and a summary can be wrong. The ledger is the list of what actually happened to the money, and Litestore builds it so that nobody can quietly turn it into a different list later.

Stripe is the only payment provider Litestore is wired to. The settings page shows a Manual bank-transfer row, but it is never enabled.

Litestore uses two records for all of this:

PaymentTransaction
PaymentDispute

PaymentTransaction is a row in the ledger. PaymentDispute stores a chargeback.

What the ledger records

Every ledger row has one of five types:

authorization
capture
refund
dispute
adjustment

Together they cover every way money can move on an order. It can be held, taken, given back, reversed by a bank or corrected.

Append-only

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

To correct a mistake, Litestore adds a new row. It never edits an old one.

This is the difference between records you can reconcile and records you can only hope are right.

An editable ledger can't tell you what happened to an order. It can only tell you what someone currently says happened. Those two answers match until the moment it matters.

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

An order's financial history stays complete, and it doesn't depend on anyone being careful.

Duplicate-proof rows

The database only allows one row for each combination of:

The provider
The provider reference
The type

So if Stripe sends the same payment confirmation twice, Litestore counts it once.

This isn't a rare case. Payment providers resend confirmations when they aren't sure you received them, which is the right thing for them to do. Your ledger therefore has to see the same event twice and record it once.

The type is part of the combination on purpose. A capture and a refund can share a provider reference, and Litestore won't mistake one for a duplicate of the other.

Currency locked to the order

The database rejects a ledger row whose currency doesn't match the order's currency.

A ledger that mixes currencies is worse than one with missing rows. Its totals still add up, but to a meaningless number. By refusing the row, Litestore makes sure every sum on an order is in one currency.

The ceiling on refunds

Refunds are capped at the order total

As Litestore writes each refund row, it adds up every refund already on the order. If the running total would go past the order total, it rejects the write. A second protection blocks edits and deletes on ledger rows and enforces the currency match.

The recount is what makes this work. Litestore doesn't just check whether this one refund is smaller than the order total. It checks whether all the refunds on the order together would come to more than the customer was billed.

So even when different people issue refunds days apart, through different routes, the refunds can't add up to more than the customer paid.

Base-currency totals

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

Revenue figures use that stored value. They don't fall back to the total in the order's currency.

Because Litestore stores the converted figure at the moment of sale, your reports stay consistent as exchange rates move. A quarter's revenue doesn't change because a currency moved afterwards, and last year's numbers stay the numbers you reported last year.

Drift alarms

Orders and customers both keep cached totals. These should always match what the database calculates from the underlying records.

If they ever disagree, Litestore writes a drift row for you to act on.

Cached totals keep lists and dashboards fast. Checking them keeps them correct. Litestore reports a cached figure that has drifted instead of trusting it, so you hear about a reconciliation problem without having to go looking for it.

Dispute records

For each chargeback, Litestore stores:

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

That is enough to work through your disputes without leaving the admin to find out what is outstanding. You still file the evidence itself with your provider.

Setting it up

Add your Stripe keys. Set your Stripe secret key and webhook secret. When you open Settings → Payments, Litestore checks the connection and shows what Stripe reports back.
Let payments come in. Captures, refunds and disputes write ledger rows as they happen.
Reconcile from the ledger. Watch the drift alarms for orders whose cached totals no longer match it.

Settings → Payments also has the checkout trust badges. You do the day-to-day money work in the Refunds and Disputes queues instead.

Which number do I trust

When an order's totals and its ledger disagree, trust the ledger. The totals are a cached summary of the ledger, which is exactly why the drift alarm compares the two.

For revenue reports, use the stored base-currency total. Litestore recorded it at the time of sale, and the reports read it.

To find out whether money actually moved, read the ledger row instead of the order status. A row only exists because something happened at the provider.

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

You can always recalculate a summary. You can never recover a history that someone was allowed to edit.