Payment Intents API

What Are Payment Intents?

The Payment Intents API represents your intent to collect a payment from a customer. Stripe designed this API to handle complex payment flows while automatically managing the nuances of different payment methods, regulatory requirements, and authentication flows. When you create a PaymentIntent, you initiate a payment process that Stripe manages through to completion, whether that results in a successful charge, requires additional customer action, or fails for some reason.

The Payment Intents API is Stripe's recommended approach for most payment integrations. It consolidates the capabilities of several legacy APIs into a single, unified interface that adapts to the payment method being used. This means you can accept credit cards, debit cards, bank transfers, digital wallets, and buy-now-pay-later options without needing to understand the intricacies of each method's specific flow. The API handles 3D Secure authentication, fraud prevention signals, and retry logic automatically, reducing the complexity your code must manage.

Key capabilities:

• Unified API for 135+ payment methods
• Automatic handling of 3D Secure and authentication
• Status-driven lifecycle for predictable behavior
• Future-proof with new payment types as they're added

Before the Payment Intents API, developers had to choose between different Stripe products based on their payment method needs. The legacy Charges API offered simplicity but couldn't handle authentication challenges well. Payment Intents combines the best of both approaches, providing a status-driven model that tells you exactly where you are in the payment process and what you need to do next. This transparency makes it easier to build robust, user-friendly payment experiences that adapt to whatever situation arises during checkout. For teams building custom e-commerce solutions, the Payment Intents API provides the foundation for secure, reliable checkout flows that handle the complexity of modern payments automatically.

Creating a PaymentIntent

Creating a PaymentIntent is straightforward, but the parameters you choose significantly impact how the payment flow behaves. The core required fields are amount and currency, which define what you're charging. The amount must be expressed in the smallest currency unit (cents for USD, for example), so a $10.00 charge would use an amount of 1000. This integer-based approach avoids floating-point precision issues that can cause incorrect charges.

Required Parameters

{
  "amount": 1000,
  "currency": "usd"
}

Amount must be in the smallest currency unit (cents for USD). A $10.00 charge uses amount: 1000.

Currency accepts ISO codes like "usd", "eur", or "gbp". When specifying currency, consider whether you need to support currency conversion or if you're charging in a single currency.

Optional Parameters

The automatic_payment_methods parameter, when set to enabled, tells Stripe to dynamically determine which payment methods to show based on your Stripe dashboard settings and the customer's context. This is the recommended approach for most integrations, as it simplifies configuration while remaining flexible.

You can specify a payment_method_types array to restrict which payment methods are available for a particular PaymentIntent. This is useful when certain products or services can only be paid for with specific methods. For example, you might allow credit cards and Apple Pay for digital goods while adding bank transfers for high-value items where customers prefer to pay via ACH.

The confirm parameter determines whether Stripe immediately attempts to charge the payment method when you create the PaymentIntent. Setting this to true is appropriate when you already have the payment method details collected, while leaving it false (the default) lets you create the PaymentIntent first and confirm later after additional validation or customer action.

Server-Side Creation Example

const paymentIntent = await stripe.paymentIntents.create({
  amount: 2000,
  currency: 'usd',
  automatic_payment_methods: { enabled: true },
  description: 'Digital product purchase',
  metadata: {
    order_id: '12345',
    customer_email: '[email protected]'
  }
});

Each payment method type has specific options that control its behavior. For card payments, you can specify whether to require 3D Secure authentication, which cards to accept (debit, credit, prepaid), and currency-specific BIN ranges. These configuration options are passed in the payment_method_options object when creating the PaymentIntent.

Sources

1. Stripe: The Payment Intents API - Official documentation covering the core Payment Intents API, lifecycle, and integration patterns
2. Stripe: The PaymentIntent Object - Complete reference for the PaymentIntent object structure and properties
3. Stripe: Payment Intents API Reference - Primary API reference for all Payment Intents operations
4. Stripe: Payment Element Migration Guide - Best practices for migrating to Payment Element with Payment Intents