Payment Intents

A PaymentIntent guides you through the process of collecting a payment from your customer. We recommend that you create exactly one PaymentIntent for each order or customer session in your system. You can reference the PaymentIntent later to see the history of payment attempts for a particular session.

A PaymentIntent transitions through multiple statuses throughout its lifetime as it interfaces with Stripe.js to perform authentication flows and ultimately creates at most one successful charge.

Related guide: Payment Intents API

Was this section helpful? Yes No

Create a PaymentIntent

POST / v1 / payment_intents

Update a PaymentIntent

POST / v1 / payment_intents /:id

Retrieve a PaymentIntent

GET / v1 / payment_intents /:id

List all PaymentIntents

GET / v1 / payment_intents

List all PaymentIntent LineItems

GET / v1 / payment_intents /:id / amount_details_line_items

Cancel a PaymentIntent

POST / v1 / payment_intents /:id / cancel

Capture a PaymentIntent

POST / v1 / payment_intents /:id / capture

Confirm a PaymentIntent

POST / v1 / payment_intents /:id / confirm

Increment an authorization

POST / v1 / payment_intents /:id / increment_authorization

Reconcile a customer_balance PaymentIntent

POST / v1 / payment_intents /:id / apply_customer_balance

Search PaymentIntents

GET / v1 / payment_intents / search

Verify microdeposits on a PaymentIntent

POST / v1 / payment_intents /:id / verify_microdeposits

The PaymentIntent object

Attributes

id string retrievable with publishable key Unique identifier for the object.
amount integer retrievable with publishable key Amount intended to be collected by this PaymentIntent. A positive integer representing how much to charge in the smallest currency unit (e.g., 100 cents to charge $1.00 or 100 to charge ¥100, a zero-decimal currency). The minimum amount is $0.50 US or equivalent in charge currency. The amount value supports up to eight digits (e.g., a value of 99999999 for a USD charge of $999,999.99).
automatic _ payment _ methods nullable object retrievable with publishable key Settings to configure compatible payment methods from the Stripe Dashboard
client _ secret nullable string retrievable with publishable key The client secret of this PaymentIntent. Used for client-side retrieval using a publishable key. The client secret can be used to complete a payment from your frontend. It should not be stored, logged, or exposed to anyone other than the customer. Make sure that you have TLS enabled on any page that includes the client secret. Refer to our docs to accept a payment and learn about how client_secret should be handled.
currency enum retrievable with publishable key Three-letter ISO currency code, in lowercase. Must be a supported currency.
customer nullable string Expandable ID of the Customer this PaymentIntent belongs to, if one exists. Payment methods attached to other Customers cannot be used with this PaymentIntent. If setup_future_usage is set and this PaymentIntent’s payment method is not card_present, then the payment method attaches to the Customer after the PaymentIntent has been confirmed and any required actions from the user are complete. If the payment method is card_present and isn’t a digital wallet, then a generated_card payment method representing the card is created and attached to the Customer instead.
customer _ account nullable string ID of the Account representing the customer that this PaymentIntent belongs to, if one exists. Payment methods attached to other Accounts cannot be used with this PaymentIntent. If setup_future_usage is set and this PaymentIntent’s payment method is not card_present, then the payment method attaches to the Account after the PaymentIntent has been confirmed and any required actions from the user are complete. If the payment method is card_present and isn’t a digital wallet, then a generated_card payment method representing the card is created and attached to the Account instead.
description nullable string retrievable with publishable key An arbitrary string attached to the object. Often useful for displaying to users.
last _ payment _ error nullable object retrievable with publishable key The payment error encountered in the previous PaymentIntent confirmation. It will be cleared if the PaymentIntent is later updated for any reason.
latest _ charge nullable string Expandable ID of the latest Charge object created by this PaymentIntent. This property is null until PaymentIntent confirmation is attempted.
metadata map Set of key-value pairs that you can attach to an object. This can be useful for storing additional information about the object in a structured format. Learn more about storing information in metadata.
next _ action nullable object retrievable with publishable key If present, this property tells you what actions you need to take in order for your customer to fulfill a payment using the provided source.
payment _ method nullable string Expandable retrievable with publishable key ID of the payment method used in this PaymentIntent.
receipt _ email nullable string retrievable with publishable key Email address that the receipt for the resulting payment will be sent to. If receipt_email is specified for a payment in live mode, a receipt will be sent regardless of your email settings.
setup _ future _ usage nullable enum retrievable with publishable key Indicates that you intend to make future payments with this PaymentIntent’s payment method. If you provide a Customer with the PaymentIntent, you can use this parameter to attach the payment method to the Customer after the PaymentIntent is confirmed and the customer completes any required actions. If you don’t provide a Customer, you can still attach the payment method to a Customer after the transaction completes. If the payment method is card_present and isn’t a digital wallet, Stripe creates and attaches a generated_card payment method representing the card to the Customer instead. When processing card payments, Stripe uses setup_future_usage to help you comply with regional legislation and network rules, such as SCA. Possible enum values off_session Use off_session if your customer may or may not be present in your checkout flow. on_session Use on_session if you intend to only reuse the payment method when your customer is present in your checkout flow.
shipping nullable object retrievable with publishable key Shipping information for this PaymentIntent.
statement _ descriptor nullable string Text that appears on the customer’s statement as the statement descriptor for a non-card charge. This value overrides the account’s default statement descriptor. For information about requirements, including the 22-character limit, see the Statement Descriptor docs. Setting this value for a card charge returns an error. For card charges, set the statement_descriptor_suffix instead.
statement _ descriptor _ suffix nullable string Provides information about a card charge. Concatenated to the account’s statement descriptor prefix to form the complete statement descriptor that appears on the customer’s statement.
status enum retrievable with publishable key Status of this PaymentIntent, one of requires_payment_method, requires_confirmation, requires_action, processing, requires_capture, canceled, or succeeded. Read more about each PaymentIntent status. Possible enum values canceled The PaymentIntent has been canceled. processing The PaymentIntent is currently being processed. requires_action The PaymentIntent requires additional action from the customer. requires_capture The PaymentIntent has been confirmed and requires capture. requires_confirmation The PaymentIntent requires confirmation. requires_payment_method The PaymentIntent requires a payment method to be attached. succeeded The PaymentIntent has succeeded.

More attributes

object string, value is "payment_intent" retrievable with publishable key
allowed _ payment _ method _ types nullable array of enums
amount _ capturable integer
amount _ details nullable object
amount _ received integer
application nullable string Expandable Connect only
application _ fee _ amount nullable integer Connect only
canceled _ at nullable timestamp retrievable with publishable key
cancellation _ reason nullable enum retrievable with publishable key
capture _ method enum retrievable with publishable key
confirmation _ method enum retrievable with publishable key
created timestamp retrievable with publishable key
excluded _ payment _ method _ types nullable array of enums
hooks nullable object
livemode boolean retrievable with publishable key
managed _ payments nullable object
on _ behalf _ of nullable string Expandable Connect only
payment _ details nullable object
payment _ method _ configuration _ details nullable object
payment _ method _ options nullable object
payment _ method _ types array of strings retrievable with publishable key
presentment _ details nullable object
processing nullable object retrievable with publishable key
review nullable string Expandable
transfer _ data nullable object Connect only
transfer _ group nullable string Connect only

The PaymentIntent object

{ "id": "pi_3MtwBwLkdIwHu7ix28a3tqPa", "object": "payment_intent", "amount": 2000, "amount_capturable": 0, "amount_details": { "tip": {} }, "amount_received": 0, "application": null, "application_fee_amount": null, "automatic_payment_methods": { "enabled": true }, "canceled_at": null, "cancellation_reason": null, "capture_method": "automatic", "client_secret": "pi_3MtwBwLkdIwHu7ix28a3tqPa_secret_YrKJUKribcBjcG8HVhfZluoGH", "confirmation_method": "automatic", "created": 1680800504, "currency": "usd", "customer": null, "description": null, "last_payment_error": null, "latest_charge": null, "livemode": false, "metadata": {}, "next_action": null, "on_behalf_of": null, "payment_method": null, "payment_method_options": { "card": { "installments": null, "mandate_options": null, "network": null, "request_three_d_secure": "automatic" }, "link": { "persistent_token": null } }, "payment_method_types": [ "card", "link" ], "processing": null, "receipt_email": null, "review": null, "setup_future_usage": null, "shipping": null, "source": null, "statement_descriptor": null, "statement_descriptor_suffix": null, "status": "requires_payment_method", "transfer_data": null, "transfer_group": null}

Create a PaymentIntent

POST / v1 / payment_intents

Creates a PaymentIntent object.

After the PaymentIntent is created, attach a payment method and confirm to continue the payment. Learn more about the available payment flows with the Payment Intents API.

When you use confirm=true during creation, it’s equivalent to creating and confirming the PaymentIntent in the same call. You can use any parameters available in the confirm API when you supply confirm=true.

Parameters

amount integer Required Amount intended to be collected by this PaymentIntent. A positive integer representing how much to charge in the smallest currency unit (e.g., 100 cents to charge $1.00 or 100 to charge ¥100, a zero-decimal currency). The minimum amount is $0.50 US or equivalent in charge currency. The amount value supports up to eight digits (e.g., a value of 99999999 for a USD charge of $999,999.99).
currency enum Required Three-letter ISO currency code, in lowercase. Must be a supported currency.
automatic _ payment _ methods object When you enable this parameter, this PaymentIntent accepts payment methods that you enable in the Dashboard and that are compatible with this PaymentIntent’s other parameters.
confirm boolean Set to true to attempt to confirm this PaymentIntent immediately. This parameter defaults to false. When creating and confirming a PaymentIntent at the same time, you can also provide the parameters available in the Confirm API.
customer string ID of the Customer this PaymentIntent belongs to, if one exists. Payment methods attached to other Customers cannot be used with this PaymentIntent. If setup_future_usage is set and this PaymentIntent’s payment method is not card_present, then the payment method attaches to the Customer after the PaymentIntent has been confirmed and any required actions from the user are complete. If the payment method is card_present and isn’t a digital wallet, then a generated_card payment method representing the card is created and attached to the Customer instead.
customer _ account string ID of the Account representing the customer that this PaymentIntent belongs to, if one exists. Payment methods attached to other Accounts cannot be used with this PaymentIntent. If setup_future_usage is set and this PaymentIntent’s payment method is not card_present, then the payment method attaches to the Account after the PaymentIntent has been confirmed and any required actions from the user are complete. If the payment method is card_present and isn’t a digital wallet, then a generated_card payment method representing the card is created and attached to the Account instead.
description string An arbitrary string attached to the object. Often useful for displaying to users.
metadata map Set of key-value pairs that you can attach to an object. This can be useful for storing additional information about the object in a structured format. Individual keys can be unset by posting an empty value to them. All keys can be unset by posting an empty value to metadata.
off _ session boolean | string only when confirm=true Set to true to indicate that the customer isn’t in your checkout flow during this payment attempt and can’t authenticate. Use this parameter in scenarios where you collect payment method details and charge them later. This parameter can only be used with confirm=true.
payment _ method string ID of the payment method (a PaymentMethod, Card, or compatible Source object) to attach to this PaymentIntent. If you omit this parameter with confirm=true, customer.default_source attaches as this PaymentIntent’s payment instrument to improve migration for users of the Charges API. We recommend that you explicitly provide the payment_method moving forward. If the payment method is attached to a Customer, you must also provide the ID of that Customer as the customer parameter of this PaymentIntent.
receipt _ email string Email address to send the receipt to. If you specify receipt_email for a payment in live mode, you send a receipt regardless of your email settings.
setup _ future _ usage enum Indicates that you intend to make future payments with this PaymentIntent’s payment method. If you provide a Customer with the PaymentIntent, you can use this parameter to attach the payment method to the Customer after the PaymentIntent is confirmed and the customer completes any required actions. If you don’t provide a Customer, you can still attach the payment method to a Customer after the transaction completes. If the payment method is card_present and isn’t a digital wallet, Stripe creates and attaches a generated_card payment method representing the card to the Customer instead. When processing card payments, Stripe uses setup_future_usage to help you comply with regional legislation and network rules, such as SCA. Possible enum values off_session Use off_session if your customer may or may not be present in your checkout flow. on_session Use on_session if you intend to only reuse the payment method when your customer is present in your checkout flow.
shipping object Shipping information for this PaymentIntent.
statement _ descriptor string Text that appears on the customer’s statement as the statement descriptor for a non-card charge. This value overrides the account’s default statement descriptor. For information about requirements, including the 22-character limit, see the Statement Descriptor docs. Setting this value for a card charge returns an error. For card charges, set the statement_descriptor_suffix instead.
statement _ descriptor _ suffix string Provides information about a card charge. Concatenated to the account’s statement descriptor prefix to form the complete statement descriptor that appears on the customer’s statement.

More parameters

allowed _ payment _ method _ types array of enums
amount _ details object
application _ fee _ amount integer Connect only
capture _ method enum
confirmation _ method enum
confirmation _ token string only when confirm=true
error _ on _ requires _ action boolean only when confirm=true
excluded _ payment _ method _ types array of enums
hooks object
mandate string only when confirm=true
mandate _ data object only when confirm=true
on _ behalf _ of string Connect only
payment _ details object
payment _ method _ configuration string
payment _ method _ data object
payment _ method _ options object
radar _ options object
return _ url string only when confirm=true
transfer _ data object Connect only
transfer _ group string Connect only
use _ stripe _ sdk boolean

Returns

Returns a PaymentIntent object.

Response

{ "id": "pi_3MtwBwLkdIwHu7ix28a3tqPa", "object": "payment_intent", "amount": 2000, "amount_capturable": 0, "amount_details": { "tip": {} }, "amount_received": 0, "application": null, "application_fee_amount": null, "automatic_payment_methods": { "enabled": true }, "canceled_at": null, "cancellation_reason": null, "capture_method": "automatic", "client_secret": "pi_3MtwBwLkdIwHu7ix28a3tqPa_secret_YrKJUKribcBjcG8HVhfZluoGH", "confirmation_method": "automatic", "created": 1680800504, "currency": "usd", "customer": null, "description": null, "last_payment_error": null, "latest_charge": null, "livemode": false, "metadata": {}, "next_action": null, "on_behalf_of": null, "payment_method": null, "payment_method_options": { "card": { "installments": null, "mandate_options": null, "network": null, "request_three_d_secure": "automatic" }, "link": { "persistent_token": null } }, "payment_method_types": [ "card", "link" ], "processing": null, "receipt_email": null, "review": null, "setup_future_usage": null, "shipping": null, "source": null, "statement_descriptor": null, "statement_descriptor_suffix": null, "status": "requires_payment_method", "transfer_data": null, "transfer_group": null}