---
topic: system-design
author: Crashtech Editorial
published: Nov 17, 2026 · read: 5 min
---

The 10-Year Evolution of Stripe Payments API: From Tokens and Charges to Payment Intents

How Stripe rebuilt its core payments API four times over 10 years: from synchronous Tokens and Charges to the universal PaymentIntents state machine.

– –

When Stripe launched in 2011, it revolutionized internet commerce with a legendary promise: integrate credit card processing into any web application with just seven lines of code.

A developer could open their terminal, copy a basic curl command, pass a credit card number, and watch a successful payment land in their account in milliseconds.

Yet, that initial seven-line integration was built on an implicit assumption that eventually broke: it assumed credit cards in the United States were the universal model for internet payments.

As Stripe expanded globally into Europe, Asia, and Latin America, the payments landscape fractured. In the Netherlands, 60% of online commerce used iDEAL bank redirects. In Germany, consumers relied on asynchronous bank debits via SEPA. In India, regulatory mandates required Two-Factor Authentication (OTP) on every transaction. In China, consumers paid via mobile QR wallets like Alipay and WeChat Pay.

None of these payment methods fit Stripe’s original API. Over a decade, Stripe was forced to completely re-architect its core payments engine four separate times without breaking backwards compatibility for millions of existing merchants.

+-------------------------------------------------------------------------------+
|                       STRIPE'S 10-YEAR PAYMENTS API EVOLUTION                 |
+-------------------------------------------------------------------------------+

Era 1: Tokens and Charges (2011-2015)
  [Card Number] ---> Token (tok_123) ---> Charge (ch_123)
  * Assumption: Synchronous, single-step, card-only, merchant-initiated.

Era 2: The Sources API (2015-2017)
  [Unify All Payment Methods under Source (src_123)]
  * Flaw: Broken redirect drops; could not track multi-step customer actions.

Era 3: PaymentIntents & PaymentMethods (2018-Present)
  [PaymentIntent (pi_123)] <---> [PaymentMethod (pm_123)]
  * Architectural Split: Decouples "What you want to collect" from "How they pay".
  * Unified Explicit State Machine: Handles 3D-Secure, Async Banks, & Mobile Wallets.

1. Era 1 (2011-2015): The Token and Charge Pattern

Stripe’s original architecture was elegant, minimal, and synchronous:

  1. Client-Side Tokenization: Stripe.js sent raw credit card numbers directly from the customer’s browser to Stripe, returning a single-use token (tok_visa_42). Card numbers never touched the merchant’s application servers, drastically simplifying PCI-DSS compliance.
  2. Synchronous Charge Creation: The merchant’s backend server posted the token to the /v1/charges endpoint:
POST /v1/charges
{
  "amount": 2000,
  "currency": "usd",
  "source": "tok_123456789",
  "description": "Premium Subscription"
}

The server blocked for 800 milliseconds, contacted the Visa/Mastercard payment rail, and returned status: "succeeded".

Why the Token and Charge Pattern Broke

The Token and Charge model made four architectural assumptions that failed outside the United States:

  • Assumption 1 (Instant Finality): Credit cards approve or decline in real time. But European SEPA debits or US ACH transfers take 3 to 5 business days to settle.
  • Assumption 2 (Zero Customer Action): Cards required no customer intervention after clicking pay. But European Strong Customer Authentication (SCA / 3D-Secure) required redirecting the buyer to their banking app to verify biometric authentication before payment could be authorized.
  • Assumption 3 (Merchant-Initiated): The merchant’s server pushed the charge. But bank transfers require the customer to initiate a push payment from their own banking portal.

2. Era 2 (2015-2017): The Sources API and the Redirect Vulnerability

To support international payment methods, Stripe introduced the Sources API (/v1/sources).

The Sources API attempted to unify every payment method (cards, Bitcoin, iDEAL, Alipay, SOFORT) under a single polymorphic Source object.

                  THE iDEAL REDIRECT RACE CONDITION
                  
[Merchant Checkout Page]
       |
       v
1. Create Source (type: "ideal") ---> Status: "pending"
       |
       v
2. Customer redirected to Dutch Bank Portal (ABN AMRO)
       |
       v
3. Customer approves payment inside bank interface
       |
       +---> Case A (Normal): Browser redirects back to merchant return_url.
       |     Merchant server creates Charge. Payment succeeds!
       |
       \---> Case B (The Failure): User closes mobile browser tab after banking!
             Browser never returns to return_url!
             Bank withdrew customer money, but Merchant never created Charge!
             Result: Customer was charged, but order was lost!

In the Sources model, creating a source did not actually capture the payment; the merchant still had to listen for webhooks and manually issue a separate /v1/charges call.

If the customer’s mobile browser crashed during the bank redirect, or if the merchant’s webhook handler timed out, the payment entered an unrecoverable zombie state.


3. Era 3 (2018-Present): The PaymentIntents State Machine

In 2017, ahead of Europe’s mandatory PSD2 Strong Customer Authentication enforcement, Stripe assembled a dedicated engineering task force. The team locked themselves in a conference room for three months to redesign the payments architecture from first principles.

The breakthrough was a fundamental separation of concerns: decoupling the “What” from the “How”.

  1. PaymentMethod (The “How”): Represents the instrument of payment (a credit card, a bank account, an Apple Pay token, a Klarna installment agreement).
  2. PaymentIntent (The “What”): Represents the lifecycle of an intended payment transaction (amount, currency, customer, and multi-step execution state).
+-------------------------------------------------------------------------------+
|                       THE PAYMENTINTENT STATE MACHINE                         |
+-------------------------------------------------------------------------------+

                             +------------------------+
                             |  requires_payment_method|
                             +------------------------+
                                         |
                                         v (Attach PaymentMethod)
                             +------------------------+
                             |   requires_confirmation|
                             +------------------------+
                                         |
                                         v (Confirm Intent)
                             +------------------------+
                             |     processing         | (Async Bank Settlement)
                             +------------------------+
                               /                     \
        Action Required       /                       \  Direct Success
       (3DS / Biometrics)    /                         \
                            v                           v
              +----------------------+        +-------------------+
              |requires_action       |        |    succeeded      |
              +----------------------+        +-------------------+
                     |                                  ^
                     \==== (User completes 3DS) ========/

The Power of requires_action

When a transaction requires two-factor authentication or bank app verification, the PaymentIntent transitions cleanly to status: "requires_action".

Stripe’s client SDKs automatically present the native 3D-Secure modal, handle biometric verification, and resume the transaction without the merchant needing to write custom redirect code for every regional banking law.


4. Four Enduring API Design Lessons from Stripe

Stripe’s 10-year payments migration yields foundational lessons for software architects designing long-lived APIs:

1. Beware Product Debt in Core Data Models

Stripe’s early /v1/charges endpoint baked credit-card-specific fields (cvc_check, card_fingerprint) directly into the root charge object. When bank debits arrived, these fields became awkward nulls. Design core abstractions around business intent, not the physical mechanics of the first vendor integration.

2. Explicit State Machines Beat Implicit Status Flags

Replacing arbitrary string flags (paid: true, refunded: false, pending: true) with a strictly validated, deterministic finite state machine (PaymentIntent statuses) eliminates impossible race conditions across asynchronous webhooks.

3. Backwards Compatibility Requires Creative Pragmatism

When Stripe launched PaymentIntents, requiring merchants to rewrite checkout code threatened platform adoption. Stripe introduced the error_on_requires_action parameter: card-only merchants could use the new API synchronously like legacy charges, while merchants adopting European methods opted into asynchronous state handling.

4. Simplicity is an Architectural Illusion

Seven lines of code looks simple to the developer only because an immense, resilient distributed state machine absorbs the brutal physical complexity of global banking networks underneath.


Architectural Comparison Matrix

DimensionEra 1: Tokens & ChargesEra 2: Sources APIEra 3: PaymentIntents
Primary AbstractionCharge + TokenSource + ChargePaymentIntent + PaymentMethod
Execution FlowSynchronous HTTP POSTFragmented WebhooksUnified Finite State Machine
3D-Secure HandlingFragile manual iframesIncomplete redirect loopsNative SDK modal handling (requires_action)
Asynchronous BanksUnsupportedPartial (Zombies on drop)Full lifecycle tracking (processing -> succeeded)
Multi-Method SupportUS Credit Cards onlyCards + Basic RedirectsUniversal: Cards, Wallets, BNPL, Bank Debits

Summary and Key Takeaways

  1. Assumptions limit global scale: Never hardcode regional conventions (like synchronous US credit cards) into foundational data models.
  2. Decouple intent from instrument: Separate what is being transacted (PaymentIntent) from the vehicle used to pay (PaymentMethod).
  3. Model distributed lifecycles as state machines: Asynchronous bank transfers and biometric 2FA require explicit state machines with clear transition invariants.
  4. Solve redirect fragility on the server: Never rely on customer browser redirects to finalize payments; coordinate state transitions through robust server-to-server webhooks.
  5. Protect developer experience with smart defaults: Absorb real-world regulatory and banking complexity into client SDKs while presenting clean, declarative API surfaces to developers.
Advertisement

/* Comments */