Payments and billing playbook

A payments playbook for any web app, shop or SaaS that takes money through a payment provider such as Stripe, Adyen, Mollie or Paddle. It covers checkout and card data, amounts and orders, payment events, subscriptions, failed payments, refunds and disputes, tax and invoices. It is written for the developers and AI agents who build billing, and for owners who must trust it.

Money bugs cost twice. A double charge loses a customer, and a missed refund or a wrong invoice can break the law. Each rule here has a check that fails before a customer notices. Legal dates and limits were checked against the official texts in October 2026. This playbook is not legal or tax advice, so confirm with an accountant which rules apply to you.

Start with Checkout and card data. It decides how much card security work you carry. Then read Amounts and orders before you write any code that stores a price.

Some topics have their home elsewhere. Security tests for payments live in abuse and limits. Webhook signing and retries live in webhooks and events. Database transactions live in the data playbook. This playbook links to them and covers the payment side.

Chapters

1. Checkout and card data

   Let the provider hold card data, handle 3-D Secure in every flow, keep prices on the server and test every outcome with test cards.

   • Required 6

2. Amounts and orders

   Hold money as integers with a currency, freeze what the customer agreed to, move orders through fixed states and never charge the same order twice.

   • Required 5
   • Recommended 1

3. Payment events and reconciliation

   Let verified provider events move orders, catch the events you missed, keep an append-only ledger and match every payout to the cent.

   • Required 5
   • Recommended 1

4. Subscriptions

   Let the provider run renewals, give access from one status check, get clear consent, remind before charges and make cancelling as easy as signing up.

   • Required 6
   • Recommended 2

5. Failed payments and dunning

   Retry only declines that can succeed and only on a fixed schedule. Ask the customer to fix the card, and keep saved cards current.

   • Required 3
   • Recommended 1

6. Refunds, disputes and fraud

   Refund through the provider once and on time, answer every dispute with evidence, watch the dispute ratio and stop card testing before it starts.

   • Required 5
   • Recommended 3

7. Tax

   Calculate tax with a service, keep proof of where each customer is, charge EU VAT by country, check VAT numbers and watch US nexus thresholds.

   • Required 5
   • Recommended 1

8. Invoices and records

   Number invoices without gaps, include every required field, correct with credit notes, send e-invoices where required and keep records for the legal period.

   • Required 6

All 50 rules on one page