alivirgo Stripe Payments Integration AI Skill Guide
Overview & Engine Architecture
Stripe provides payment APIs, Checkout UI, Customers, and Billing subscriptions. Clients never trust browser-reported amounts; the server creates PaymentIntents/Checkout Sessions and verifies webhook signatures. Agents design idempotent webhook handlers, store Stripe customer/subscription IDs, and keep secret keys server-side only.
Browser / app
-> Your API (secret key)
-> Stripe API (Checkout / PaymentIntents / Billing)
Stripe -> webhooks -> Your API (verify signature, update DB)
When to use this skill
- Adding one-time Checkout or PaymentIntent flows
- Building subscription start/cancel/upgrade paths
- Implementing webhook receivers safely
- Debugging test-mode events in the Stripe Dashboard / CLI
Operational directives
- Use test mode keys until go-live; never mix live keys in local
.envcommitted to git. - Verify
Stripe-Signatureon every webhook; reject on failure. - Process webhook events idempotently (store
event.id). - Pass
Idempotency-Keyon creating PaymentIntents and other critical POSTs. - Authorize using your own user session; Stripe customer ID is not proof of login alone.
Checkout Session sketch (server)
const session = await stripe.checkout.sessions.create({
mode: "payment",
line_items: [{ price: "price_123", quantity: 1 }],
success_url: "https://example.com/success?session_id={CHECKOUT_SESSION_ID}",
cancel_url: "https://example.com/cancel",
customer: stripeCustomerId,
});
Webhook verification sketch
const event = stripe.webhooks.constructEvent(
rawBody, // must be raw bytes, not parsed JSON
signatureHeader,
webhookSecret
);
if (await alreadyProcessed(event.id)) return;
switch (event.type) {
case "checkout.session.completed":
await fulfill(event.data.object);
break;
default:
break;
}
await markProcessed(event.id);
Commands
stripe listen --forward-to localhost:3000/webhooks/stripe
stripe trigger payment_intent.succeeded
Common pitfalls
| Pitfall | Result | Fix |
|---|---|---|
| Parsed JSON body for webhooks | Signature verify fails | Use raw body parser |
| Fulfill on client redirect only | Missed payments / fraud | Fulfill on webhook |
| No idempotency | Double charge / double fulfill | Keys + event.id store |
| Price defined only on client | Price tampering | Server-side price IDs |
Best practices
- Map Stripe objects to internal order rows with clear states (
pending,paid,failed). - Log event type + id, never full card payloads (you should not receive PANs with Checkout/Elements properly configured).
- Use Customer Portal for self-serve billing changes when appropriate.
- Review Radar rules before high-risk launches.
Limitations
- Tax, VAT, and compliance requirements vary by jurisdiction (Stripe Tax may apply).
- Connect / marketplace money-flows need additional onboarding and payout logic.
- API versions are pinned per account - read changelogs when upgrading.
Related skills
@nodejs/@fastapi- webhook HTTP servers@postgresql- durable order state@playwright- checkout UI smoke tests in test mode