# Stripe Payments

Payment integration discipline for Stripe APIs.

## Rules

1. **Idempotency keys on every create operation.** Payment intents, charges, subscriptions — any mutating call that can be retried gets an idempotency key. Network retries without keys double-charge.

2. **Webhooks are the source of truth.** Don't rely on the client redirect alone. Handle `payment_intent.succeeded`, `invoice.paid`, and failure events server-side with signature verification.

3. **Never handle raw card data.** Use Stripe Elements, Checkout, or Payment Element. Card numbers on your server put you in PCI scope you don't want.

4. **Test with Stripe's test mode and fixtures.** Use test card numbers and webhook fixtures. Don't test payment flows against live keys.

5. **Amounts in the smallest currency unit.** Cents, not dollars. `$10.00` is `1000`. Floating point money is how you lose cents at scale.

6. **Handle async payment methods.** SEPA, ACH, and bank transfers succeed asynchronously. Your UI and fulfillment logic must handle pending, succeeded, and failed states.

## What This Replaces

Ad-hoc payment code that double-charges on retry, trusts client-side success, and handles only card payments that settle instantly.

## Official Source

Distilled from Stripe's official agent skills.
Full upstream: https://officialskills.sh/stripe/skills/stripe-best-practices