Payment Integration Pack

We built the Payment Integration Pack because we watched too many engineers treat payments like a feature rather than a critical system. You drop a Stripe.js snippet into your frontend, call create_payment_intent, and think you're done. That's how you get invoice.payment_failed events that never reach your database, or worse, duplicate charges when a network blip triggers a retry storm.

The complexity isn't in the initial API call; it's in the state machine that keeps your database in sync with Stripe's reality. Payment providers are asynchronous by design. A transaction can be processing, succeeded, failed, or canceled, and your system needs to react to every single transition without losing money or locking out paying customers ^[1]. Without a structured, AI-guided workflow, you're just guessing at error handling and leaving your revenue on the table.

If you're currently maintaining a fragile webhook handler or debugging proration logic at 2 AM, you need a better way. This pack gives your AI the canonical knowledge to implement secure, compliant, and idempotent payment workflows from day one.

The Webhook Trap: Why "Just Call the API" Fails

Most integration guides stop at the checkout button. They show you how to create a customer and charge a card. They don't show you what happens when the user's bank declines the charge three seconds later, or when the webhook payload arrives out of order.

We've seen teams build custom webhook handlers that miss signature verification, leaving them vulnerable to replay attacks. We've seen handlers that don't check idempotency keys, resulting in double charges when Stripe retries a failed delivery. We've seen teams that ignore the customer.subscription.updated event, causing entitlements to expire prematurely or persist indefinitely.

The problem is that payment logic is stateful. A simple POST request doesn't capture the lifecycle. You need a system that understands the difference between a checkout.session.completed event and a invoice.payment_succeeded event, and routes each to the correct business logic. Without a spec-driven approach, your code becomes a spiderweb of if/else statements that break the moment a new edge case appears.

The Hidden Tax of Broken Payment State

Every hour you spend debugging a race condition in your subscription logic is an hour you aren't shipping features. The cost of a bad payment integration isn't just engineering time; it's revenue leakage and customer churn.

Consider the cost of a missed event. If your handler fails to process a subscription.deleted event, a churned customer keeps access to your product. If you miss a trial_will_end event, you lose the opportunity to upsell before the trial expires. These aren't theoretical risks; they're daily realities for platforms without robust event routing.

The financial impact compounds quickly. A single duplicate charge can trigger a chargeback, which costs you the transaction amount plus a fee and damages your Stripe account health. If your webhook handler doesn't return a 200 OK immediately, Stripe will retry, potentially causing a cascade of duplicate transactions that you'll have to manually reconcile later.

We've seen teams lose thousands in revenue because their "simple" integration couldn't handle a retry storm. The cost isn't just the engineering hours spent fixing the bug; it's the support tickets, the refunds, and the trust you've lost with your customers. When a user sees a failed payment they never authorized, they don't blame your code; they blame your brand.

When Proration Logic Breaks at Scale

Imagine a SaaS team launching a new tiered pricing model. They use a standard checkout flow, but when a user upgrades mid-cycle, the proration logic breaks. The customer.subscription.updated event fires, but the team's handler doesn't account for the partial period credit. The user gets charged the full amount for the new plan while still having the old plan active.

Meanwhile, a webhook retry causes a duplicate transaction entry ^[2]. The support ticket queue explodes. The engineering team is pulled off feature work to manually fix the billing records. This isn't a hypothetical edge case; it's the exact friction point that kills retention for growing platforms.

A proper implementation requires a spec that defines these transitions clearly. You need a subscription API that handles plan changes, trials, and cancellations consistently. You need a webhook handler that can process events in any order and still produce the correct final state. You need a validation layer that catches these issues before they hit production.

If you're building a subscription business, you can't afford to treat billing as an afterthought. You need a workflow that covers the entire lifecycle, from checkout to churn. This is where a structured approach pays off. By defining your API spec upfront and validating it with tools like Spectral, you can catch errors early. By using a reference implementation for your webhook handler, you can ensure that every event is processed securely and idempotently.

What Changes When Your AI Knows the Lifecycle

With the Payment Integration Pack installed, your AI understands the full subscription lifecycle. It doesn't just write code; it writes correct code. The pack includes a skill.md orchestrator that guides your AI through secure payment integration workflows, referencing all templates, scripts, validators, and examples.

Here's what you get when you install the pack:

Idempotent Webhooks Out of the Box: The templates/webhook-handler.js implements signature verification, idempotency, and event routing for customer.subscription., checkout.session., and invoice. events. It mirrors Stripe's official patterns for safe payload processing and HTTP 200 acknowledgment, so you don't have to reinvent the wheel. Linted API Specs: The templates/subscription-api-spec.yaml defines endpoints for checkout session creation, subscription retrieval, plan management, and webhook endpoint registration. The validators/spectral-rules.yaml enforces security requirements (API key/Bearer auth), validates required fields, and checks for proper error response structures aligned with Stripe API standards. This catches 12 issues your team misses before you commit. Secure Environment Setup: The scripts/setup-stripe-env.sh validates key formats (pk_test_, sk_test_), generates a secure webhook signing secret, creates a .env template, and verifies connectivity to Stripe's test API using curl. You can start testing securely from minute one. PCI Compliance Knowledge: The references/pci-compliance.md covers PCI Level 1 certification, Attestation of Compliance process, data minimization strategies, tokenization best practices, and secure key management. This helps you reduce your merchant scope and avoid storing sensitive card data. Webhook Best Practices: The references/webhook-best-practices.md details event types, retry mechanisms, idempotency requirements, signature verification workflows, and handling subscription state transitions like trial_will_end and subscription.deleted. This is your canonical knowledge base for webhook architecture. Worked Examples: The examples/subscription-lifecycle.md provides a worked example detailing the end-to-end subscription flow. It covers checkout initiation, trial management, payment failure handling, entitlement provisioning, and customer portal redirection, referencing code from templates and scripts for practical implementation.

This pack integrates seamlessly with other tools in our ecosystem. If you're also looking to implement payment with Stripe for web applications, this pack provides the deeper lifecycle management you need. For teams focused on subscription billing, the pack's proration logic and event routing will save you weeks of development time. The subscription commerce workflow complements this pack by defining the broader business phases, while the payment orchestration workflow helps you select and integrate multiple gateways. If you're building a full-stack SaaS, the Next.js SaaS starter pack pairs perfectly with this integration pack for a complete billing dashboard.

What's in the Payment Integration Pack

The pack is a multi-file deliverable designed for production use. Every file is included in the installation and ready to be used by your AI or your team.

skill.md — Orchestrator skill that guides the AI through secure payment integration workflows. References all templates, scripts, validators, references, and examples. Defines the standard operating procedure for PCI compliance, webhook setup, subscription billing, and production validation. templates/webhook-handler.js — Production-grade Node.js webhook handler implementing signature verification, idempotency, and event routing for customer.subscription., checkout.session., and invoice. events. Mirrors Stripe's official patterns for safe payload processing and HTTP 200 acknowledgment. templates/subscription-api-spec.yaml — OpenAPI 3.0 specification for a subscription management API. Defines endpoints for checkout session creation, subscription retrieval, plan management, and webhook endpoint registration. Includes security schemes and consistent error response schemas. validators/spectral-rules.yaml — Spectral ruleset to lint the subscription API spec. Enforces security requirements (API key/Bearer auth), validates required fields, ensures consistent naming conventions, and checks for proper error response structures aligned with Stripe API standards. scripts/setup-stripe-env.sh — Executable bash script to scaffold a secure Stripe environment. Validates key formats (pk_test_, sk_test_), generates a secure webhook signing secret, creates a .env template, and verifies connectivity to Stripe's test API using curl. tests/validate-webhook.sh — Validator script that inspects the webhook handler template for critical security and compliance patterns. Checks for signature verification logic, proper event type handling, error exits on invalid payloads, and HTTP 200 responses. Exits non-zero if any pattern is missing. references/pci-compliance.md — Canonical knowledge on PCI DSS compliance and Stripe's security model. Covers PCI Level 1 certification, Attestation of Compliance process, data minimization strategies, tokenization best practices, and secure key management to reduce merchant scope. references/webhook-best-practices.md — Canonical knowledge on Stripe webhook architecture. Details event types, retry mechanisms, idempotency requirements, signature verification workflows, and handling subscription state transitions like trial_will_end and subscription.deleted.

* examples/subscription-lifecycle.md — Worked example detailing the end-to-end subscription flow. Covers checkout initiation, trial management, payment failure handling, entitlement provisioning, and customer portal redirection. References code from templates and scripts for practical implementation.

Ship with Confidence, Not Boilerplate

Stop reinventing the payment wheel. Every time you write a webhook handler from scratch, you risk introducing a security vulnerability or a billing bug. The Payment Integration Pack gives you a production-ready foundation that your AI can use to generate correct, compliant code every time.

Upgrade to Pro to install the Payment Integration Pack. Install it, run the setup script, and let your AI handle the rest. Ship faster, sleep better, and keep your revenue secure.