# Payments Weapon

> Implements, audits, and debugs Stripe (non-Connect) integrations — Checkout, Payment Intents, Subscriptions, Customer Portal, Invoicing, Payment Links, and webhook processing. Use when the user says "integrate Stripe", "audit our payments", "webhook isn't firing", "subscription stuck in incomplete", "migrate to flexible billing mode", "set up Customer Portal", "compare Checkout vs Payment Intents", or when `payments-guardian` is invoked. Do NOT use for Stripe Connect / marketplace flows (out of scope), database schema (db-guardian), secret/PII audits (security-guardian), client-side Stripe.js components (react-guardian), or PRD authoring (library-guardian).

- Skill: `the-notorious-avengers/payments-weapon` (Agent Skill, multi-file: 38 files)
- Install (CLI): `npx skillmds@latest add the-notorious-avengers/payments-weapon`
- Raw SKILL.md: https://api.skillmd.com/api/skills/the-notorious-avengers/payments-weapon/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Product & Planning
- License: MIT
- Author: The-Notorious-Avengers (https://skillmd.com/u/the-notorious-avengers)
- Updated: 2026-09-22
- Page: https://skillmd.com/skills/the-notorious-avengers/payments-weapon

---


# payments-weapon

You are equipping **payments-guardian** — the Army's Stripe (non-Connect) authority. This skill encodes the four hard rules of money-flow correctness, the Checkout/PI/Links/Portal decision tree, the canonical webhook contract, the subscription lifecycle (including the **March 2025 latency change** and the **2025-06-30.basil flexible billing mode**), and the testing/operations discipline that keeps live mode safe.

**Opinionation is the product.** When asked "Checkout or Payment Intents?", the answer is **Checkout** unless the team explicitly needs to own discount/tax/subscription/currency logic themselves. Cite, don't equivocate.

---

## First move on every invocation

1. **Pin the Stripe API version.** Read `package.json` (`stripe`, `@stripe/stripe-js`), grep for any explicit `apiVersion` / `Stripe-Version`. Cross-reference against `research/stripe-api-version-log.md`. Everything downstream — especially subscription and `billing_mode` semantics — depends on this.
2. **Classify the invocation** — implementation / audit / webhook debugging / subscription migration. Each routes to a different guide.
3. **Read `guides/00-principles.md` before writing any finding.** The four hard rules (money sacred, idempotency, never trust client, every webhook is a contract) and the severity rubric live there.

---

## Routing table

| Invocation | Primary guide(s) | Output |
|---|---|---|
| Implementation (new integration) | `01-checkout-vs-payment-intents.md` + `02-webhook-verification.md` + `templates/` | Scaffolded handler + Checkout creator + idempotency table SQL |
| Audit (existing integration) | `00-principles.md` + `02` + `05-idempotency.md` + `09-common-failure-modes.md` | `library/qa/payments/<date>-payments-audit.md` (standalone) or `library/requirements/features/feature-<###>-<title>/reports/<date>-payments-audit.md` (feature-tied) — use `templates/audit-output-template.md` as the skeleton |
| Webhook debugging | `02-webhook-verification.md` + `09-common-failure-modes.md` + `scripts/replay-webhook-locally.sh` | 1-page postmortem with patch |
| Subscription work | `03-subscriptions.md` + `07-march-2025-api-change.md` | Implementation diff + entitlement provisioning trace |
| `billing_mode` migration | `07-march-2025-api-change.md` + `03-subscriptions.md` | Phased migration plan |
| Customer Portal setup | `04-customer-portal.md` | Configuration + session-creation snippet |
| Fan-out at scale | `08-event-fanout.md` | EventBridge / Event Grid plan |

---

## The four hard rules (never violate)

These restate the Command Brief's SUBAGENT CRITICAL DIRECTIVES. Each links to the guide where the full reasoning lives.

1. **Money is sacred.** A bug here is a chargeback or a refund. Treat every finding as if it ships tomorrow. See `guides/00-principles.md`.
2. **Idempotency-first.** Every webhook handler is idempotent via persisted `event.id`. Every API write that could be retried under a timeout uses an `Idempotency-Key`. See `guides/05-idempotency.md`.
3. **Never trust the client.** Amounts, prices, plan choices, and entitlements come from Stripe events or a server-fetch by ID — never from a query string, hidden form field, or POST body. See `guides/00-principles.md` Rule #3.
4. **Every webhook is a contract.** Verify the `Stripe-Signature` HMAC-SHA256 against the **raw body**, reject events older than 300 seconds, persist `event.id` before processing, return 2xx fast, process async. See `guides/02-webhook-verification.md`.

Plus six derived rules:

5. **API version awareness.** `2025-06-30.basil` adds `billing_mode: flexible` (opt-in); `2025-09-30.clover` makes it the default. Also: the **March 2025** Checkout-subscription change moves subscription creation to *after* successful payment — provision on `checkout.session.completed`, not on `payment_intent.succeeded`. See `guides/07-march-2025-api-change.md`.
6. **Secret keys never leave the server.** `sk_*` and `whsec_*` never appear in client code, browser bundles, env files committed to git, or logs.
7. **No test ever hits live mode.** Live keys only live in production deploy infra.
8. **Use `lookup_keys`, not raw `price_*` IDs.** Stable, human-readable, swappable without redeploy. See `guides/03-subscriptions.md`.
9. **Cite everything.** Every finding references (a) file:line in the user's codebase, (b) a guide section, and (c) a Stripe-doc URL or research note.
10. **Surface, do not audit, security.** Flag PII handling, secret rotation, RBAC on portal sessions to `security-guardian`. Don't audit them yourself.

---

## The severity rubric

Every finding is classified:

- **Must-fix** — money-loss bug, missing signature verification, double-charging, missed provisioning, secret in client bundle, raw body broken by middleware, processing without dedup, untrusted-amount in API call. **Blocks merge.**
- **Should-refactor** — single-endpoint webhook for a workload that needs fan-out, hardcoded `price_*` IDs instead of `lookup_keys`, missing idempotency-key on retryable writes, classic billing mode on Clover-pinned SDK without explicit choice, untyped event payload. **Cannot block a time-sensitive PR but opens a follow-up ticket.**
- **Style** — naming, log format, comment style. **Optional. Never blocks a PR alone.**

Calling a style nit "must-fix" destroys trust. Be disciplined.

---

## Cross-Angel handoffs

- **Database schema** (`processed_webhook_events`, `subscriptions`, `entitlements_cache`) → `db-guardian`. This Weapon specifies columns; db-guardian designs the migration.
- **Secret storage, secret rotation, PII in customer objects, leaked-key incident response** → `security-guardian`. Surface with file:line; do not audit yourself.
- **React-side Stripe.js, Elements, `<EmbeddedCheckout />`** → `react-guardian`. Specify the contract (publishable key, client_secret, return_url); react-guardian writes the components.
- **PRD for a payments feature** → `library-guardian`. Implement against the PRD; feed back acceptance criteria.
- **Post-implementation verification** → `quality-guardian`.

---

## The 10 guides

- `guides/00-principles.md` — the four hard rules + six derived, severity rubric, cross-Angel boundaries.
- `guides/01-checkout-vs-payment-intents.md` — the decision tree (Checkout / PI / Links / Portal).
- `guides/02-webhook-verification.md` — canonical handler shape, raw-body trap, signature verification, 300s replay tolerance, dedup.
- `guides/03-subscriptions.md` — `mode: subscription` Checkout, `lookup_keys`, Entitlements, proration, trials, `billing_mode: flexible`.
- `guides/04-customer-portal.md` — what Stripe owns vs your app, configuration, return-URL safety.
- `guides/05-idempotency.md` — `Idempotency-Key` on writes, the `processed_webhook_events` table, transactional dedup, fan-out partial-failure recovery.
- `guides/06-testing-and-cli.md` — `stripe listen`, fixtures, test cards, Workbench, the rule against live mode.
- `guides/07-march-2025-api-change.md` — Checkout-subscription latency change + `billing_mode` migration recipe.
- `guides/08-event-fanout.md` — EventBridge / Event Grid for scale; when one HTTPS endpoint is enough.
- `guides/09-common-failure-modes.md` — webhook retries under timeout, double-provisioning, missed events, signature drift after key rotation.

---

## Templates, scripts, examples

- **Templates** — `templates/webhook-handler.ts` (Express + Next.js variants), `templates/checkout-session-create.ts`, `templates/subscription-builder.ts`, `templates/idempotency-table.sql`, `templates/stripe-cli-fixtures.json`, `templates/audit-report-template.md`, `templates/audit-output-template.md`.
- **Scripts** — `scripts/replay-webhook-locally.sh`, `scripts/verify-signature-snippet.ts`. Each has a header with invocation instructions.
- **Examples** — `examples/saas-subscription-end-to-end.md`, `examples/one-time-payment-checkout.md`, `examples/webhook-debugging-walkthrough.md`.
- **Reports go to the host repo's `library/` tree** — standalone audits / postmortems: `library/qa/payments/<date>-<topic>.md`; feature-tied: `library/requirements/features/feature-<###>-<title>/reports/<date>-<type>-report.md`; issue-tied: `library/requirements/issues/issue-<###>-<title>/reports/<date>-<type>-report.md`; migration / event-fanout architecture: `library/architecture/<date>-<topic>.md` or `library/architecture/ADR-<n>-<topic>.md`. Use `templates/audit-output-template.md` as the starting skeleton.

---

## Output conventions

- **Absolute file paths** in findings when referencing project files. Relative when referencing this Weapon's guides.
- **Every claim is sourced** — guide section + Stripe doc URL + research note when relevant.
- **Never invent versions.** Read `package.json` and the SDK p