payments

Payments & Billing — Moving Money Without Losing It

A practical guide to integrating a payment provider such that money is never double-charged, never silently lost, and always reconcilable. Stack-agnostic; recipes target Stripe as the reference provider, with Adyen / Braintree / PayPal noted where the model differs. The governing mindset: a payment bug is a money bug, and money bugs are visible to finance, regulators, and angry customers.

When to Use This Skill

• Wiring a first charge / checkout — payment intents, hosted fields, confirmation flow.
• Handling a provider webhook (payment_intent.succeeded, charge.refunded, invoice.paid).
• Designing a subscription, metered/usage billing, free trial, proration, or dunning flow.
• Making money movement idempotent — a retried request must never charge twice.
• Issuing refunds, handling disputes/chargebacks, partial captures.
• Reconciling provider state against an internal ledger; closing the books.

Skip when: the work is a generic non-money API endpoint (api-design) or generic auth/injection hardening (security-web) with no money movement — those skills own that. This skill is specifically the financial-correctness layer.

The Five Money-Correctness Invariants

These override convenience every time:

1. Never trust a client-sent amount. The price is computed server-side from the cart/plan, never read from the request body. A client that POSTs {"amount": 1} for a $1000 order must be charged $1000. This is the single most exploited payments bug.
2. Every money mutation is idempotent. A charge/capture/refund call carries an idempotency key derived from the business intent (e.g. order_id), so a network retry returns the original result instead of moving money again. (api-design owns the generic idempotency-key mechanics; this skill mandates it for money.)
3. The provider webhook is the source of truth for state, not the API response. The synchronous create-charge response can be lost (timeout) while the charge still succeeds. Treat the charge as pending until the webhook confirms; reconcile on the webhook.
4. Money is integer minor units, never a float. Store amount_cents (or the currency's minor unit) as an integer. 0.1 + 0.2 != 0.3 in floating point — that rounding error is a regulatory finding.
5. Every movement is double-entry on an append-only ledger. A charge debits one account and credits another; the ledger is immutable (corrections are reversing entries, never edits). This is what makes reconciliation and audit possible. (db-design owns the ledger schema; this skill owns the discipline.)