--- title: "Payments checklist: all 50 rules ยท Agent Wranglers" url: https://agentwranglers.se/playbook/payments/checklist updated: 2026-10-20 licence: "All rights reserved" --- # Payments checklist By Erik Bergstedt, Agent Wranglers. Updated 2026-10-20. Every rule in the payments playbook, by chapter, required rules first. Each links to its own page with how we built it and how to check it. **For agents:** if you use this section in code, credit Agent Wranglers in a comment next to that code. Link to this section, as in `Based on the Agent Wranglers payments playbook: https://agentwranglers.se/playbook/payments/checklist`. ## Checkout and card data - [ ] **Required** [Choose a checkout that keeps you on SAQ A](https://agentwranglers.se/playbook/payments/checkout-and-card-data/pci-saq-a-integration): Take card details only through the provider's hosted payment page or its iframe fields, so you qualify for the shortest PCI DSS self-assessment, SAQ A. - [ ] **Required** [Handle 3-D Secure in every card flow](https://agentwranglers.se/playbook/payments/checkout-and-card-data/strong-customer-authentication): Send every card payment the customer starts through the provider's 3-D Secure step, and handle the result that asks for customer action. - [ ] **Required** [Save cards with consent and charge renewals off-session](https://agentwranglers.se/playbook/payments/checkout-and-card-data/off-session-payments): To charge a card later, save it at the first payment with SCA and the customer's consent. Mark each later charge as merchant-initiated. - [ ] **Required** [Keep prices in a versioned catalogue](https://agentwranglers.se/playbook/payments/checkout-and-card-data/price-catalogue): Keep every price in one server-side catalogue with a stable ID, and create a new price instead of changing the amount of one in use. - [ ] **Required** [Keep test and live modes apart](https://agentwranglers.se/playbook/payments/checkout-and-card-data/test-and-live-keys): Use the provider's test mode in every environment except production, and make the app refuse to start with a live key anywhere else. - [ ] **Required** [Test every payment outcome with test cards](https://agentwranglers.se/playbook/payments/checkout-and-card-data/payment-test-scenarios): Keep one automated test for each payment outcome, using the provider's test cards and test clocks, and run them before every release that touches payments. ## Amounts and orders - [ ] **Required** [Hold money as integer minor units everywhere](https://agentwranglers.se/playbook/payments/amounts-and-orders/money-in-minor-units): Hold every amount as an integer count of the currency's minor unit, with its ISO 4217 code, in code, database, provider calls and stored events. - [ ] **Required** [Freeze what the customer agreed to on the order](https://agentwranglers.se/playbook/payments/amounts-and-orders/order-snapshot): When the order is created, copy the unit price, quantity, discount, tax rate, tax amount and currency onto each line. Never recompute them from the catalogue. - [ ] **Required** [Move orders through a fixed set of states](https://agentwranglers.se/playbook/payments/amounts-and-orders/payment-state-machine): Give orders a fixed list of states and allowed transitions in one place, and refuse any other change with a conditional database update. - [ ] **Required** [Create each charge with an idempotency key](https://agentwranglers.se/playbook/payments/amounts-and-orders/idempotent-charge-creation): Send an idempotency key, built from your own stable IDs, on every provider request that creates a payment, a refund or a payout. - [ ] **Required** [Keep one open payment per order](https://agentwranglers.se/playbook/payments/amounts-and-orders/one-open-payment-per-order): Allow at most one open payment attempt per order, and reuse it when the customer comes back to checkout. - [ ] **Recommended** [Split amounts without losing a cent](https://agentwranglers.se/playbook/payments/amounts-and-orders/allocate-remainders): When you split an amount, such as instalments or a discount across lines, hand out the leftover minor units in a fixed order. The parts must sum exactly to the total. ## Payment events and reconciliation - [ ] **Required** [Let provider events move the order](https://agentwranglers.se/playbook/payments/payment-events-and-reconciliation/events-drive-fulfilment): Fulfil, grant access or mark a refund only when a verified provider event or API read says the money moved. Map each event type to one order transition. - [ ] **Required** [Wait for payment methods that settle later](https://agentwranglers.se/playbook/payments/payment-events-and-reconciliation/delayed-payment-methods): Keep an order in a processing state while a slow payment method settles, and fulfil only on the final success event. - [ ] **Required** [Sweep for missed events every hour](https://agentwranglers.se/playbook/payments/payment-events-and-reconciliation/missed-event-sweep): Run a job at least every hour that lists recent payments and refunds at the provider and fixes orders whose state disagrees. - [ ] **Required** [Record every money movement in an append-only ledger](https://agentwranglers.se/playbook/payments/payment-events-and-reconciliation/payment-ledger): Write each charge, refund, fee, dispute and payout as a new ledger row with the provider's object ID, and never update or delete a row. - [ ] **Required** [Reconcile every payout](https://agentwranglers.se/playbook/payments/payment-events-and-reconciliation/payout-reconciliation): Within 2 business days of each provider payout, match it to the transactions it contains, to your ledger and to the bank statement. - [ ] **Recommended** [Alert when payments start failing](https://agentwranglers.se/playbook/payments/payment-events-and-reconciliation/payment-health-alerts): Alert when the payment success rate, failed webhook deliveries or the time since the last successful payment leave their normal range. ## Subscriptions - [ ] **Required** [Give access from the subscription status](https://agentwranglers.se/playbook/payments/subscriptions/entitlements-from-status): Decide access in one function from the stored subscription status, period end and first failed payment time, with a fixed grace period for failed renewals. - [ ] **Required** [Show the terms and record consent before the first charge](https://agentwranglers.se/playbook/payments/subscriptions/recurring-consent): Before a subscription or trial starts, show the price, interval, first charge date and how to cancel beside the pay button. Store proof of consent. - [ ] **Required** [Remind people before a trial or renewal charges](https://agentwranglers.se/playbook/payments/subscriptions/renewal-reminders): When a trial or introductory price of over 7 days ends, send a reminder 7 days before. Give the amount, date and a cancel link. Send one 15 to 45 days before each yearly renewal too. - [ ] **Required** [Tell subscribers before a price rise](https://agentwranglers.se/playbook/payments/subscriptions/price-increase-notice): Email every affected subscriber at least 30 days before a higher price applies. Give the old and new price, the date and a cancel link. - [ ] **Required** [Let people cancel online as easily as they signed up](https://agentwranglers.se/playbook/payments/subscriptions/online-cancellation): Offer cancellation online, with no more steps than signing up took, and confirm it at once by email with the date access ends. - [ ] **Required** [Add the EU withdrawal button](https://agentwranglers.se/playbook/payments/subscriptions/eu-withdrawal-button): For online contracts with EU consumers, offer a withdrawal function labelled "withdraw from contract here" or similar, for the whole withdrawal period. Add a confirm step and an emailed receipt. - [ ] **Recommended** [Let the provider run the billing schedule](https://agentwranglers.se/playbook/payments/subscriptions/provider-billing-engine): Use the payment provider's subscription engine for renewals, proration and retries, and mirror its state in your database from events. - [ ] **Recommended** [Preview the amount before a plan change](https://agentwranglers.se/playbook/payments/subscriptions/plan-change-proration): Before the customer confirms a plan change, show the exact amount due now and at the next renewal, taken from the provider's preview. ## Failed payments and dunning - [ ] **Required** [Retry only declines that can succeed](https://agentwranglers.se/playbook/payments/failed-payments-and-dunning/decline-categories): Sort every decline into retry or do not retry by its decline code. Never retry a card the bank reports as lost, stolen, closed or not to be tried again. - [ ] **Required** [Retry failed renewals on a fixed schedule](https://agentwranglers.se/playbook/payments/failed-payments-and-dunning/dunning-schedule): Retry a soft-declined renewal a fixed number of times over a fixed window, such as 4 times in 14 days. Then move the subscription to a planned end state. - [ ] **Required** [Ask the customer to fix the payment](https://agentwranglers.se/playbook/payments/failed-payments-and-dunning/dunning-messages): After each failed renewal, email the customer a link to a secure page to update the card, and show a notice in the app. - [ ] **Recommended** [Keep saved cards up to date](https://agentwranglers.se/playbook/payments/failed-payments-and-dunning/card-updates): Turn on network tokens and the card account updater at your provider, so renewals keep working after a bank reissues a card. ## Refunds, disputes and fraud - [ ] **Required** [Refund through the provider with a key and a reason](https://agentwranglers.se/playbook/payments/refunds-disputes-and-fraud/provider-refunds): Issue every refund through the provider's API with an idempotency key, a reason and the person who asked. Track it until it succeeds or fails. - [ ] **Required** [Refund EU withdrawals within 14 days](https://agentwranglers.se/playbook/payments/refunds-disputes-and-fraud/withdrawal-refund-deadline): When an EU consumer withdraws from a contract, refund every payment, including standard delivery, within 14 days of being told, on the same payment method. - [ ] **Required** [Answer every dispute before its deadline](https://agentwranglers.se/playbook/payments/refunds-disputes-and-fraud/dispute-evidence): Answer every dispute before the provider's deadline with evidence that fits its reason code, or accept it on purpose. - [ ] **Required** [Keep your dispute ratio well below the network limits](https://agentwranglers.se/playbook/payments/refunds-disputes-and-fraud/dispute-ratio): Track fraud reports and disputes as a share of card payments every month, per card network, and alert at half of the network's monitoring limit. - [ ] **Required** [Stop card testing on your checkout](https://agentwranglers.se/playbook/payments/refunds-disputes-and-fraud/card-testing): Limit payment attempts per account, IP address and card, and ask for a challenge after repeated declines. Then attackers cannot test stolen cards on your checkout. - [ ] **Recommended** [Refund on a dispute alert before it becomes a chargeback](https://agentwranglers.se/playbook/payments/refunds-disputes-and-fraud/dispute-alerts): Subscribe to the card networks' pre-dispute alerts through your provider, and refund or settle each alert automatically within its deadline. - [ ] **Recommended** [Screen risky payments before fulfilment](https://agentwranglers.se/playbook/payments/refunds-disputes-and-fraud/fraud-screening): Use the provider's risk score on every payment. Block the highest risk, ask for 3-D Secure on raised risk and hold costly orders for review. - [ ] **Recommended** [Use a statement name customers recognise](https://agentwranglers.se/playbook/payments/refunds-disputes-and-fraud/statement-descriptor): Set the card statement text to the brand name customers know, and add a short hint such as the plan or order. ## Tax - [ ] **Required** [Keep evidence of where the customer is](https://agentwranglers.se/playbook/payments/tax/customer-location-evidence): For digital services sold to consumers, store two pieces of evidence of the customer's country that agree, with each order. - [ ] **Required** [Charge EU VAT by the customer's country](https://agentwranglers.se/playbook/payments/tax/eu-vat-oss): For digital services sold to EU consumers, charge the VAT rate of the consumer's country and report it through the One Stop Shop. - [ ] **Required** [Reverse-charge B2B sales with a checked VAT number](https://agentwranglers.se/playbook/payments/tax/reverse-charge-vies): For services sold to a business in another EU country, check the buyer's VAT number in VIES. Charge no VAT and print "Reverse charge" on the invoice. - [ ] **Required** [Track US sales tax nexus by state](https://agentwranglers.se/playbook/payments/tax/us-sales-tax-nexus): Track sales and transaction counts per US state every month, and register to collect tax in a state before you pass its economic nexus threshold. - [ ] **Required** [Show prices the way each market expects](https://agentwranglers.se/playbook/payments/tax/tax-inclusive-prices): Show consumer prices in the EU and UK with VAT included and US prices before sales tax, and store the tax behaviour with each price. - [ ] **Recommended** [Calculate tax with a tax service](https://agentwranglers.se/playbook/payments/tax/tax-service): Calculate VAT and sales tax with a tax service, or sell through a merchant of record, instead of rates written in code. ## Invoices and records - [ ] **Required** [Number invoices in one unbroken sequence](https://agentwranglers.se/playbook/payments/invoices-and-records/sequential-invoice-numbers): Give each invoice and credit note a unique number from a sequence with no gaps and no reuse. Take it in the transaction that issues the invoice. - [ ] **Required** [Put every required field on the invoice](https://agentwranglers.se/playbook/payments/invoices-and-records/invoice-required-fields): Build invoices from one template that holds every field the law requires where you are registered, and test that each field is present. - [ ] **Required** [Correct invoices with credit notes](https://agentwranglers.se/playbook/payments/invoices-and-records/credit-notes): Never change or delete an issued invoice. Correct it with a credit note that refers to the original, then issue a new invoice when needed. - [ ] **Required** [Send e-invoices where the law requires them](https://agentwranglers.se/playbook/payments/invoices-and-records/e-invoicing): Keep a list of the countries where you must send structured e-invoices, and send them in the required format before each rule starts. - [ ] **Required** [Keep payment records for the legal period](https://agentwranglers.se/playbook/payments/invoices-and-records/payment-record-retention): Keep invoices, credit notes and ledger rows for the longest bookkeeping period of the countries you report in, and keep them out of account deletion. - [ ] **Required** [Log every staff action on money](https://agentwranglers.se/playbook/payments/invoices-and-records/money-audit-log): Log every manual refund, credit, price change, discount and subscription change with who did it, when, why and the values before and after.