stripe-payments

name	stripe-payments
description	Use when integrating Stripe one-time payments, PaymentIntents, SetupIntents, Checkout, and webhook-driven flows in PHP or Node.js. Covers integration-model selection, SCA / 3D Secure handling, multi-currency, Stripe Tax basics, idempotency, and signed-webhook receivers. Recurring subscriptions, dunning, and metered billing live in subscription-billing.
metadata	{"portable":true,"compatible_with":["Codex","codex"]}

Stripe Payments

Use When

• Integrating Stripe for one-time payments, saved-card flows, or webhook receivers in a PHP or Node.js backend.
• Choosing between Stripe-hosted Checkout, Embedded Checkout, Payment Element, and raw Payment Intents.
• Hardening webhook handlers for signature verification, idempotency, and retry safety.
• Charging across currencies, handling SCA / 3D Secure, or wiring Stripe Tax.

Do Not Use When

• The work is recurring billing, plan changes, dunning, proration, metered usage, or revenue recognition. Use subscription-billing.
• The work is Stripe Connect, marketplaces, or split payments. Out of scope.
• Tax registration strategy and filing operations. Stripe Tax docs handle this directly.

Required Inputs

• Target stack (PHP, Node.js, or both), runtime versions, deploy target.
• UX requirements (hosted redirect, embedded form, custom UI) and PCI scope target.
• Currencies to charge, settlement country, and whether SCA-regulated regions apply.
• Where secrets live (Vault, AWS Secrets Manager, env files in dev only).

Workflow

1. Read this SKILL.md end-to-end, then load referenced deep-dives only as needed.
2. Pick an integration model from §3 before writing code.
3. Implement Customer + PaymentIntent flow, then layer SetupIntent only if saving cards.
4. Stand up the webhook receiver with SDK signature verification and event.id idempotency.
5. Run through the production checklist before shipping.

Quality Standards

• Every Stripe mutation uses an Idempotency-Key.
• Every webhook event is signature-verified against the raw body and deduplicated by event.id.
• Currency amounts are formatted via a decimal_digits helper, never hard-coded * 100.
• Card data never touches your servers. Use Checkout, Payment Element, or Elements with iframe isolation.

Anti-Patterns

• Polling Stripe for state instead of consuming webhooks.
• Using the legacy Charge API for new code instead of PaymentIntent.
• Writing manual HMAC signature verification when an SDK helper exists.
• Returning 2xx from the webhook only after heavy work completes (causes retries on timeout).
• Hard-coding * 100 for amounts, breaking JPY, KRW, UGX, and other zero-decimal currencies.

Outputs

• Working PHP and/or Node.js code that creates Customers and PaymentIntents.
• A signed, idempotent webhook receiver.
• A production checklist mapped to your secrets, observability, and deploy stack.

References

• Use the references/ directory for deep walkthroughs after reading the core workflow below.

Use this skill when Stripe is the payment rail. The goal is safe, retriable, webhook-driven payments that survive replays, partial failures, and SCA challenges.

Load Order

1. world-class-engineering
2. web-app-security-audit, api-design-first, cicd-devsecops (for HTTPS, idempotent endpoints, Vault-managed keys)
3. This skill for Stripe mechanics
4. subscription-billing for recurring billing, dunning, metering, and revenue ops
5. observability-monitoring for PaymentIntent dashboards and webhook lag alerts

§1 Why Stripe and How the Platform Is Structured

Stripe documents three primary ways to accept payments on a website:

• Build a checkout page: Stripe-hosted page, embedded form, or embedded components.
• Accept payments without code: Payment Links create a custom page without code.
• Build an advanced integration: embed a custom Stripe payment form using Elements.

Stripe's official guidance for new builds: prefer the Checkout Sessions API with the Payment Element over direct Payment Intents for most integrations. Use raw Payment Intents only when explicitly required. Source: docs.stripe.com/payments, docs.stripe.com/payments/accept-a-payment.

§2 Core API Objects

Only the objects needed for one-time and saved-card flows. Recurring entities live in subscription-billing.

• Customer — long-lived record with email, name, default PaymentMethod, tax data. Required to save a card for off-session charges.
• PaymentMethod — tokenised card, bank debit, or wallet attachable to a Customer.
• PaymentIntent — modern object that "tracks a payment from creation through checkout, and triggers additional authentication steps when required." Provides automatic authentication handling, no double charges, and explicit SCA support.
• SetupIntent — saves a PaymentMethod for future use without an immediate charge.
• Checkout Session — wraps Hosted or Embedded Checkout; creates a PaymentIntent (or Subscription) under the hood.
• Charge (legacy) — present in the API and referenced from PaymentIntent; do not create directly in new code.

 Customer ──► PaymentMethod
    │             │
    └── PaymentIntent / SetupIntent ──► Charge
        (Checkout Session wraps either)

§3 Choosing an Integration Model

Model	What you build	Card data lives	Complexity	Pick when
Stripe-hosted Checkout	Redirect link or button	Stripe (lowest PCI scope)	2/5	Fastest path, standard pricing pages
Embedded Checkout	Stripe-hosted form mounted in your DOM	Stripe (low PCI scope)	2/5	Want Checkout's logic but stay on-domain
Checkout Sessions + Payment Element	Custom form using Stripe UI components	Stripe (PCI SAQ A)	3/5	Custom UX, multiple payment methods, design control
Payment Intents API direct	Hand-built confirmation flow	Stripe via Elements	Highest	Only when explicitly required

Source: Stripe "Accept a payment" guide.

§4 PHP Integration (stripe-php)

Runtime: PHP 7.2+. Install:

composer require stripe/stripe-php

require_once 'vendor/autoload.php';
$stripe = new \Stripe\StripeClient(getenv('STRIPE_SECRET_KEY'));

Customer creation (verbatim shape from stripe-php README):

$customer = $stripe->customers->create([
    'description' => 'example customer',
    'email' => '[e-mail]',
    'payment_method' => 'pm_card_visa',
]);

PaymentIntent creation. Required: amount (smallest currency unit) and currency. Common optional: customer, payment_method, confirm, off_session, automatic_payment_methods, setup_future_usage.

$paymentIntent = $stripe->paymentIntents->create([
    'amount' => 1999,                   // $19.99 in smallest currency unit
    'currency' => 'usd',
    'customer' => $customer->id,
    'automatic_payment_methods' => ['enabled' => true],
], ['idempotency_key' => $uuidV4]);

Save-a-card flow: create a SetupIntent, confirm it client-side with Elements, then later create a PaymentIntent with customer, payment_method set to the saved method, plus off_session: true and confirm: true.

Full integration walkthrough: references/stripe-php-integration.md.

§5 Node.js Integration (stripe-node)

Runtime: all LTS versions of Node.js 18+. Install:

npm install stripe

Customer creation, ESM / TypeScript (verbatim from stripe-node README):

import Stripe from 'stripe';
const stripeClient = new Stripe(process.env.STRIPE_SECRET_KEY!);

const customer = await stripeClient.customers.create({
  email: '[e-mail]',
});

PaymentIntent:

const intent = await stripeClient.paymentIntents.create(
  {
    amount: 1999,
    currency: 'usd',
    customer: customer.id,
    automatic_payment_methods: { enabled: true },
  },
  { idempotencyKey: crypto.randomUUID() },
);

Full integration walkthrough: references/stripe-nodejs-integration.md.

§6 Webhooks

Webhooks are the durable source of truth for payment state. Polling is a bug.

Endpoint requirements (per docs.stripe.com/webhooks):

• Accept POST with JSON event payloads.
• Return a 2xx before executing complex logic that could time out.
• Register a publicly accessible HTTPS URL per environment (each gets its own whsec_*).

Signature verification. Use the SDK helper rather than implementing HMAC manually:

• PHP: \Stripe\Webhook::constructEvent($payload, $sigHeader, $endpointSecret)
• Node: stripe.webhooks.constructEvent(payload, sigHeader, endpointSecret)

The verifier needs the raw request body. In Express, mount express.raw({ type: 'application/json' }) only on the webhook route. In Fastify, register a buffer parser. In PHP, read file_get_contents('php://input') before any framework body parsing.

Manual verification reference (only if no SDK):

1. Extract t= (timestamp) and v1= (signature) from the Stripe-Signature header.
2. Concatenate timestamp + '.' + raw_body.
3. HMAC-SHA256 with the endpoint secret as key.
4. Constant-time compare against the received v1 signature.
5. Reject if timestamp skew exceeds tolerance (default 5 minutes).

Retry semantics (Stripe-side):

• Live mode: up to 3 days with exponential backoff.
• Sandbox: 3 retries over a few hours.
• Manual replay: up to 15 days via dashboard, 30 days via CLI.
• Manually resending an event does not dismiss Stripe's automatic retries.

Idempotency at the receiver. Persist event.id in MySQL with a unique index. Insert the event row and commit the side effect in the same transaction so replays no-op cleanly.

CREATE TABLE stripe_processed_events (
  event_id     VARCHAR(255) PRIMARY KEY,
  event_type   VARCHAR(100) NOT NULL,
  received_at  TIMESTAMP NOT NULL DEFAULT CURRENT_TIMESTAMP,
  processed_at TIMESTAMP NULL,
  payload_hash CHAR(64) NOT NULL,
  INDEX idx_event_type (event_type, received_at)
);

Combine event.type with data.object.id to identify duplicates that span event IDs (e.g. retried charge attempts).

Idempotency at the sender. Send an Idempotency-Key HTTP header on every POST. Stripe stores the first response's status and body for that key and errors if subsequent requests arrive with mismatched parameters. Use V4 UUIDs (max 255 chars). Stripe may garbage-collect keys after 24 hours.

Common event types to subscribe to:

• payment_intent.succeeded, payment_intent.payment_failed, payment_intent.requires_action, payment_intent.processing, payment_intent.canceled
• checkout.session.completed
• invoice.paid, invoice.payment_failed, invoice.finalized, invoice.upcoming
• customer.subscription.* (delegate handling to subscription-billing)

Full event catalogue and handler patterns: references/webhook-handling.md.

§7 3D Secure / SCA

Stripe requires Strong Customer Authentication in regulated regions; SCA "requires customers to use two-factor authentication like 3D Secure to verify their purchase." The Payment Intents API surfaces this via the requires_action status.

PaymentIntent status enum: requires_payment_method, requires_confirmation, requires_action, processing, succeeded, canceled.

On-session vs off-session (Stripe phrasing):

• On-session: a payment occurs while the customer is actively in your checkout flow and able to authenticate.
• Off-session: a payment occurs without the customer present, using previously-collected payment information.

Rules:

• For on-session flows where you intend to charge later, set setup_future_usage: 'off_session' on the PaymentIntent.
• For off-session flows, create the PaymentIntent with off_session: true and confirm: true.
• If Stripe returns requires_action on an off-session attempt, your dunning logic must email the customer back to authenticate. Hand recovery flows to subscription-billing when this happens inside a renewal cycle.

§8 Multi-Currency

Stripe supports charging "in over 135 currencies."

• Presentment currency: the currency of the charge.
• Settlement currency: the currency accepted by your destination bank account.

If presentment differs from settlement, Stripe converts at deposit time, typically with a 1% FX spread.

Zero-decimal currencies (JPY, KRW, UGX, VND, RWF, and others): the amount value is the actual amount, not minor units. To charge 500 JPY, send amount: 500. For two-decimal currencies, multiply by 100 (10 USD → 1000).

Ship a helper that maps ISO currency to its decimal_digits rather than hard-coding * 100:

const ZERO_DECIMAL = new Set(['BIF','CLP','DJF','GNF','JPY','KMF','KRW','MGA','PYG','RWF','UGX','VND','VUV','XAF','XOF','XPF']);
export function toMinorUnits(amount: number, currency: string): number {
  const code = currency.toUpperCase();
  return ZERO_DECIMAL.has(code) ? Math.round(amount) : Math.round(amount * 100);
}

§9 Stripe Tax Basics

Stripe Tax automates "sales tax, VAT, and GST compliance on all your transactions" and "handles tax obligation monitoring, registrations, calculations, collections, and filings." It also tracks sales against local registration thresholds and alerts when obligations form.

Enable on a Checkout Session or Subscription:

curl https://api.stripe.com/v1/subscriptions \
  -u "$STRIPE_SECRET_KEY:" \
  -d "automatic_tax[enabled]=true"

Validate customer location at creation: -d "tax[validate_location]=immediately".

Tax IDs. Customers can store country-specific Tax IDs (eu_vat, gb_vat, au_abn, and 200+ types). Collect them at Checkout via tax_id_collection: { enabled: true } and persist via customers.createTaxId. For B2B with valid IDs, Stripe applies reverse-charge automatically where applicable.

§10 Local Testing

Test card matrix (success cases):

Brand	Number	CVC
Visa	4242 4242 4242 4242	any 3 digits
Mastercard	5555 5555 5555 4444	any 3 digits
American Express	3782 822463 10005	any 4 digits
Discover	6011 1111 1111 1117	any 3 digits
Diners Club	3056 9300 0902 0004	any 3 digits
JCB	3566 0020 2036 0505	any 3 digits

All accept any future expiration date. Sandbox mode is isolated; test-key transactions don't move funds.

Decline / authentication cards: 4000 0025 0000 3155 (3DS required), 4000 0000 0000 0002 (generic decline), 4000 0000 0000 9995 (insufficient funds), 4000 0000 0000 0341 (attach succeeds, first off-session charge fails). Pull the full table from docs.stripe.com/testing when authoring decline tests.

Stripe CLI for local webhooks:

stripe login
stripe listen --forward-to localhost:4242/webhook
stripe trigger payment_intent.succeeded
stripe trigger invoice.payment_failed

The CLI prints a webhook signing secret on first run; pass it as the endpoint_secret argument to the SDK verification helper.

§11 Production Checklist

• Live and test secret keys stored only in Vault (or equivalent secrets manager); rotated via the cicd-devsecops runbook; never in committed .env.
• Restricted API keys (rak_*) used for read-only or scoped integrations; full secret keys live only in admin operations.
• Webhook endpoint verified with the SDK helper; raw body preserved end-to-end.
• Webhook handler is idempotent: event.id persisted with a unique index in MySQL; side-effect commit in the same transaction.
• Idempotency-Key (V4 UUID) on every server-side paymentIntents.create call.
• PaymentIntent status transitions observed via dashboards (cross-ref observability-monitoring).
• Currency amounts formatted via toMinorUnits(), not * 100.
• Test-mode webhook fixtures committed to repo; Stripe CLI replay wired in CI.
• TLS 1.2+ enforced; non-HTTPS webhook delivery rejected.
• Webhook secret rotation runbook in place: create new endpoint secret, deploy with both old and new for 24h, remove old.
• Stripe request IDs and webhook event IDs logged with internal correlation IDs.
• Full API keys and full webhook payloads never logged at info level (PAN last-four and PII).

Standards

Security. Never store raw card data; use Stripe-hosted collection or Elements. Keep secret keys server-side only. Verify every webhook signature and reject unsigned payloads. Stripe's redirect and hosted-field model keeps card data off your servers, limiting PCI scope to SAQ A.

Data and state. Stripe object IDs map to internal customer and entitlement records. Access derives from PaymentIntent and Invoice state through verified events. Refunds and cancellations update internal state through durable transitions, never optimistic writes.

UX. Tell the user whether payment is pending, requires action, failed, or complete. Surface SCA prompts immediately. Offer self-service payment-method updates.

Operations. Log Stripe request IDs, webhook event IDs, and internal correlation IDs together. Keep a replay-safe processor and a manual reprocess path. Emit release markers around payment-flow changes.

Review Checklist

• Integration model in §3 chosen explicitly; PCI-scope target documented.
• Customers and payment methods stored by reference, not raw card data.
• PaymentIntents handle requires_action and async completion.
• Save-a-card flows use SetupIntent then off-session PaymentIntent with confirm: true.
• Every Stripe mutation uses Idempotency-Key (V4 UUID).
• Webhooks verify signatures against the raw body and are replay-safe via event.id + unique index.
• Currency math goes through a decimal_digits helper.
• Test mode covers SCA challenge, decline, insufficient funds, and webhook signature failure.
• Stripe Tax enabled where required; tax IDs collected for B2B.
• Production checklist completed before promoting to live keys.

Companion Skills

• subscription-billing — recurring billing, plan changes, dunning, proration, metered usage, revenue recognition, customer portal.
• saas-accounting-system — double-entry posting of Stripe settlements, refunds, FX conversions.
• ai-saas-billing — AI module gating and per-tenant token metering on top of Stripe.
• web-app-security-audit — payment endpoints, webhook handlers, key-handling posture.
• cicd-devsecops — Vault-managed key rotation and secret distribution.
• observability-monitoring — PaymentIntent dashboards and webhook lag alerts.

Sources

• references/stripe-php-integration.md — PHP 7.2+ patterns for Customers, PaymentIntents, SetupIntents, and webhooks.
• references/stripe-nodejs-integration.md — Node.js 18+ / TypeScript patterns for the same flows.
• references/webhook-handling.md — event catalogue, dedup rules, idempotent state updates.
• ../subscription-billing/SKILL.md — recurring billing, dunning, metered billing, revenue ops.
• ../saas-accounting-system/SKILL.md — accounting integration for Stripe settlements.
• ../web-app-security-audit/SKILL.md — security audit for payment endpoints.
• Stripe Payments overview: docs.stripe.com/payments
• Stripe "Accept a payment": docs.stripe.com/payments/accept-a-payment
• Stripe Payment Intents overview: docs.stripe.com/payments/payment-intents
• Stripe API — Create a PaymentIntent: docs.stripe.com/api/payment_intents/create
• Stripe Webhooks: docs.stripe.com/webhooks
• Stripe API — Idempotent Requests: docs.stripe.com/api/idempotent_requests
• Stripe API — Event Types: docs.stripe.com/api/events/types
• Stripe Currencies: docs.stripe.com/currencies
• Stripe Tax: docs.stripe.com/tax and docs.stripe.com/tax/subscriptions
• Stripe Customer Tax IDs: docs.stripe.com/billing/customer/tax-ids
• Stripe Testing: docs.stripe.com/testing
• stripe/stripe-php README: github.com/stripe/stripe-php
• stripe/stripe-node README: github.com/stripe/stripe-node