| name | software-payments |
| description | Designs production payment and billing systems. Use when implementing Stripe, Paddle, Adyen, subscriptions, tax, marketplaces, or mobile purchase flows. |
| compatibility | Portable core. Works on Claude Code and Codex. |
| version | 1.1 |
| last_validated | 2026-07-11T00:00:00.000Z |
Payments & Billing Engineering
Use this skill to design, implement, and debug production payment integrations: checkout flows, subscription lifecycle handling, billing portals, entitlement gating, webhooks, regional pricing, and payment-testing strategy.
Keep the skill focused on system choice and durable integration defaults. Push provider-specific code detail, migration edge cases, and deep implementation examples into the references.
Quick Reference
When to Use This Skill
Use this skill when the primary work is:
- choosing a payment processor, merchant-of-record layer, or billing stack
- implementing hosted or custom checkout
- designing subscription lifecycle and webhook handling
- building feature gating and billing-portal flows
- handling regional pricing, tax-sensitive platform choice, or local methods
- testing and operating checkout or billing workflows
Route elsewhere when the main task is:
Defaults
- Stripe is the default processor for most SaaS and product teams.
- Hosted checkout is the default starting point unless branded custom UI is a hard requirement.
- Webhooks are the source of truth for subscription and entitlement state.
- Initialize provider clients lazily; do not fail builds on missing secrets at import time.
- Omit
payment_method_types unless you intentionally restrict available methods.
- Make every webhook handler signature-verified and idempotent.
- Keep feature gating enforced in three places: registry, API boundary, and UI paywall.
- Treat platform availability, API versions, preview features, and tax behavior as volatile and verify before final advice.
Workflow
- Classify the business model:
- one-time purchase
- subscription
- usage-based billing
- marketplace or multi-party flow
- mobile IAP or hybrid web-plus-app billing
- Choose the stack:
- processor
- merchant-of-record layer if needed
- billing orchestrator if lifecycle complexity justifies it
- Choose the checkout surface:
- Checkout or Payment Links for speed
- Payment Element for custom UX
- Implement the operational core:
- webhook verification
- idempotent processing
- billing portal or self-serve management
- entitlement sync and feature gating
- Add testing, observability, and incident handling before calling the integration production-ready.
ASCII Flow
Payments task
-> Define money movement, provider, customer, and ledger boundary
-> Classify charge, subscription, payout, refund, dispute, or wallet flow
-> Design idempotency, webhooks, reconciliation, and audit trail
-> Implement failure handling, retries, and customer-safe messaging
-> Verify provider rules, network behavior, and compliance constraints
-> Test success, decline, duplicate, timeout, refund, and retry paths
Platform Selection Defaults
| Situation | Default |
|---|
| standard SaaS subscription | Stripe |
| managed tax and seller-of-record model | Paddle or LemonSqueezy; Stripe Managed Payments only where eligible |
| high-volume or enterprise payment ops | Adyen |
| mobile subscription-heavy product | StoreKit 2 or Play Billing as the store-of-record; add RevenueCat only when cross-platform entitlement sync, experiments, or web-plus-store coordination materially justify it |
| UK or EU local rails and direct debit | GoCardless, Mollie, or open-banking providers |
| complex contract, seat, or revenue-recognition logic | Chargebee or Recurly on top of the processor |
| usage-based metering or token billing | Stripe Billing Meters or Lago |
Use references/platform-comparison.md and references/uk-eu-payments-guide.md for the detailed trade-offs.
Known Traps
- Hybrid mobile billing without one entitlement registry. If App Store, Play Billing, and web subscriptions can all grant access, define one canonical entitlement state and one conflict-resolution rule before launch.
- Treating checkout success redirects as purchase truth. Redirects are UX only; provisioning must wait for the verified webhook or store-server notification path.
- Mixing mobile digital-goods policy boundaries with web-SaaS billing assumptions. Apple and Google policy treatment for in-app digital goods is volatile and must be re-verified before final implementation advice.
- Assuming RevenueCat is automatically the default for every mobile subscription stack. It is a coordination layer, not a requirement, and adds its own operational surface.
- Reusing one webhook consumer for unrelated billing side effects without idempotent boundaries. Entitlements, invoicing, CRM sync, and analytics fan-out need separate retry and replay behavior.
- Deferring tax, merchant-of-record, and invoice-issuer decisions until after checkout buildout. Those choices affect product catalog, legal entity exposure, refunds, and support flows.
Common Anti-Patterns
- Selling iOS in-app digital goods through Stripe inside the native app flow.
- Creating separate product or price catalogs in web, mobile, and billing systems with no synchronization contract.
- Using provider object IDs as the only entitlement key instead of a stable internal subscription or account identity.
- Shipping a billing portal without a tested downgrade, cancellation, refund, and grace-period policy.
- Letting the pricing page, checkout copy, entitlement rules, and CRM lifecycle drift independently.
- Treating revenue analytics events as operational truth for access control.
Stripe Integration Defaults
If Stripe is the chosen processor, keep these defaults:
- initialize the server client lazily
- prefer Checkout or Payment Links first
- let Stripe choose dynamic payment methods unless business rules require restriction
- use webhooks, not the client redirect, as the source of truth
- store internal user and tier metadata carefully and validate it before DB use
- use subscription schedules for preplanned billing changes
- keep billing portal enabled for self-serve changes
- use entitlements when packaging changes often, but still enforce authorization in your own API
Use references/stripe-patterns.md for API-version notes, webhook mappings, and migration detail.
Production Readiness Checklist
Common mistakes:
| Mistake | Consequence |
|---|
| Trusting client redirect as proof of purchase | Provisioning before the verified webhook, creating access without payment |
| Hardcoding prices or plan logic in code | Catalog drift and deploy-gated pricing changes |
Setting payment_method_types unnecessarily | Unintentionally restricts available methods |
| Silently failing webhooks instead of retrying | Invisible entitlement loss or dangling subscriptions |
| Treating Apple/Google policy as stable across releases | Store rejection or forced redesign |
See: references/testing-patterns.md, references/webhook-reliability-patterns.md, references/feature-gating-patterns.md, references/ops-runbook-checkout-errors.md
Navigation
Core
Regional and operational
Mobile and in-app purchase
Testing and migrations
July 2026 Regulatory and Scheme Traps
- SCA 3DS2 test card matrix (Stripe): use
4000000000003220 to force a 3DS2 challenge flow; use 4000000000003063 for a frictionless 3DS2 authentication; use 4000002500003155 for a card requiring authentication; use 4000008400001629 for a card where 3DS2 is not supported (fallback to 3DS1 or no-auth). Verify current test card list in Stripe docs before CI test runs — card numbers and behaviour occasionally change between API versions.
- SCA exemptions apply to low-value and MIT transactions: merchant-initiated transactions (subscriptions, saved-payment charges) are exempt from SCA when correctly flagged with
off_session: true and a valid mandate; failing to set this flag causes unexpected declines on renewal charges. EMV 3DS 2.3.1 (August 2022) remains the deployed spec; 2.3.1 is not a hard requirement for exemption handling, but issuer/network support for it varies — a v2.4 pilot with AI-based risk scoring and EU Digital Identity Wallet support is in early 2026 rollout and is not yet something to build against.
- PSD3 / PSR — agreed, not yet in force: the European Parliament and Council reached political agreement on PSD3 and the Payment Services Regulation (PSR) in November 2025; final texts were published in April 2026 and cleared committee/plenary votes in the following weeks. Official Journal publication was expected around mid-2026 but may slip later in the year — verify current status before citing an in-force date. The PSR is a Regulation (direct effect, no national transposition); PSD3 is a Directive requiring member-state transposition, typically 18–24 months after entry into force. Do not build to final PSD3/PSR requirements yet, but flag the expected changes below as architecture risks now.
- PSD3 / PSR changes to design around: mandatory open banking performance/API standards, revised SCA exemption thresholds, stronger consumer liability protections for APP fraud (aligning with the direction already set by UK PSR 2024 mandatory reimbursement), and expanded scope to one-leg-out (one side of the transaction outside the EEA) transactions.
- EU Instant Payments Regulation (IPR) milestones: eurozone PSPs have had to receive instant SEPA credit transfers since 9 January 2025 and send them since 9 October 2025, with Verification of Payee (VOP) required in the eurozone since October 2025. Non-euro EU member states have longer runways: VOP is not required until 9 July 2027, and the obligation to send instant credit transfers in euro from local-currency accounts can extend to 9 June 2028 under specified conditions. Re-verify exact dates against the regulation text before committing an implementation date to a customer.
- Visa Acquirer Monitoring Program (VAMP): Visa lowered the merchant "excessive" fraud-plus-dispute ratio threshold from 2.20% to 1.50% effective 1 April 2026 for the US, Canada, EU, and APAC (CEMEA remains at 2.20% as of this writing). The ratio merges fraud reports (TC40) and disputes (TC15) — a single disputed-and-flagged transaction can count twice. Acquirer-level thresholds (0.5% "above standard", 0.7% "excessive") also apply. Treat these exact percentages as volatile and verify against current Visa program documentation before advising a merchant near the line.
Fact-Checking
- Known bugs, regressions, framework/compiler/runtime footguns, and version-specific crash or workaround guidance must be verified against current primary web sources before being treated as current fact.
- Verify provider availability, preview status, API-version behavior, and tax or compliance claims before final advice.
- Prefer official processor, merchant-of-record, and platform docs over secondary summaries.
- If live verification is unavailable, mark provider-specific claims as unverified.
Learnings Loop
Before applying this skill on a non-trivial task, read learnings.consolidated.md in this directory (and learnings.md if present).
After applying it, if you encountered a pattern worth remembering, a mistake worth preventing, or a domain fact that surprised you, append one dated bullet to learnings.md via agents-skills-feedback-loop/scripts/append_learning.py. Do not modify SKILL.md itself.
