Overview
Stripe is the most developer-focused payment processing platform available — the payment infrastructure that powers a significant proportion of the world's online commerce, from individual SaaS subscriptions to high-volume marketplace transactions. Stripe's API design, documentation quality, testing infrastructure, and the breadth of its payment and financial services make it the default choice for technology teams building payment functionality into web applications, platforms, and marketplaces.
Stripe's product surface covers significantly more than basic payment processing. Payments — card payments, bank transfers, local payment methods across 135+ currencies. Billing — subscription management, invoice generation, metered billing, trial periods, coupon and discount management. Connect — multi-party payment flows for platforms and marketplaces, with automatic fee splitting and payout management. Financial Connections — secure access to customer bank account data for bank transfer verification and financial data. Radar — machine learning-based fraud detection. Tax — automatic tax calculation and reporting. Issuing — custom card programme management. Each of these products has its own API surface and integration requirements, and many production Stripe integrations combine multiple products.
The Stripe API is a REST API that has maintained consistent design principles since its founding — predictable resource URLs, consistent HTTP methods, comprehensive error responses, webhook-based event delivery, and the idempotency key mechanism that makes retry logic safe. Stripe's API versioning model — explicit version pinning with controlled upgrade paths — means that integrations do not break unexpectedly when Stripe releases new API versions.
We build Stripe integrations for SaaS businesses, e-commerce operations, marketplaces, and platforms that need reliable, production-quality payment processing — covering the full range of Stripe's products from basic payment acceptance through complex multi-party marketplace payment flows.
What Stripe Integration Covers
Authentication and API keys. Stripe uses API key authentication with separate keys for test and live environments.
API keys: the Stripe secret key (sk_live_... for production, sk_test_... for test) passed in the Authorization: Bearer {secret_key} header or as the username in HTTP Basic authentication. The publishable key (pk_live_..., pk_test_...) used in client-side JavaScript for Stripe.js and the Payment Element — safe to expose in frontend code because it cannot perform server-side actions.
Restricted keys: Stripe restricted API keys that limit access to specific resources and operations — the key that can only read customer data and create payment intents, without access to payout management or account configuration. The principle of least privilege applied to Stripe API access.
API versioning: the Stripe-Version header that pins the integration to a specific Stripe API version — ensuring that Stripe API changes do not silently break the integration. The version string (2024-06-20 format) that locks the response format regardless of Stripe's current default version.
Payment Intents — the modern payment flow. Stripe's Payment Intent API is the recommended approach for accepting payments, handling 3D Secure authentication, and managing complex payment flows.
Payment Intent creation: the POST /v1/payment_intents endpoint for creating a Payment Intent. The Payment Intent with amount (in the smallest currency unit — cents for EUR/USD, pence for GBP), currency (lowercase ISO 4217 code — eur, usd, gbp), payment_method_types (the allowed payment methods — ["card"], ["card", "ideal", "sepa_debit"]), confirm (true to confirm immediately with a provided payment method, false for client-side confirmation), customer (the Stripe customer ID for saved payment method access), metadata (custom key-value pairs for internal reference), and idempotency_key for safe retries.
Client secret: the client_secret in the Payment Intent response — the credential passed to the client-side Stripe.js for payment confirmation. The client secret that authorises the browser to confirm the payment without exposing the secret API key.
Payment confirmation flow: the server creates the Payment Intent and returns the client_secret to the frontend. Stripe.js uses the client_secret to confirm the payment — handling card details collection, 3DS authentication, and payment submission without the server seeing raw card data.
Payment Intent status: the Payment Intent lifecycle — requires_payment_method (initial state), requires_confirmation (payment method attached, awaiting confirmation), requires_action (3DS authentication required), processing (payment submitted to card network), succeeded (payment completed), canceled (payment cancelled). The webhook events that notify the server of status transitions.
Stripe.js and Payment Element. The client-side Stripe library for secure payment data collection.
Stripe.js: the JavaScript library loaded from https://js.stripe.com/v3/ that provides the Payment Element and other UI components. The Stripe(publishableKey) initialisation that creates the Stripe instance.
Payment Element: the embedded UI component that renders a complete payment form — card number, expiry, CVC, postal code, and the other fields required for the selected payment method. The Payment Element that adapts its form fields based on the payment_method_types configured on the Payment Intent — showing iDEAL bank selection for Dutch payments, SEPA debit form for bank transfer payments. The single integration that handles multiple payment methods through a single UI.
stripe.confirmPayment(): the client-side function that submits the payment — collecting the form data, handling 3DS authentication redirects, and returning the payment result. The return_url parameter for payment methods that require a redirect (iDEAL, SEPA).
Webhooks — event-driven payment confirmation. The Stripe webhook system for reliable payment event delivery.
Webhook endpoint: the Stripe webhook endpoint configured in the Stripe Dashboard or via the Webhooks API — the URL that Stripe sends signed POST requests to when payment events occur. The webhook endpoint configured with specific event types to receive — payment_intent.succeeded, payment_intent.payment_failed, invoice.paid, customer.subscription.updated, charge.refunded.
Signature verification: the Stripe-Signature header in every webhook request — the HMAC-SHA256 signature computed from the raw request body and the webhook endpoint's signing secret. The mandatory signature verification that must occur before any webhook payload is processed — using the raw request body (before JSON parsing) and the endpoint's signing secret, not the API secret key. The Stripe library's stripe.webhooks.constructEvent() method that handles verification and returns the verified event object.
Idempotent webhook processing: Stripe may deliver the same webhook event more than once. The idempotent webhook handler that records processed event IDs and skips duplicate events — using the event id as the idempotency key.
Critical webhook events: payment_intent.succeeded for confirming payment completion and triggering order fulfilment. payment_intent.payment_failed for handling payment failures and notifying customers. invoice.paid for confirming subscription payment and maintaining access. invoice.payment_failed for handling subscription payment failures and triggering dunning. customer.subscription.deleted for handling subscription cancellation. charge.dispute.created for managing chargebacks.
Stripe Billing — subscriptions and invoices. The Stripe Billing product for recurring payment and invoice management.
Customer creation: the POST /v1/customers endpoint for creating Stripe customer records — the customer with email, name, phone, address, metadata (the application's user ID for correlation), and the default payment method. The customer ID (cus_...) used in subscription creation, invoice generation, and payment method management.
Payment method attachment: the POST /v1/payment_methods/{paymentMethodId}/attach endpoint for attaching a payment method to a customer after client-side collection. The customer parameter for the customer to attach to. Setting the attached payment method as the customer's default with POST /v1/customers/{customerId} with invoice_settings.default_payment_method.
Subscription creation: the POST /v1/subscriptions endpoint for creating a subscription. The subscription with customer (the Stripe customer ID), items (array of price objects), payment_settings, trial_period_days for trial subscriptions, cancel_at_period_end for scheduled cancellation, and metadata. The subscription that generates invoices automatically at the configured billing cycle.
Price configuration: the POST /v1/prices endpoint for creating prices attached to products. The price with unit_amount (in smallest currency unit), currency, recurring.interval (month, year, week, day), recurring.interval_count for multi-month billing cycles, and product reference. The metered price with recurring.usage_type: "metered" for usage-based billing.
Invoice management: the GET /v1/invoices endpoint for listing invoices. The invoice object with status (draft, open, paid, void, uncollectible), amount_due, amount_paid, hosted_invoice_url (the Stripe-hosted invoice page), and invoice_pdf (the PDF download URL). The POST /v1/invoices/{invoiceId}/finalize endpoint for finalising draft invoices. The POST /v1/invoices/{invoiceId}/pay endpoint for manually triggering payment collection on open invoices.
Metered billing: the POST /v1/subscription_items/{subscriptionItemId}/usage_records endpoint for reporting usage for metered subscriptions — the API call count, the compute minutes, or the other usage metric that triggers billing based on consumption. The usage record with quantity and timestamp.
Coupon and discount management: the POST /v1/coupons endpoint for creating discount coupons — fixed amount or percentage discount, with optional duration (once, repeating, forever) and redemption limits. The POST /v1/customers/{customerId}/discount endpoint for applying a coupon to a customer. The POST /v1/subscriptions/{subscriptionId} with discounts for subscription-level discounts.
Stripe Connect — multi-party payments. The Stripe Connect product for platforms and marketplaces that handle payments on behalf of connected accounts.
Connect account types: Standard accounts (full Stripe dashboard access for connected sellers), Express accounts (Stripe-hosted onboarding with limited dashboard), Custom accounts (platform-controlled with Stripe's liability). The account type that fits the platform's relationship with its sellers.
Connect account creation: the POST /v1/accounts endpoint for creating connected accounts. The account with type (express, custom, standard), country, email, and capabilities (the payment and payout capabilities requested). The onboarding link via POST /v1/account_links for Express and Custom accounts — the URL the seller visits to complete Stripe's identity verification and bank account setup.
Destination charges: the POST /v1/payment_intents with transfer_data.destination (the connected account ID) and application_fee_amount (the platform's fee in smallest currency unit) for routing payment to a connected account with automatic fee deduction. The charge that appears on the connected account's Stripe balance after the platform fee is deducted.
Separate charges and transfers: the two-step approach for more complex marketplace flows — charge the customer on the platform account, then transfer funds to connected accounts using POST /v1/transfers with the destination and amount. The transfer that moves funds from the platform's Stripe balance to the connected account.
Payout management: the connected account payouts to the seller's bank account — managed by Stripe automatically on the configured payout schedule, or triggered manually via POST /v1/payouts on the connected account using the Stripe-Account header to act on the connected account's behalf.
Stripe Radar — fraud prevention. Stripe's built-in fraud detection that evaluates every payment.
Radar rules: the Stripe Dashboard rule configuration for blocking or flagging payments based on risk score, card country, IP country, email domain, or custom metadata. The rule that blocks high-risk payments before they are processed.
3DS enforcement: the Stripe Radar setting that triggers 3D Secure authentication for payments above a risk threshold — adding the authentication step for suspicious payments while allowing low-risk payments to proceed without friction.
Refunds and disputes. Managing refunds and handling payment disputes.
Refund creation: the POST /v1/refunds endpoint for refunding payments. The refund with payment_intent (or charge), amount (partial refund amount in smallest currency unit, omit for full refund), and reason (duplicate, fraudulent, requested_by_customer). The refund that returns funds to the customer's payment method.
Dispute handling: the GET /v1/disputes endpoint for retrieving disputes (chargebacks). The dispute object with status (warning_needs_response, needs_response, under_review, won, lost), the amount, and the evidence_details for the response deadline. The POST /v1/disputes/{disputeId} endpoint for submitting dispute evidence — the evidence object with product description, customer communication, shipping tracking, and other documentation that supports the dispute response.
Idempotency keys. Stripe's mechanism for safe API call retries.
Idempotency key usage: the Idempotency-Key header on every mutating Stripe API call — the unique string that identifies the specific operation attempt. Stripe returns the same response for subsequent requests with the same idempotency key without performing the operation again — preventing duplicate charges from network retry logic.
Key generation: the UUID or other unique string generated per operation — not reused across different operations. The idempotency key stored alongside the pending operation so that it can be reused if the original request fails and needs to be retried.
Integration Patterns
SaaS subscription billing. The subscription flow — customer selects a plan, provides payment method through the Payment Element, the server creates a Stripe customer and subscription, the subscription generates invoices automatically, the webhook confirms each invoice payment and maintains the customer's subscription status in the application database.
E-commerce checkout. The one-time payment flow — customer completes checkout, the server creates a Payment Intent with the order amount, the Payment Element collects card details and handles 3DS, the payment_intent.succeeded webhook triggers order fulfilment.
Marketplace payments. The Connect flow — seller completes onboarding and creates a connected account, buyer purchases from the seller, the platform creates a destination charge that routes payment to the seller with automatic fee deduction, Stripe manages seller payouts to their bank account.
Invoicing. The B2B invoice flow — the server creates a Stripe customer for the business client, creates a Stripe invoice with line items, finalises and sends the invoice, the client pays through the hosted invoice page, the invoice.paid webhook confirms payment and updates the application.
Technologies Used
- C# / ASP.NET Core — Stripe integration using the
Stripe.netNuGet package - TypeScript / Node.js — Stripe integration using the
stripenpm package for both server-side and Next.js API routes - Python — Stripe integration using the
stripePyPI package for Django, Flask, and FastAPI applications - PHP / Laravel — Stripe integration using the
stripe/stripe-phplibrary - Rust — Stripe integration using the
async-stripecrate for Rust-based payment services - Stripe.js / Payment Element — client-side payment collection
- Webhooks — event-driven payment confirmation and subscription lifecycle management
- SQL (PostgreSQL / MySQL) — customer records, subscription state, payment history, invoice records
- Redis — idempotency key storage, webhook deduplication, subscription state caching
- Hangfire / scheduled jobs — dunning management, failed payment retry, subscription reporting
- Docker — containerised payment service deployment
- GitHub Actions — CI/CD pipeline for payment service deployment
Stripe in the Payment Architecture
Stripe's reliability, documentation quality, and API design consistency make it the payment infrastructure that development teams choose when they want to spend their time building product rather than debugging payment edge cases. The webhook delivery reliability, the idempotency key system, the comprehensive test mode that mirrors production behaviour, and the Stripe Dashboard's visibility into every transaction are the operational qualities that distinguish Stripe from less mature payment processors.
For applications that outgrow basic payment acceptance — that need subscription management, marketplace payment flows, or usage-based billing — Stripe's product surface grows with the requirement. The investment in a production-quality Stripe integration pays dividends as the application's payment requirements evolve.
Payment Infrastructure Built to Production Standards
Stripe integrations built to production standards — correct Payment Intent flow with Stripe.js for PCI-compliant card data handling, HMAC-verified webhook processing with idempotent event handling, subscription lifecycle management with dunning and recovery flows, Connect integration for marketplace payment flows, and the monitoring that surfaces payment failures and webhook delivery issues before they affect revenue.