Stripe API Integration Guide

Payment Intents

The PaymentIntent API is Stripe's recommended integration for collecting payments. A PaymentIntent tracks the lifecycle of a payment from creation through confirmation to settlement. It handles complex flows like 3D Secure authentication, multi-step payment methods, and retries automatically.

Each PaymentIntent transitions through statuses: requires_payment_method, requires_confirmation, requires_action (for 3DS), processing, and succeeded. The amount is specified in the smallest currency unit (cents for USD, pence for GBP).

Setup Intents

SetupIntents are used to save a customer's payment method for future use without making an immediate charge. This is essential for subscription sign-ups where the first payment occurs later, or for saving cards on file. The SetupIntent collects and authenticates the payment method (including 3DS if required by the card issuer), then attaches it to a Customer object.

Set usage: "off_session" when you plan to charge the card without the customer present, so Stripe requests the appropriate authentication upfront.

Customers and Subscriptions

The Customer object stores payment methods, email, shipping details, and metadata. Attach one or more PaymentMethods to a Customer, and designate one as the invoice_settings.default_payment_method.

Subscriptions handle recurring billing. Each subscription has one or more items (each referencing a Price). Stripe generates Invoices automatically at each billing period. Key subscription behaviors include proration on plan changes, trial periods, billing anchors for aligning renewal dates, and automatic retries via Smart Retries when payments fail.

Stripe Connect

Connect enables platforms and marketplaces to process payments on behalf of other businesses or individuals. Stripe offers three account types, each with different trade-offs between onboarding control, branding, and payout management.

Platforms collect fees using application_fee_amount on PaymentIntents, or by creating separate Transfers after a charge. Destination charges send payments directly to a connected account; separate charges and transfers offer more flexibility for multi-party settlements.

Webhooks

Stripe sends webhook events to your server for asynchronous notifications. Critical events include payment_intent.succeeded, invoice.payment_failed, customer.subscription.deleted, and account.updated (for Connect).

Always verify webhook signatures using the Stripe-Signatureheader and your endpoint's signing secret. Stripe retries failed deliveries (non-2xx responses) with exponential backoff for up to 3 days. Your handler should return a 200 response quickly and process the event asynchronously.

Idempotency Keys

Include an Idempotency-Key header on POST requests to safely retry operations without creating duplicates. Stripe caches the response for 24 hours. If a request with the same key is received again, Stripe returns the cached response instead of processing a new operation.

Use a unique identifier tied to your business logic, such as an order ID or a UUID generated when the user initiates the payment. This protects against network timeouts and double-clicks.

SCA and 3D Secure

Strong Customer Authentication (SCA) is required under PSD2 for most online payments in the European Economic Area. Stripe handles SCA through 3D Secure 2 (3DS2), which provides a frictionless flow when possible and falls back to a challenge flow when the issuer requires it.

When a PaymentIntent enters the requires_action status, use stripe.handleNextAction() on the client to present the 3DS challenge. For off-session payments (recurring charges), set off_session: true and handle authentication_required errors by bringing the customer back on-session.

Exemptions include transactions under 30 EUR (low-value), merchant-initiated transactions (MIT) for recurring payments with a mandate, and transactions flagged as low-risk by Stripe Radar through Transaction Risk Analysis (TRA).

Key API Endpoints