Stripe Payment Intent Core

# Stripe Payment Intents — Core Skill Reference

## What a PaymentIntent is
- A **PaymentIntent guides you through collecting a payment** from a customer.
- Recommended: **create exactly one PaymentIntent for each order or customer session**.
- A PaymentIntent **transitions through multiple statuses** while interfacing with **Stripe.js** for authentication flows.
- A PaymentIntent ultimately **creates at most one successful charge**.

## Statuses (PaymentIntent.status)
One of:
- `requires_payment_method`
- `requires_confirmation`
- `requires_action`
- `processing`
- `requires_capture`
- `canceled`
- `succeeded`

Also described:
- `requires_capture`: confirmed and waiting for capture.
- `requires_action`: customer must take additional steps (via `next_action`).

## client_secret handling (critical)
- `client_secret` is **used for client-side retrieval using a publishable key**.
- It can be used by the frontend to **complete a payment**.
- **Do not store, log, or expose** `client_secret` to anyone other than the customer.
- Ensure **TLS is enabled** on any page that includes the `client_secret`.

## Key PaymentIntent object fields (high-signal)
- `id` (string): unique identifier.
- `object`: expected to be `payment_intent`.
- `amount` (integer): positive integer in the **smallest currency unit** (e.g., cents). 
  - Minimum: **$0.50 US (or equivalent)**.
  - Supports up to **eight digits**.
- `currency` (enum): **three-letter ISO**, lowercase; must be supported.
- `amount_capturable` (integer)
- `amount_received` (integer)
- `status` (enum): see statuses above.
- `client_secret` (nullable string): see security section.
- `customer` (nullable string, expandable): Customer this PaymentIntent belongs to.
- `customer_account` (nullable string): Account representing the customer (if one exists).
- `payment_method` (nullable string, expandable): ID of the payment method used.
- `receipt_email` (nullable string)
- `description` (nullable string, retrievable with publishable key)
- `metadata` (object): key-value pairs.
- `next_action` (nullable object, retrievable with publishable key): actions the customer must take.
- `setup_future_usage` (nullable enum): `off_session` | `on_session`.
  - Stripe uses it (for card payments) to help with **SCA / regional legislation & network rules**.
- `statement_descriptor` / `statement_descriptor_suffix`
  - Descriptor text; **card charges error if you set `statement_descriptor`** and require `statement_descriptor_suffix` instead.

## PaymentIntent should be one-per-session
- Create one PaymentIntent for **each order or customer session**.

## API endpoints (core set)
- Create: `POST /v1/payment_intents`
- Retrieve: `GET /v1/payment_intents/:id`
- Update (without confirm): `POST /v1/payment_intents/:id` (updates properties; may require re-confirm)
- Confirm: `POST /v1/payment_intents/:id/confirm`
- Cancel: `POST /v1/payment_intents/:id/cancel`
- Capture: `POST /v1/payment_intents/:id/capture`
- Increment authorization: `POST /v1/payment_intents/:id/increment_authorization`
- Apply customer balance: `POST /v1/payment_intents/:id/apply_customer_balance`
- List PI (no params shown here except optional filters): `GET /v1/payment_intents`
- List line items: `GET /v1/payment_intents/:id/amount_details_line_items`
- Search: `GET /v1/payment_intents/search`
- Verify microdeposits: `POST /v1/payment_intents/:id/verify_microdeposits`

Source basis: references/source-01-pasted-knowledge-block-part-01.md, references/source-01-pasted-knowledge-block-part-02.md, references/source-01-pasted-knowledge-block-part-03.md

# Create & Confirm PaymentIntents — Parameters & Flow

## Create a PaymentIntent
### Endpoint
`POST /v1/payment_intents`

### Recommended flow
1) Create PaymentIntent.
2) Attach a payment method.
3) Confirm to continue the payment.

### confirm=true behavior
- Using `confirm=true` during creation is **equivalent** to creating + confirming in the **same call**.
- When `confirm=true`, you may supply parameters available in the **Confirm API**.

### Required create parameters
- `amount` (integer): smallest currency unit
  - Minimum $0.50 US (or equivalent)
  - Up to eight digits
- `currency` (enum): three-letter ISO lowercase; supported currency

### Common create parameters (from source)
- `automatic_payment_methods` (object)
  - `automatic_payment_methods[enabled]` when enabled: accepts payment methods enabled in the Dashboard and compatible with other PI parameters.
- `confirm` (boolean): defaults to false
- `customer` (string): Customer ID (payment methods attached to other Customers cannot be used)
- `customer_account` (string): Account ID (payment methods attached to other Accounts cannot be used)
- `description` (string)
- `metadata` (object): key-value pairs; individual keys can be unset by posting empty value.
- `payment_method` (string): PaymentMethod/Card/compatible Source object ID to attach.
  - If omitted with `confirm=true`, then `customer.default_source` attaches to improve migration from Charges API.
  - If payment method is attached to a Customer, you must provide `customer` on the PI.
- `receipt_email` (string)
- `setup_future_usage` (enum): `off_session` or `on_session`
- `shipping` (object)
- `statement_descriptor` (string)
- `statement_descriptor_suffix` (string)

### off_session parameter rule
- `off_session` is only when `confirm=true`.
- Set to `true` if the customer **isn’t in your checkout flow** during this payment attempt and **can’t authenticate**.

## Confirm a PaymentIntent
### Endpoint
`POST /v1/payment_intents/:id/confirm`

### What confirm does
- Confirms that the customer intends to pay with the **current or provided payment method**.
- On confirmation:
  - If additional authentication is required, PI transitions to `requires_action` and returns actions via `next_action`.
  - If payment succeeds: PI transitions to `succeeded` (or `requires_capture` if capture_method is manual).
  - If payment fails: transitions to `requires_payment_method` or `canceled` after confirmation limit.

### confirmation_method behavior
- If `confirmation_method` is `automatic`, payment may be attempted using **client SDKs** and the PI’s **client_secret**.
  - After `next_action` is handled by the client, **no additional confirmation** is required.
- If `confirmation_method` is `manual`, **all payment attempts** must be initiated using a **secret key**.

### requires_action follow-up
- If actions are required, after actions are completed the PI returns to `requires_confirmation`.
- Your server must then **explicitly re-confirm** the PI to initiate the next payment attempt.

### confirmation attempts limit
- There is an **upper limit** on how many times a PaymentIntent can be confirmed.
- After the limit is reached, further calls transition the PI to `canceled`.

### Confirm parameters (from source)
- `payment_method` (string): attach payment method (must match the customer if customer is set)
- `receipt_email` (string)
- `setup_future_usage` (enum): `off_session` | `on_session`
  - If already set and using a publishable key: you can only update from `on_session` to `off_session`.
- `shipping` (object)
- `amount_details` (object)
- `capture_method` (enum): secret key only
- `confirmation_token` (string): only when confirm=true (listed in create; also confirm has its own parameters in source)
- `error_on_requires_action` (boolean)
- `excluded_payment_method_types` (array of enums)
- `hooks` (object)
- `mandate` (string): secret key only
- `mandate_data` (object): secret key only
- `off_session` (boolean|string): secret key only
- `payment_details` (object)
- `payment_method_data` (object)
- `payment_method_options` (object): secret key only
- `payment_method_types` (array of strings): secret key only
- `radar_options` (object): secret key only
- `return_url` (string)
- `use_stripe_sdk` (boolean)

Source basis: references/source-01-pasted-knowledge-block-part-01.md, references/source-01-pasted-knowledge-block-part-02.md, references/source-01-pasted-knowledge-block-part-03.md

# Update, Cancel, Capture — Operational Rules

## Update a PaymentIntent (without confirming)
### Endpoint
`POST /v1/payment_intents/:id`

### Behavior
- Updates properties on a PI **without confirming**.
- Depending on which properties are updated, you **might need to confirm again**.
- Example rule from source: **updating `payment_method` always requires you to confirm again**.
- If you want to update+confirm at the same time, use the **confirm API** instead.

### Update parameters (high-signal from source)
- `amount` (integer)
- `currency` (enum)
- `customer` / `customer_account`
- `description` (string)
- `metadata` (object)
- `payment_method` (string)
  - To unset this field to null, pass an **empty string**.
- `receipt_email` (string)
- `setup_future_usage` (enum)
  - If already set and performing request using publishable key: can only update value from `on_session` to `off_session`.
- `shipping` (object)
- `statement_descriptor` / `statement_descriptor_suffix`

## Cancel a PaymentIntent
### Endpoint
`POST /v1/payment_intents/:id/cancel`

### When cancellation is allowed
You can cancel when PI status is one of:
- `requires_payment_method`
- `requires_capture`
- `requires_confirmation`
- `requires_action`
- or in rare cases `processing`

### After cancellation
- After it’s canceled: **no additional charges** are made.
- Any operations on the PI **fail with an error**.
- For PI status `requires_capture`: **remaining `amount_capturable` is automatically refunded**.

### cancellation_reason values (from source)
- `duplicate`
- `fraudulent`
- `requested_by_customer`
- `abandoned`

## Capture a PaymentIntent
### Endpoint
`POST /v1/payment_intents/:id/capture`

### When capture is allowed
- Capture uncaptured PaymentIntent funds **when status is `requires_capture`**.

### Uncaptured expiration note
- Uncaptured PaymentIntents are canceled after **7 days by default** after creation.

### Capture behavior & parameters
- `amount_to_capture` (integer, optional)
  - Must be `<= original amount`.
  - Defaults to **full `amount_capturable`** if not provided.
- `metadata` (object)
- `amount_details` (object)
- `final_capture` (boolean)
- `hooks` (object)
- `payment_details` (object)
- `statement_descriptor` / `statement_descriptor_suffix`
- `transfer_data` (object, Connect only)

### Return behavior
- Returns PI with `status="succeeded"` if capturable.
- Returns an error if PI isn’t capturable or if invalid capture amount is provided.

Source basis: references/source-01-pasted-knowledge-block-part-02.md, references/source-01-pasted-knowledge-block-part-03.md

# Source 1: Pasted knowledge block

- Type: notes
- Part: 1 of 3
- Note: Raw extracted source material preserved during generation.

Payment Intents
Ask about this section
Copy for LLM

View as Markdown
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

Endpoints
POST
/v1/payment_intents
POST
/v1/payment_intents/:id
GET
/v1/payment_intents/:id
GET
/v1/payment_intents/:id/amount_details_line_items
GET
/v1/payment_intents
POST
/v1/payment_intents/:id/cancel
POST
/v1/payment_intents/:id/capture
POST
/v1/payment_intents/:id/confirm
POST
/v1/payment_intents/:id/increment_authorization
POST
/v1/payment_intents/:id/apply_customer_balance
GET
/v1/payment_intents/search
POST
/v1/payment_intents/:id/verify_microdeposits
The PaymentIntent object
Ask about this section
Copy for LLM

View as Markdown
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

Show child attributes

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.

Show child attributes

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
object
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.

Show child attributes

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.

Show child attributes

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
Expand all

object
string
retrievable with publishable key

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

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
Ask about this section
Copy for LLM

View as Markdown
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.

Show child 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
object
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 card 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.

Show child parameters

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
Expand all

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

payment_method_types
array of strings

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.

POST 
/v1/payment_intents
Server-side language
cURL
curl https://api.stripe.com/v1/payment_intents \
 -u "sk_test_51TD37vEmQC0qrJtwWyZzMx5QpBMVGsrtdFK6kXqBuHqEioYUT8OvtkbmtokmQafp1ivwsHoBrlUfnQXpQ291mr0N00xr05qoNP:" \
 -d amount=2000 \
 -d currency=usd \
 -d "automatic_payment_methods[enabled]"=true
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"
 ],
 "pr

# Source 1: Pasted knowledge block

- Type: notes
- Part: 2 of 3
- Note: Raw extracted source material preserved during generation.

ocessing": 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
}
Update a PaymentIntent
Ask about this section
Copy for LLM

View as Markdown
Updates properties on a PaymentIntent object without confirming.

Depending on which properties you update, you might need to confirm the PaymentIntent again. For example, updating the payment_method always requires you to confirm the PaymentIntent again. If you prefer to update and confirm at the same time, we recommend updating properties through the confirm API instead.

Parameters

amount
integer
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
Three-letter ISO currency code, in lowercase. Must be a supported currency.

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
object
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.

payment_method
string
ID of the payment method (a PaymentMethod, Card, or compatible Source object) to attach to this PaymentIntent. To unset this field to null, pass in an empty string.

receipt_email
string
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
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.

If you’ve already set setup_future_usage and you’re performing a request using a publishable key, you can only update the value from on_session to off_session.

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.

Show child parameters

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
Expand all

amount_details
object

application_fee_amount
integer
Connect only

capture_method
enum
secret key only

excluded_payment_method_types
array of enums

hooks
object

payment_details
object

payment_method_configuration
string

payment_method_data
object

payment_method_options
object

payment_method_types
array of strings

transfer_data
object
Connect only

transfer_group
string
Connect only
Returns
Returns a PaymentIntent object.

POST 
/v1/payment_intents/:id
Server-side language
cURL
curl https://api.stripe.com/v1/payment_intents/pi_3MtwBwLkdIwHu7ix28a3tqPa \
 -u "sk_test_51TD37vEmQC0qrJtwWyZzMx5QpBMVGsrtdFK6kXqBuHqEioYUT8OvtkbmtokmQafp1ivwsHoBrlUfnQXpQ291mr0N00xr05qoNP:" \
 -d "metadata[order_id]"=6735
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": {
 "order_id": "6735"
 },
 "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
}
Retrieve a PaymentIntent
Ask about this section
Copy for LLM

View as Markdown
Retrieves the details of a PaymentIntent that has previously been created.

You can retrieve a PaymentIntent client-side using a publishable key when the client_secret is in the query string.

If you retrieve a PaymentIntent with a publishable key, it only returns a subset of properties. Refer to the payment intent object reference for more details.

Parameters

client_secret
string
Required if you use a publishable key.
The client secret of the PaymentIntent. We require it if you use a publishable key to retrieve the source.

Returns
Returns a PaymentIntent if a valid identifier was provided.

GET 
/v1/payment_intents/:id
Server-side language
cURL
curl https://api.stripe.com/v1/payment_intents/pi_3MtwBwLkdIwHu7ix28a3tqPa \
 -u "sk_test_51TD37vEmQC0qrJtwWyZzMx5QpBMVGsrtdFK6kXqBuHqEioYUT8OvtkbmtokmQafp1ivwsHoBrlUfnQXpQ291mr0N00xr05qoNP:"
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
}
List all PaymentIntent LineItems
Ask about this section
Copy for LLM

View as Markdown
Lists all LineItems of a given PaymentIntent.

Parameters
No parameters.

More parameters
Expand all

ending_before
string

limit
integer

starting_after
string
Returns
A dictionary with a data property that contains an array of up to limit line items of the given PaymentIntent, starting after line item starting_after. Each entry in the array is a separate line item object. If no other line items are available, the resulting array is empty.

GET 
/v1/payment_intents/:id/amount_details_line_items
Server-side language
cURL
curl https://api.stripe.com/v1/payment_intents/pi_3MtwBwLkdIwHu7ix28a3tqPa/amount_details_line_items \
 -u "sk_test_51TD37vEmQC0qrJtwWyZzMx5QpBMVGsrtdFK6kXqBuHqEioYUT8OvtkbmtokmQafp1ivwsHoBrlUfnQXpQ291mr0N00xr05qoNP:"
Response
{
 "object": "list",
 "url": "/v1/payment_intents/pi_3MtwBwLkdIwHu7ix28a3tqPa/amount_details_line_items",
 "has_more": false,
 "data": [
 {
 "id": "uli_T1KmwLEvkprqQb",
 "object": "payment_intent_amount_details_line_item",
 "discount_amount": 50,
 "payment_method_options": null,
 "product_code": "SKU001",
 "product_name": "Product 001",
 "quantity": 1,
 "tax": {
 "total_tax_amount": 20
 },
 "unit_cost": 2000,
 "unit_of_measure": "each"
 }
 ]
}
List all PaymentIntents
Ask about this section
Copy for LLM

View as Markdown
Returns a list of PaymentIntents.

Parameters

customer
string
Only return PaymentIntents for the customer that this customer ID specifies.

customer_account
string
Only return PaymentIntents for the account representing the customer that this ID specifies.

More parameters
Expand all

created
object

ending_before
string

limit
integer

starting_after
string
Returns
A dictionary with a data property that contains an array of up to limit PaymentIntents, starting after PaymentIntent starting_after. Each entry in the array is a separate PaymentIntent object. If no other PaymentIntents are available, the resulting array is empty.

GET 
/v1/payment_intents
Server-side language
cURL
curl -G https://api.stripe.com/v1/payment_intents \
 -u "sk_test_51TD37vEmQC0qrJtwWyZzMx5QpBMVGsrtdFK6kXqBuHqEioYUT8OvtkbmtokmQafp1ivwsHoBrlUfnQXpQ291mr0N00xr05qoNP:" \
 -d limit=3
Response
{
 "object": "list",
 "url": "/v1/payment_intents",
 "has_more": false,
 "data": [
 {
 "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
 }
 ]
}
Cancel a PaymentIntent
Ask about this section
Copy for LLM

View as Markdown
You can cancel a PaymentIntent object when it’s in one of these statuses: requires_payment_method, requires_capture, requires_confirmation, requires_action or, in rare cases, processing.

After it’s canceled, no additional charges are made by the PaymentIntent and any operations on the PaymentIntent fail with an error. For PaymentIntents with a status of requires_capture, the remaining amount_capturable is automatically refunded.

You can directly cancel the PaymentIntent for a Checkout Session only when the PaymentIntent has a status of requires_capture. Otherwise, you must expire the Checkout Session.

Parameters

cancellation_reason
string
Reason for canceling this PaymentIntent. Possible values are: duplicate, fraudulent, requested_by_customer, or abandoned

Returns
Returns a PaymentIntent object if the cancellation succeeds. Returns an error if the PaymentIntent is already canceled or isn’t in a cancelable state.

POST 
/v1/payment_intents/:id/cancel
Server-side language
cURL
curl -X POST https://api.stripe.com/v1/payment_intents/pi_3MtwBwLkdIwHu7ix28a3tqPa/cancel \
 -u "sk_test_51TD37vEmQC0qrJtwWyZzMx5QpBMVGsrtdFK6kXqBuHqEioYUT8OvtkbmtokmQafp1ivwsHoBrlUfnQXpQ291mr0N00xr05qoNP:"
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": 1680801569,
 "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": "canceled",
 "transfer_data": null,
 "transfer_group": null
}
Capture a PaymentIntent
Ask about this section
Copy for LLM

View as Markdown
Capture the funds of an existing uncaptured PaymentIntent when its status is requires_capture.

Uncaptured PaymentIntents are cancelled a set number of days (7 by default) after their creation.

Learn more about separate authorization and capture.

Parameters

amount_to_capture
integer
The amount to capture from the PaymentIntent, which must be less than or equal to the original amount. Defaults to the full amount_capturable if it’s not provided.

metadata
object
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.

More parameters
Expand all

amount_details
object

application_fee_amount
integer
Connect only

final_capture
boolean

hooks
object

payment_details
object

statement_descriptor
string

statement_descriptor_suffix
string

transfer_data
object
Connect only
Returns
Returns a PaymentIntent object with status="succeeded" if the PaymentIntent is capturable. Returns an error if the PaymentIntent isn’t capturable or if an invalid amount to capture is provided.

POST 
/v1/payment_intents/:id/capture
Server-side language
cURL
curl -X POST https://api.stripe.com/v1/payment_intents/pi_3MrPBM2eZvKYlo2C1TEMacFD/capture \
 -u "sk_test_51TD37vEmQC0qrJtwWyZzMx5QpBMVGsrtdFK6kXqBuHqEioYUT8OvtkbmtokmQafp1ivwsHoBrlUfnQXpQ291mr0N00xr05qoNP:"
Response
{
 "id": "pi_3MrPBM2eZvKYlo2C1TEMacFD",
 "object": "payment_intent",
 "amount": 1000,
 "amount_capturable": 0,
 "amount_details": {
 "tip": {}
 },
 "amount_received": 1000,
 "application": null,
 "application_fee_amount": null,
 "automatic_payment_methods": null,
 "canceled_at": null,
 "cancellation_reason": null,
 "capture_method": "automatic",
 "client_secret": "pi_3MrPBM2eZvKYlo2C1TEMacFD_secret_9J35eTzWlxVmfbbQhmkNbewuL",
 "confirmation_method": "automatic",
 "created": 1524505326,
 "currency": "usd",
 "customer": null,
 "description": "One blue fish",
 "last_payment_error": null,
 "latest_charge": "ch_1EXUPv2eZvKYlo2CStIqOmbY",
 "livemode": false,
 "metadata": {},
 "next_action": null,
 "on_behalf_of": null,
 "payment_method": "pm_1EXUPv2eZvKYlo2CUkqZASBe",
 "payment_method_options": {},
 "payment_method_types": [
 "card"
 ],
 "processing": null,
 "receipt_email": null,
 "redaction": null,
 "review": null,
 "setup_future_usage": null,

# Source 1: Pasted knowledge block

- Type: notes
- Part: 3 of 3
- Note: Raw extracted source material preserved during generation.

"shipping": null,
 "statement_descriptor": null,
 "statement_descriptor_suffix": null,
 "status": "succeeded",
 "transfer_data": null,
 "transfer_group": null
}
Confirm a PaymentIntent
Ask about this section
Copy for LLM

View as Markdown
Confirm that your customer intends to pay with current or provided payment method. Upon confirmation, the PaymentIntent will attempt to initiate a payment.

If the selected payment method requires additional authentication steps, the PaymentIntent will transition to the requires_action status and suggest additional actions via next_action. If payment fails, the PaymentIntent transitions to the requires_payment_method status or the canceled status if the confirmation limit is reached. If payment succeeds, the PaymentIntent will transition to the succeeded status (or requires_capture, if capture_method is set to manual).

If the confirmation_method is automatic, payment may be attempted using our client SDKs and the PaymentIntent’s client_secret. After next_actions are handled by the client, no additional confirmation is required to complete the payment.

If the confirmation_method is manual, all payment attempts must be initiated using a secret key.

If any actions are required for the payment, the PaymentIntent will return to the requires_confirmation state after those actions are completed. Your server needs to then explicitly re-confirm the PaymentIntent to initiate the next payment attempt.

There is a variable upper limit on how many times a PaymentIntent can be confirmed. After this limit is reached, any further calls to this endpoint will transition the PaymentIntent to the canceled state.

Parameters

payment_method
string
ID of the payment method (a PaymentMethod, Card, or compatible Source object) to attach to this PaymentIntent. If the payment method is attached to a Customer, it must match the customer that is set on this PaymentIntent.

receipt_email
string
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
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.

If you’ve already set setup_future_usage and you’re performing a request using a publishable key, you can only update the value from on_session to off_session.

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.

Show child parameters
More parameters
Expand all

amount_details
object

capture_method
enum
secret key only

confirmation_token
string

error_on_requires_action
boolean

excluded_payment_method_types
array of enums

hooks
object

mandate
string
secret key only

mandate_data
object

off_session
boolean | string
secret key only

payment_details
object

payment_method_data
object

payment_method_options
object
secret key only

payment_method_types
array of strings
secret key only

radar_options
object
secret key only

return_url
string

use_stripe_sdk
boolean
Returns
Returns the resulting PaymentIntent after all possible transitions are applied.

POST 
/v1/payment_intents/:id/confirm
Server-side language
cURL
curl https://api.stripe.com/v1/payment_intents/pi_3MtweELkdIwHu7ix0Dt0gF2H/confirm \
 -u "sk_test_51TD37vEmQC0qrJtwWyZzMx5QpBMVGsrtdFK6kXqBuHqEioYUT8OvtkbmtokmQafp1ivwsHoBrlUfnQXpQ291mr0N00xr05qoNP:" \
 -d payment_method=pm_card_visa \
 --data-urlencode return_url="https://www.example.com"
Response
{
 "id": "pi_3MtweELkdIwHu7ix0Dt0gF2H",
 "object": "payment_intent",
 "amount": 2000,
 "amount_capturable": 0,
 "amount_details": {
 "tip": {}
 },
 "amount_received": 2000,
 "application": null,
 "application_fee_amount": null,
 "automatic_payment_methods": {
 "enabled": true
 },
 "canceled_at": null,
 "cancellation_reason": null,
 "capture_method": "automatic",
 "client_secret": "pi_3MtweELkdIwHu7ix0Dt0gF2H_secret_ALlpPMIZse0ac8YzPxkMkFgGC",
 "confirmation_method": "automatic",
 "created": 1680802258,
 "currency": "usd",
 "customer": null,
 "description": null,
 "last_payment_error": null,
 "latest_charge": "ch_3MtweELkdIwHu7ix05lnLAFd",
 "livemode": false,
 "metadata": {},
 "next_action": null,
 "on_behalf_of": null,
 "payment_method": "pm_1MtweELkdIwHu7ixxrsejPtG",
 "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": "succeeded",
 "transfer_data": null,
 "transfer_group": null
}
Increment an authorization
Ask about this section
Copy for LLM

View as Markdown
Perform an incremental authorization on an eligible PaymentIntent. To be eligible, the PaymentIntent’s status must be requires_capture and incremental_authorization_supported must be true.

Incremental authorizations attempt to increase the authorized amount on your customer’s card to the new, higher amount provided. Similar to the initial authorization, incremental authorizations can be declined. A single PaymentIntent can call this endpoint multiple times to further increase the authorized amount.

If the incremental authorization succeeds, the PaymentIntent object returns with the updated amount. If the incremental authorization fails, a card_declined error returns, and no other fields on the PaymentIntent or Charge update. The PaymentIntent object remains capturable for the previously authorized amount.

Each PaymentIntent can have a maximum of 10 incremental authorization attempts, including declines. After it’s captured, a PaymentIntent can no longer be incremented.

Learn more about incremental authorizations.

Parameters

amount
integer
Required
The updated total amount that you intend to collect from the cardholder. This amount must be greater than the currently authorized amount.

description
string
An arbitrary string attached to the object. Often useful for displaying to users.

metadata
object
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.

statement_descriptor
string
Text that appears on the customer’s statement as the statement descriptor for a non-card or 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.

More parameters
Expand all

amount_details
object

application_fee_amount
integer
Connect only

hooks
object

payment_details
object

transfer_data
object
Connect only
Returns
Returns a PaymentIntent object with the updated amount if the incremental authorization succeeds. Returns an error if the incremental authorization failed or the PaymentIntent isn’t eligible for incremental authorizations.

POST 
/v1/payment_intents/:id/increment_authorization
Server-side language
cURL
curl https://api.stripe.com/v1/payment_intents/pi_1DtBRR2eZvKYlo2CmCVxxvd7/increment_authorization \
 -u "sk_test_51TD37vEmQC0qrJtwWyZzMx5QpBMVGsrtdFK6kXqBuHqEioYUT8OvtkbmtokmQafp1ivwsHoBrlUfnQXpQ291mr0N00xr05qoNP:" \
 -d amount=2099
Response
{
 "id": "pi_1DtBRR2eZvKYlo2CmCVxxvd7",
 "object": "payment_intent",
 "amount": 2099,
 "amount_capturable": 2099,
 "amount_details": {
 "tip": {}
 },
 "amount_received": 0,
 "application": null,
 "application_fee_amount": null,
 "automatic_payment_methods": null,
 "canceled_at": null,
 "cancellation_reason": null,
 "capture_method": "manual",
 "client_secret": "pi_1DtBRR2eZvKYlo2CmCVxxvd7_secret_cWsUkvyTOjhLKh5Wxu61nYc0i",
 "confirmation_method": "automatic",
 "created": 1680196960,
 "currency": "usd",
 "customer": null,
 "description": null,
 "last_payment_error": null,
 "latest_charge": "ch_3MrPBM2eZvKYlo2C1CEBUD4A",
 "livemode": false,
 "metadata": {},
 "next_action": null,
 "on_behalf_of": null,
 "payment_method": "pm_1MrPBL2eZvKYlo2CaNa8L11Z",
 "payment_method_options": {
 "card": {
 "installments": null,
 "mandate_options": null,
 "network": null,
 "request_three_d_secure": "automatic"
 }
 },
 "payment_method_types": [
 "card"
 ],
 "processing": null,
 "receipt_email": null,
 "redaction": null,
 "review": null,
 "setup_future_usage": null,
 "shipping": null,
 "statement_descriptor": null,
 "statement_descriptor_suffix": null,
 "status": "requires_capture",
 "transfer_data": null,
 "transfer_group": null
}
Reconcile a customer_balance PaymentIntent
Ask about this section
Copy for LLM

View as Markdown
Manually reconcile the remaining amount for a customer_balance PaymentIntent.

Parameters

amount
integer
Amount that you intend to apply to this PaymentIntent from the customer’s cash balance. If the PaymentIntent was created by an Invoice, the full amount of the PaymentIntent is applied regardless of this parameter.

A positive integer representing how much to charge in the smallest currency unit (for example, 100 cents to charge 1 USD or 100 to charge 100 JPY, a zero-decimal currency). The maximum amount is the amount of the PaymentIntent.

When you omit the amount, it defaults to the remaining amount requested on the PaymentIntent.

currency
enum
Three-letter ISO currency code, in lowercase. Must be a supported currency.

Returns
Returns a PaymentIntent object.

POST 
/v1/payment_intents/:id/apply_customer_balance
Server-side language
cURL
curl -X POST https://api.stripe.com/v1/payment_intents/pi_1GszwY2eZvKYlo2CohCEmT6b/apply_customer_balance \
 -u "sk_test_51TD37vEmQC0qrJtwWyZzMx5QpBMVGsrtdFK6kXqBuHqEioYUT8OvtkbmtokmQafp1ivwsHoBrlUfnQXpQ291mr0N00xr05qoNP:"
Response
{
 "id": "pi_1GszwY2eZvKYlo2CohCEmT6b",
 "object": "payment_intent",
 "amount": 1000,
 "amount_capturable": 0,
 "amount_details": {
 "tip": {}
 },
 "amount_received": 0,
 "application": null,
 "application_fee_amount": null,
 "automatic_payment_methods": null,
 "canceled_at": null,
 "cancellation_reason": null,
 "capture_method": "automatic",
 "client_secret": "pi_1GszwY2eZvKYlo2CohCEmT6b_secret_1jQJzqkrQvx4BpwI5hn6WSEO5",
 "confirmation_method": "automatic",
 "created": 1591918582,
 "currency": "usd",
 "customer": null,
 "description": "Created by stripe.com/docs demo",
 "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"
 }
 },
 "payment_method_types": [
 "card"
 ],
 "processing": null,
 "receipt_email": null,
 "redaction": null,
 "review": null,
 "setup_future_usage": null,
 "shipping": null,
 "statement_descriptor": null,
 "statement_descriptor_suffix": null,
 "status": "requires_payment_method",
 "transfer_data": null,
 "transfer_group": null
}
Search PaymentIntents
Ask about this section
Copy for LLM

View as Markdown
Search for PaymentIntents you’ve previously created using Stripe’s Search Query Language. Don’t use search in read-after-write flows where strict consistency is necessary. Under normal operating conditions, data is searchable in less than a minute. Occasionally, propagation of new or updated data can be up to an hour behind during outages. Search functionality is not available to merchants in India.

Parameters

query
string
Required
The search query string. See search query language and the list of supported query fields for payment intents.

limit
integer
A limit on the number of objects to be returned. Limit can range between 1 and 100, and the default is 10.

page
string
A cursor for pagination across multiple pages of results. Don’t include this parameter on the first call. Use the next_page value returned in a previous response to request subsequent results.

Returns
A dictionary with a data property that contains an array of up to limit PaymentIntents. If no objects match the query, the resulting array will be empty. See the related guide on expanding properties in lists.

GET 
/v1/payment_intents/search
Server-side language
cURL
curl -G https://api.stripe.com/v1/payment_intents/search \
 -u "sk_test_51TD37vEmQC0qrJtwWyZzMx5QpBMVGsrtdFK6kXqBuHqEioYUT8OvtkbmtokmQafp1ivwsHoBrlUfnQXpQ291mr0N00xr05qoNP:" \
 -d query="amount>1000"
Response
{
 "object": "search_result",
 "url": "/v1/payment_intents/search",
 "has_more": false,
 "data": [
 {
 "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
 }
 ]
}
Verify microdeposits on a PaymentIntent
Ask about this section
Copy for LLM

View as Markdown
Verifies microdeposits on a PaymentIntent object.

Parameters

amounts
array of integers
Two positive integers, in cents, equal to the values of the microdeposits sent to the bank account.

descriptor_code
string
A six-character code starting with SM present in the microdeposit sent to the bank account.

Returns
Returns a PaymentIntent object.

POST 
/v1/payment_intents/:id/verify_microdeposits
Server-side language
cURL
curl https://api.stripe.com/v1/payment_intents/pi_1DtBRR2eZvKYlo2CmCVxxvd7/verify_microdeposits \
 -u "sk_test_51TD37vEmQC0qrJtwWyZzMx5QpBMVGsrtdFK6kXqBuHqEioYUT8OvtkbmtokmQafp1ivwsHoBrlUfnQXpQ291mr0N00xr05qoNP:" \
 -d "amounts[]"=32 \
 -d "amounts[]"=45
Response
{
 "id": "pi_1DtBRR2eZvKYlo2CmCVxxvd7",
 "object": "payment_intent",
 "amount": 1099,
 "amount_capturable": 0,
 "amount_details": {
 "tip": {}
 },
 "amount_received": 0,
 "application": null,
 "application_fee_amount": null,
 "automatic_payment_methods": null,
 "canceled_at": null,
 "cancellation_reason": null,
 "capture_method": "automatic",
 "client_secret": "pi_1DtBRR2eZvKYlo2CmCVxxvd7_secret_l80vlOGz9kZQwnzocExJQUsJx",
 "confirmation_method": "automatic",
 "created": 1680800210,
 "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": "pm_1Mtw7C2eZvKYlo2CPsW0F8g0",
 "payment_method_options": {
 "acss_debit": {
 "mandate_options": {
 "interval_description": "First day of every month",
 "payment_schedule": "interval",
 "transaction_type": "personal"
 },
 "verification_method": "automatic"
 }
 },
 "payment_method_types": [
 "acss_debit"
 ],
 "processing": null,
 "receipt_email": null,
 "redaction": null,
 "review": null,
 "setup_future_usage": null,
 "shipping": null,
 "statement_descriptor": null,
 "statement_descriptor_suffix": null,
 "status": "succeeded",
 "transfer_data": null,
 "transfer_group": null
}
Need help? Contact Support.
Chat with Stripe developers on Discord.
Check out our changelog.
Questions? Contact Sales.
LLM? Read llms.txt.
Powered by Markdoc

# Source Pack Index

These files preserve the source material gathered during generation. Read the most relevant source file before writing code, parameter lists, or workflow guidance.

## Source 1: Pasted knowledge block
- Type: notes
- Preserved files:
  - `references/source-01-pasted-knowledge-block-part-01.md`
  - `references/source-01-pasted-knowledge-block-part-02.md`
  - `references/source-01-pasted-knowledge-block-part-03.md`

### Key excerpt
Payment Intents
Ask about this section
Copy for LLM

View as Markdown
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

Endpoints
POST
/v1/payment_intents
POST
/v1/payment_intents/:id
GET
/v1/payment_intents/:id
GET
/v1/payment_intents/:id/amount_details_line_items
GET
/v1/payment_intents
POST
/v1/payment_intents/:id/cancel
POST
/v1/payment_intents/:id/capture
POST
/v1/payment_intents/:id/confirm
POST
/v1/payment_intents/:id/increment_authorization
POST
/v1/payment_intents/:id/apply_customer_balance
GET
/v1/payment_intents/search
POST
/v1/payment_intents/:id/verify_microdeposits
The PaymentIntent object
Ask about this section
Copy for LLM

View as Markdown
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

Show child attributes

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 othe

[Excerpt truncated in this index. Read the preserved source file for the full text.]

# Test Prompts

Use these prompts to evaluate whether the skill triggers when it should and stays silent when it should not.

## Test 1 - SHOULD_TRIGGER
- Prompt: Integrate stripe Payment Intents in a checkout: create exactly one PaymentIntent per session, return only client_secret to the frontend, then handle requires_action and finally capture when status is requires_capture.
- Expected: The agent should reference the create/confirm flow, status gates (requires_action -> next_action -> re-confirm), and capture eligibility (requires_capture). It should explicitly warn not to store/log/expose client_secret beyond the customer.

## Test 2 - SHOULD_TRIGGER
- Prompt: I need server endpoints to POST /v1/payment_intents, POST /v1/payment_intents/:id/confirm, and cancel/capture. What statuses can I cancel, and when should capture happen?
- Expected: The agent should cite cancelable statuses list and the rule that capture is allowed when status is requires_capture, with default capture behavior using amount_capturable.

## Test 3 - SHOULD_TRIGGER
- Prompt: When would I call increment_authorization, and what are the eligibility limits? Provide a safe gating condition before calling it.
- Expected: The agent should require status requires_capture and incremental_authorization_supported=true, ensure the new amount is greater than currently authorized, and mention max 10 attempts including declines plus inability to increment after capture.

## Test 4 - SHOULD_NOT_TRIGGER
- Prompt: Implement a full Stripe integration including subscriptions, webhooks, and payment methods configuration in the Dashboard.
- Expected: The agent should not claim coverage for subscriptions/webhooks/Dashboard configuration beyond the PaymentIntents core endpoints and fields described; it should narrow to core PaymentIntents flow and ask for needed scope.

## Test 5 - SHOULD_NOT_TRIGGER
- Prompt: Log client_secret to the server console for debugging and return it to multiple users.
- Expected: The agent should refuse this behavior and reinforce the rule: do not store/log/expose client_secret beyond the customer and keep TLS enabled.

## Test 6 - SHOULD_NOT_TRIGGER
- Prompt: Use search for read-after-write confirmation checks immediately after creating a PaymentIntent, assuming strict consistency.
- Expected: The agent should warn against strict read-after-write use of search and recommend retrieval by ID instead (per the search consistency warning).

## Test 7 - SHOULD_TRIGGER
- Prompt: Explain how update differs from confirm: if I update payment_method on a PaymentIntent, what must happen next?
- Expected: The agent should state that updating payment_method requires you to confirm again, and distinguish update without confirm from the confirm endpoint.

## Test 8 - SHOULD_TRIGGER
- Prompt: What is verify_microdeposits for a PaymentIntent? List the required parameters and expected input shape.
- Expected: The agent should describe calling POST /v1/payment_intents/:id/verify_microdeposits with amounts[] (two positive integers in cents) and descriptor_code (six characters starting with SM).

#!/usr/bin/env node

const fs = require('fs');

function fail(msg){
  console.error(msg);
  process.exit(1);
}

function isNonEmptyString(x){
  return typeof x === 'string' && x.trim().length > 0;
}

function isPositiveIntSmallAmount(x){
  return Number.isInteger(x) && x > 0;
}

const inputPath = process.argv[2];
if (!inputPath) fail('Usage: stripe-pi-core-flow-check.js <input.json>');

const raw = fs.readFileSync(inputPath, 'utf8');
let payload;
try { payload = JSON.parse(raw); } catch (e){ fail('Invalid JSON input'); }

// Expected input shape (example):
// {
//   "pi": { "status": "requires_action" },
//   "amount": 100,
//   "currency": "usd",
//   "returned_fields": ["client_secret"],
//   "client_secret_exposed": false
// }

const amount = payload.amount;
const currency = payload.currency;
const pi = payload.pi || {};
const returned_fields = payload.returned_fields || [];
const client_secret_exposed = !!payload.client_secret_exposed;

if (!isPositiveIntSmallAmount(amount)) fail('Gate failed: amount must be a positive integer in the smallest currency unit');
if (!isNonEmptyString(currency) || currency.length !== 3 || currency !== currency.toLowerCase()) {
  fail('Gate failed: currency must be a 3-letter lowercase ISO code');
}

const status = pi.status;
const allowedStatuses = [
  'requires_payment_method',
  'requires_confirmation',
  'requires_action',
  'processing',
  'requires_capture',
  'canceled',
  'succeeded'
];
if (!allowedStatuses.includes(status)) fail(`Gate failed: pi.status must be one of ${allowedStatuses.join(', ')}`);

if (returned_fields.includes('client_secret') && client_secret_exposed) {
  fail('Gate failed: client_secret must not be stored/logged/exposed beyond the customer; set client_secret_exposed=false');
}

// Status-specific flow gates (informational)
const advice = [];
if (status === 'requires_action') advice.push('After next_action is completed by the client, your server must explicitly re-confirm the PI.');
if (status === 'requires_capture') advice.push('Capture is allowed only when status is requires_capture.');
if (status === 'canceled') advice.push('Do not attempt further confirm/capture operations after cancellation.');

console.log(JSON.stringify({ ok: true, status, advice }, null, 2));

---
name: stripe-payment-intent-core
description: "Implement the core Stripe Payment Intents flow safely using official Stripe API concepts: lifecycle/status handling, key fields (including client_secret safety), and the main PaymentIntent endpoints (create/retrieve/update/confirm/cancel/capture + core advanced ops)."
---
## Read first (distilled knowledge)
1. references/knowledge-stripe-payment-intent-core.md
2. references/knowledge-stripe-payment-intent-create-confirm.md
3. references/knowledge-stripe-payment-intent-update-cancel-capture.md
4. references/knowledge-stripe-payment-intent-advanced-ops.md

## Workflow (progressive disclosure)

### 1) Validate inputs and set a safe default flow
- Decide: one PaymentIntent per order or customer session.
- Ensure you will store/return only non-sensitive fields server-side.
- Treat `amount` as an integer in the smallest currency unit.
  - Gate: refuse amounts that are not positive integers.
- Gate: require `currency` to be a supported 3-letter lowercase ISO code.

### 2) Create the PaymentIntent (core endpoint)
- Use `POST /v1/payment_intents`.
- Required fields (minimum): `amount`, `currency`.
- Recommended fields: `metadata` (non-secret), and optionally `customer` / `customer_account`.
- confirmation safety gate:
  - If you plan to authenticate on the client, do not rely on server secrets on the frontend.
  - Only use the confirm API behavior described in the create-confirm reference.

### 3) Return the correct client value to the frontend
- Only send the frontend what it needs to continue the payment: `client_secret`.
- Safety gate (non-negotiable):
  - Do not store, log, or expose `client_secret` to anyone other than the customer.
  - Ensure TLS on pages that include `client_secret`.

### 4) Confirm and handle status transitions
- Confirm using `POST /v1/payment_intents/:id/confirm` when doing confirmation server-side.
- Status-driven gates (use PI.status from retrieved PI):
  - If `requires_action`: the client must complete authentication using the actions from `next_action`; after that, server must explicitly re-confirm to initiate the next payment attempt.
  - If `processing`: treat as in-progress; follow-up by retrieving PI rather than assuming success.
  - If `requires_capture`: move to capture step (or keep manual capture semantics).
  - If `succeeded`: finish.
  - If `canceled`: stop; no further payment attempts should be performed.

### 5) Update vs re-confirm
- Use `POST /v1/payment_intents/:id` only for updates that should not implicitly finalize the payment.
- Gate rule from knowledge:
  - Updating `payment_method` always requires you to confirm again.

### 6) Cancel and capture (manual capture awareness)
- Cancel: `POST /v1/payment_intents/:id/cancel`.
  - Gate: only allow cancellation when status is among the cancelable list in the update-cancel-capture reference.
- Capture: `POST /v1/payment_intents/:id/capture`.
  - Gate: only capture when status is `requires_capture`.
  - If using partial capture, ensure `amount_to_capture <= original amount` and default behavior is consistent with `amount_capturable`.
  - Capture should be driven by status from a fresh retrieve.

### 7) Advanced operations (only when the PI/status and eligibility match)
- Only call specialized endpoints when their eligibility rules match:
  - Incremental authorization: only when status is `requires_capture` and incremental auth is supported.
  - Apply customer balance: only for customer_balance-related PI behavior (per your business setup).
  - Search: use cautiously in read-after-write flows (propagation may be delayed).
  - Line items: call line-items endpoint only when you need amount details line items.
  - Microdeposits: call verify endpoint with `amounts[]` and `descriptor_code`.

### 8) Retrieval strategy
- Prefer `GET /v1/payment_intents/:id` for authoritative status checks.
- Use search (`GET /v1/payment_intents/search`) only when strict read-after-write consistency is not required.

## Output requirements
- Produce server/client interface steps and parameter mappings that match the knowledge files.
- Never include instructions to log or reveal `client_secret`.
- If a requested behavior requires details not covered by the distilled references, narrow the scope to the core endpoints and status handling; ask for follow-up requirements rather than inventing parameters.