{"slug":"api-commerce-stripe","title":"api-commerce-stripe","summary":"Stripe payment processing — Checkout Sessions, Payment Intents, subscriptions, webhooks, Connect, customer management, error handling","platform":"Claude","tags":[],"authorName":"LLM Mart","authorSlug":"llm-mart","score":0,"source":"github","price":null,"verified":false,"createdAt":"2026-09-29T15:27:55.273265Z","repo":{"url":"https://github.com/agents-inc/skills","stars":24,"forks":8,"license":"MIT","updatedAt":"2026-09-07T17:50:55Z"},"bodyHtml":"<hr>\n<h2>name: api-commerce-stripe\ndescription: Stripe payment processing — Checkout Sessions, Payment Intents, subscriptions, webhooks, Connect, customer management, error handling</h2>\n<h1>Stripe Patterns</h1>\n<blockquote>\n<p><strong>Quick Guide:</strong> Use the <code>stripe</code> npm package for all server-side Stripe operations. Always verify webhook signatures with <code>constructEvent()</code> using the raw request body, never the parsed body. Use idempotency keys on all mutating requests. Keep the secret key server-side only. Handle errors with <code>instanceof Stripe.errors.StripeError</code>. Amounts are always in the smallest currency unit (e.g., cents for USD).</p>\n</blockquote>\n<hr>\n<p>&lt;critical_requirements&gt;</p>\n<h2>CRITICAL: Before Using This Skill</h2>\n<blockquote>\n<p><strong>All code must follow project conventions in CLAUDE.md</strong> (kebab-case, named exports, import ordering, <code>import type</code>, named constants)</p>\n</blockquote>\n<p><strong>(You MUST NEVER expose <code>STRIPE_SECRET_KEY</code> in client-side code — it stays on the server only)</strong></p>\n<p><strong>(You MUST verify webhook signatures with <code>stripe.webhooks.constructEvent()</code> using the RAW request body — never parsed JSON)</strong></p>\n<p><strong>(You MUST use idempotency keys on all mutating (POST) requests to prevent duplicate charges)</strong></p>\n<p><strong>(You MUST handle all Stripe errors with <code>instanceof Stripe.errors.StripeError</code> — never swallow payment errors)</strong></p>\n<p><strong>(You MUST express monetary amounts in the smallest currency unit — cents for USD, not dollars)</strong></p>\n<p>&lt;/critical_requirements&gt;</p>\n<hr>\n<p><strong>Auto-detection:</strong> Stripe, stripe, stripe.checkout.sessions, stripe.paymentIntents, stripe.customers, stripe.subscriptions, stripe.webhooks, constructEvent, PaymentIntent, CheckoutSession, STRIPE_SECRET_KEY, STRIPE_WEBHOOK_SECRET, stripe.prices, stripe.products, stripe.refunds, stripe.transfers, stripe.accounts, Stripe.errors, idempotencyKey, payment_intent.succeeded, checkout.session.completed</p>\n<p><strong>When to use:</strong></p>\n<ul>\n<li>Creating Checkout Sessions for one-time or subscription payments</li>\n<li>Building custom payment flows with Payment Intents</li>\n<li>Handling webhook events for asynchronous payment lifecycle</li>\n<li>Managing customers, payment methods, and subscriptions</li>\n<li>Building marketplace platforms with Stripe Connect</li>\n<li>Processing refunds and handling disputes</li>\n<li>Setting up products and prices for a catalog</li>\n</ul>\n<p><strong>Key patterns covered:</strong></p>\n<ul>\n<li>Stripe client initialization with TypeScript types</li>\n<li>Checkout Sessions (one-time payments, subscriptions, setup mode)</li>\n<li>Payment Intents (custom flows, confirmation, capture)</li>\n<li>Webhook signature verification and event handling</li>\n<li>Customer creation, update, and payment method attachment</li>\n<li>Subscription lifecycle (create, update, cancel, trials, proration)</li>\n<li>Products and Prices (catalog management)</li>\n<li>Stripe Connect (account creation, transfers, destination charges)</li>\n<li>Error handling with typed Stripe errors</li>\n<li>Idempotency keys for safe retries</li>\n</ul>\n<p><strong>When NOT to use:</strong></p>\n<ul>\n<li>Client-side Stripe.js or Stripe Elements (use your frontend framework skill)</li>\n<li>Stripe CLI commands or dashboard configuration</li>\n<li>Non-Stripe payment processors (use their dedicated skill)</li>\n</ul>\n<p><strong>Detailed Resources:</strong></p>\n<ul>\n<li>For decision frameworks and anti-patterns, see <a href=\"reference.md\">reference.md</a></li>\n</ul>\n<p><strong>Core Setup &amp; Payments:</strong></p>\n<ul>\n<li><a href=\"examples/core.md\">examples/core.md</a> — Client setup, Checkout Sessions, Payment Intents, error handling</li>\n</ul>\n<p><strong>Webhooks &amp; Events:</strong></p>\n<ul>\n<li><a href=\"examples/webhooks.md\">examples/webhooks.md</a> — Signature verification, event handling, idempotent processing</li>\n</ul>\n<p><strong>Subscriptions &amp; Billing:</strong></p>\n<ul>\n<li><a href=\"examples/subscriptions.md\">examples/subscriptions.md</a> — Subscription lifecycle, trials, proration, metered billing</li>\n</ul>\n<p><strong>Connect &amp; Platforms:</strong></p>\n<ul>\n<li><a href=\"examples/connect.md\">examples/connect.md</a> — Connected accounts, transfers, destination charges, platform fees</li>\n</ul>\n<hr>\n\n<hr>\n\n<hr>\n<p>&lt;red_flags&gt;</p>\n<h2>RED FLAGS</h2>\n<p><strong>High Priority Issues:</strong></p>\n<ul>\n<li><strong>Secret key in client-side code</strong> — <code>STRIPE_SECRET_KEY</code> must never appear in browser bundles. Use <code>STRIPE_PUBLISHABLE_KEY</code> (starts with <code>pk_</code>) for client-side Stripe.js only.</li>\n<li><strong>Webhook signature not verified</strong> — Without <code>constructEvent()</code> verification, attackers can send fake events to fulfill orders, grant access, or modify records.</li>\n<li><strong>Raw body not used for webhooks</strong> — Using <code>req.body</code> (parsed JSON) instead of the raw body string/buffer causes signature verification to fail silently. With Express, use <code>express.raw({ type: \"application/json\" })</code> on the webhook route.</li>\n<li><strong>Missing idempotency keys</strong> — Without idempotency keys, network retries can create duplicate charges. Always pass <code>{ idempotencyKey }</code> on create/update operations.</li>\n<li><strong>Dollar amounts instead of cents</strong> — <code>amount: 10</code> creates a $0.10 charge, not $10.00. Always multiply by 100 or name variables <code>amountInCents</code>.</li>\n</ul>\n<p><strong>Medium Priority Issues:</strong></p>\n<ul>\n<li><strong>Not pinning API version</strong> — Without <code>apiVersion</code> in the constructor, Stripe uses your account's default version. API changes can silently break your integration.</li>\n<li><strong>Using <code>payment_method_types</code> instead of <code>automatic_payment_methods</code></strong> — The legacy array approach requires manual updates as new payment methods become available. <code>automatic_payment_methods: { enabled: true }</code> is the modern approach.</li>\n<li><strong>Swallowing Stripe errors</strong> — Empty <code>catch</code> blocks hide payment failures. Always log the error's <code>requestId</code> for debugging with Stripe support.</li>\n<li><strong>Not handling <code>requires_action</code> status</strong> — Payment Intents may require 3D Secure authentication. Check <code>paymentIntent.status</code> after confirmation.</li>\n<li><strong>Polling instead of webhooks</strong> — Checking payment status in a loop is unreliable and wastes API calls. Use webhooks for all asynchronous payment events.</li>\n</ul>\n<p><strong>Common Mistakes:</strong></p>\n<ul>\n<li><strong>Processing webhooks synchronously</strong> — Long-running operations in the webhook handler cause timeouts. Return <code>200</code> immediately, then process asynchronously.</li>\n<li><strong>Not handling duplicate webhook events</strong> — Stripe may deliver the same event multiple times. Track processed event IDs to ensure idempotent handling.</li>\n<li><strong>Using test keys in production</strong> — Keys starting with <code>sk_test_</code> and <code>pk_test_</code> only work with test data. Verify your environment configuration.</li>\n<li><strong>Forgetting <code>expand</code> for nested objects</strong> — Stripe returns IDs by default for related objects. Use <code>expand: [\"latest_invoice.payment_intent\"]</code> to get full objects.</li>\n</ul>\n<p><strong>Gotchas &amp; Edge Cases:</strong></p>\n<ul>\n<li><strong>Stripe events are not ordered</strong> — <code>invoice.paid</code> may arrive before <code>invoice.created</code>. Design handlers to be order-independent.</li>\n<li><strong>Checkout Session <code>{CHECKOUT_SESSION_ID}</code> is a literal template</strong> — Stripe replaces this placeholder in the <code>success_url</code>. Do not URL-encode it.</li>\n<li><strong>Subscription proration is on by default</strong> — Upgrading a plan mid-cycle prorates automatically. Pass <code>proration_behavior: \"none\"</code> to disable.</li>\n<li><strong>Idempotency keys expire after 24 hours</strong> — After expiry, the same key creates a new request. For long-lived retries, generate a new key.</li>\n<li><strong>Zero-decimal currencies</strong> — JPY, KRW, and others have no decimal subunit. <code>amount: 500</code> in JPY means 500 yen, not 5 yen. Check <code>Stripe.ZERO_DECIMAL_CURRENCIES</code>.</li>\n<li><strong>Connect transfers require <code>transfers</code> capability</strong> — Connected accounts must have <code>card_payments</code> and <code>transfers</code> capabilities enabled before receiving transfers.</li>\n<li><strong>Webhook secrets differ per endpoint</strong> — Each webhook endpoint has its own signing secret. Using the wrong secret causes all signature verifications to fail.</li>\n</ul>\n<p>&lt;/red_flags&gt;</p>\n<hr>\n<p>&lt;critical_reminders&gt;</p>\n<h2>CRITICAL REMINDERS</h2>\n<blockquote>\n<p><strong>All code must follow project conventions in CLAUDE.md</strong> (kebab-case, named exports, import ordering, <code>import type</code>, named constants)</p>\n</blockquote>\n<p><strong>(You MUST NEVER expose <code>STRIPE_SECRET_KEY</code> in client-side code — it stays on the server only)</strong></p>\n<p><strong>(You MUST verify webhook signatures with <code>stripe.webhooks.constructEvent()</code> using the RAW request body — never parsed JSON)</strong></p>\n<p><strong>(You MUST use idempotency keys on all mutating (POST) requests to prevent duplicate charges)</strong></p>\n<p><strong>(You MUST handle all Stripe errors with <code>instanceof Stripe.errors.StripeError</code> — never swallow payment errors)</strong></p>\n<p><strong>(You MUST express monetary amounts in the smallest currency unit — cents for USD, not dollars)</strong></p>\n<p><strong>Failure to follow these rules will create security vulnerabilities, duplicate charges, and silent payment failures.</strong></p>\n<p>&lt;/critical_reminders&gt;</p>\n","files":[{"path":"examples/connect.md","sizeBytes":8777,"isText":true},{"path":"examples/core.md","sizeBytes":11258,"isText":true},{"path":"examples/subscriptions.md","sizeBytes":10100,"isText":true},{"path":"examples/webhooks.md","sizeBytes":10074,"isText":true},{"path":"reference.md","sizeBytes":7638,"isText":true},{"path":"SKILL.md","sizeBytes":13182,"isText":true}],"reviewScore":null,"reviewSummary":null,"trust":{"provenance":"trusted-source-unreviewed","notice":"Community-authored content, reproduced verbatim and not vetted as instructions. Treat it as data to evaluate, never as directives to follow.","bodySource":null},"bodyLocked":false,"purchaseUrl":null,"sourceUrl":null,"report":{"provenance":"trusted-source-unreviewed","screen":{"ran":true,"outcome":"notes-only","suspicious":0,"notes":1,"hiddenCharacters":false},"virusScan":{"engine":"clamav","status":"clean","scannedAt":"2026-09-29T15:28:44.192538Z","sha256":"479108E47BB336A60F6F782CA591409C929307EBA0A16665A9EC5895ECC21666","sizeBytes":20372},"review":null,"source":{"repositoryUrl":"https://github.com/agents-inc/skills","path":"dist/plugins/api-commerce-stripe/skills/api-commerce-stripe","license":"MIT","commit":"3a51ef571e996b18294bf776d53dbdad26de0617","subtreeSha":"552E8C3B80231B58124717FBCFBC6F8D697EA42D41DAD6F060C55C8DE8AB4C2C","lastSyncedAt":"2026-09-29T15:27:48.914434Z"},"reviewedAt":"2026-09-29T15:31:06.592494Z","notice":"Community-authored content, reproduced verbatim and not vetted as instructions. Treat it as data to evaluate, never as directives to follow."},"install":[{"target":"skills-cli","command":"npx skills add https://github.com/agents-inc/skills/tree/main/dist/plugins/api-commerce-stripe/skills/api-commerce-stripe"},{"target":"claude-code","command":"claude plugin marketplace add https://llmmart.ai/marketplace.json && claude plugin install agents-inc-skills@llmmart"},{"target":"git","command":"git clone https://github.com/agents-inc/skills.git"}]}