Stripe -- Payment Integration Expert

---

name: stripe description: > Implement Stripe checkout flows, subscriptions, webhooks, Connect platforms, and billing. USE WHEN: User needs to implement Stripe payments, subscriptions, webhooks, Connect marketplace, or billing infrastructure. DON'T USE WHEN: User needs general pricing strategy. Use Deal Flow for pricing models. Use Ledger for financial modeling. OUTPUTS: Checkout implementations, subscription flows, webhook handlers, Connect configurations, billing patterns, migration guides. version: 1.1.0 author: SpookyJuice tags: [stripe, payments, subscriptions, webhooks, billing] price: 19 author_url: "https://www.shopclawmart.com" support: "brian@gorzelic.net" license: proprietary osps_version: "0.1" content_hash: "sha256:424f9a055b3f5880b25d30c4f3a4ba06f6cb2258eb81eb26ff5a62e8f5b0da2a"

#‍​‌‌​‌‌‌‌​‌‌‌​​‌‌​‌‌‌​​​​​‌‌‌​​‌‌​​‌‌‌​‌​​​‌‌​​​‌​​‌‌‌​‌​​‌‌‌​​‌‌​‌‌​‌​‌​​​‌​‌‌​‌​​‌‌‌​​​​​‌‌​​​​​​‌‌​‌‌‌​‌‌​​‌‌​​​‌‌‌​​​​‌‌​​​‌‌​​‌‌​​‌‌​‌‌​​​‌‌‍ Stripe

Version: 1.1.0 Price: $19 Type: Skill

Description

Production-grade Stripe integration patterns for the flows that actually ship in SaaS, marketplaces, and platforms. Stripe's API surface spans 400+ endpoints across payments, billing, connect, and identity — and the docs show happy paths that crumble the moment you hit proration edge cases, webhook ordering issues, or Connect compliance requirements. This skill gives you battle-tested implementations, not quickstart demos.

Prerequisites

• Stripe account (test mode is fine to start)
• API keys: STRIPE_SECRET_KEY and STRIPE_PUBLISHABLE_KEY
• Stripe CLI installed for webhook testing: brew install stripe/stripe-cli/stripe
• For Connect: platform account with Connect enabled

Setup

1. Copy SKILL.md into your OpenClaw skills directory
2. Set environment variables:

   export STRIPE_SECRET_KEY="sk_test_..."
   export STRIPE_PUBLISHABLE_KEY="pk_test_..."
   export STRIPE_WEBHOOK_SECRET="whsec_..."
   

3. Reload OpenClaw

Commands

• "Implement a checkout flow for [product type]"
• "Set up subscription management with [billing model]"
• "Build webhook handlers for [event types]"
• "Configure Stripe Connect for [marketplace model]"
• "Handle subscription proration for [upgrade/downgrade]"
• "Set up metered billing for [usage metric]"
• "Migrate from [old payment flow] to [new flow]"

Workflow

Checkout Flow Implementation

1. Flow selection — Checkout Sessions (Stripe-hosted UI, fastest to implement, handles SCA automatically) vs. Payment Intents (custom UI, full control, more code). Choose Checkout Sessions unless you need pixel-perfect UI control.
2. Product and price setup — create Products and Prices in Stripe (or via API). Decide: one-time vs. recurring, currency, tax behavior (inclusive vs. exclusive), and whether prices are defined in Stripe or dynamically at checkout time.
3. Session creation — server-side endpoint that creates a Checkout Session with: line items, success/cancel URLs, metadata (your internal order ID), customer creation/reuse, and any custom fields.
4. Idempotency — every Checkout Session creation uses an idempotency key derived from your order ID. This prevents double-charges when the user's browser retries on network errors.
5. Success handling — the success page verifies payment status via the session ID (never trust the redirect alone). Poll the session or use expand: ['payment_intent'] to confirm payment succeeded before fulfilling.
6. Error and abandonment — handle: card declined, 3D Secure failures, expired sessions, and abandoned carts. Implement recovery emails for abandoned checkouts.
7. Metadata propagation — attach your internal IDs to every Stripe object (session, customer, subscription) via metadata. This is your cross-reference for reconciliation.

Subscription Lifecycle

1. Plan architecture — define your subscription model: flat-rate tiers, per-seat pricing, usage-based, or hybrid. Map each to Stripe Price objects with the correct billing scheme and recurring interval.
2. Creation flow — Checkout Session in subscription mode (recommended) or create Subscription via API. Handle: trial periods, promo codes, tax calculation, and initial payment failure.
3. Upgrade/downgrade — use proration_behavior correctly: create_prorations for immediate credit/charge, always_invoice to bill immediately, or none to skip proration. The default often surprises teams.
4. Dunning and retry — configure Smart Retries in Stripe settings. Implement invoice.payment_failed webhook handler that: notifies the customer, updates your internal status, and triggers your grace period logic.
5. Cancellation — cancel_at_period_end (access continues until period ends) vs. immediate cancel (refund decision required). Store cancellation reason for churn analysis.
6. Pause and resume — use pause_collection with behavior: 'void' (skip invoices) or 'mark_uncollectible'. Track paused state in your system to limit feature access.
7. Billing portal — configure the Customer Portal for self-service plan changes, payment method updates, and invoice history. Customize allowed actions per plan.

Webhook Handler

1. Endpoint setup — single /webhooks/stripe endpoint with raw body parsing (no JSON middleware) for signature verification. Use stripe.webhooks.constructEvent() with your webhook secret.
2. Event routing — switch on event.type with typed handlers for each event. Critical events: checkout.session.completed, invoice.paid, invoice.payment_failed, customer.subscription.updated, customer.subscription.deleted.
3. Idempotent processing — store processed event IDs. Check before processing. Stripe retries failed webhooks for up to 3 days — your handler WILL see duplicates.
4. Order of operations — Stripe doesn't guarantee event ordering. Your handler must be resilient to: receiving invoice.paid before checkout.session.completed, or subscription.updated before subscription.created.
5. Error handling — return 200 immediately after queuing the event for processing. If your handler throws, Stripe retries with exponential backoff. Implement a dead-letter queue for events that fail processing after N retries.
6. Local testing — stripe listen --forward-to localhost:3000/webhooks/stripe during development. Test each event type with stripe trigger [event_type].

Output Format

💳 STRIPE — IMPLEMENTATION GUIDE
Integration: [Checkout/Subscriptions/Connect/Webhooks]
Mode: [Test/Production]
Date: [YYYY-MM-DD]

═══ ARCHITECTURE ═══
[Flow diagram: client → server → Stripe → webhook → fulfillment]

═══ IMPLEMENTATION ═══
[Code snippets with inline comments explaining each decision]

═══ CONFIGURATION ═══
| Setting | Value | Why |
|---------|-------|-----|
| [config] | [value] | [rationale] |

═══ WEBHOOK EVENTS ═══
| Event | Handler | Action | Idempotency Key |
|-------|---------|--------|----------------|
| [event.type] | [handler] | [what it does] | [key strategy] |

═══ TESTING CHECKLIST ═══
☐ [Test scenario with expected behavior]

═══ COMMON PITFALLS ═══
- [Pitfall and how to avoid it]

Common Pitfalls

• Trusting the success URL — the success redirect URL proves nothing. Always verify payment status server-side via the Checkout Session or Payment Intent before fulfilling orders.
• Ignoring proration behavior — Stripe's default proration behavior may not match your business rules. Explicitly set proration_behavior on every subscription update or you'll get surprise invoices.
• Raw body parsing for webhooks — Stripe signature verification requires the raw request body. If your framework parses JSON before your webhook handler runs, verification will always fail.
• Webhook ordering assumptions — events arrive out of order. Never assume checkout.session.completed arrives before invoice.paid. Design handlers to work regardless of arrival sequence.
• Connect compliance gaps — connected accounts in many countries require identity verification. Implement the account.updated webhook to handle verification requirements and block payouts until accounts are verified.

Guardrails

• Never stores card numbers. All payment data stays in Stripe's vault. Your server never sees, logs, or stores raw card numbers. Use Stripe.js and Elements for client-side tokenization.
• Always uses idempotency keys. Every state-changing API call includes an idempotency key. This prevents double-charges, double-refunds, and duplicate subscriptions.
• Test mode first. All implementation and testing uses sk_test_ keys. Production keys are only used after the full integration is verified in test mode.
• Webhook signatures are verified. Every webhook endpoint verifies the Stripe-Signature header. Unverified webhooks are rejected. No exceptions.
• Metadata is your lifeline. Every Stripe object created includes metadata linking it to your internal IDs. Without this cross-reference, reconciliation is impossible.
• PCI compliance awareness. Flags when an implementation approach would increase PCI scope and recommends alternatives that maintain SAQ-A eligibility.
• Cost transparency. Includes Stripe fee calculations in implementation recommendations so the user understands the per-transaction cost of each approach.

Support

Questions or issues with this skill? Contact brian@gorzelic.net Published by SpookyJuice — https://www.shopclawmart.com