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.
openapi: 3.0.0
info:
title: Stripe Payment Intents API
description: >-
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.
contact:
email: [email protected]
name: Stripe Dev Platform Team
url: https://stripe.com
termsOfService: https://stripe.com/us/terms/
version: '2023-10-16'
x-stripeSpecFilename: spec3
security:
- basicAuth: []
- bearerAuth: []
servers:
- url: https://api.stripe.com/
paths:
/v1/payment_intents:
get:
description: <p>Returns a list of PaymentIntents.</p>
operationId: getPaymentIntents
parameters:
- description: >-
A filter on the list, based on the object `created` field. The value
can be a string with an integer Unix timestamp or a dictionary with
a number of different query options.
explode: true
in: query
name: created
required: false
schema:
anyOf:
- properties:
gt:
type: integer
gte:
type: integer
lt:
type: integer
lte:
type: integer
title: range_query_specs
type: object
- type: integer
style: deepObject
- description: >-
Only return PaymentIntents for the customer that this customer ID
specifies.
in: query
name: customer
required: false
schema:
maxLength: 5000
type: string
style: form
- description: >-
A cursor for use in pagination. `ending_before` is an object ID that
defines your place in the list. For instance, if you make a list
request and receive 100 objects, starting with `obj_bar`, your
subsequent call can include `ending_before=obj_bar` in order to
fetch the previous page of the list.
in: query
name: ending_before
required: false
schema:
maxLength: 5000
type: string
style: form
- description: Specifies which fields in the response should be expanded.
explode: true
in: query
name: expand
required: false
schema:
items:
maxLength: 5000
type: string
type: array
style: deepObject
- description: >-
A limit on the number of objects to be returned. Limit can range
between 1 and 100, and the default is 10.
in: query
name: limit
required: false
schema:
type: integer
style: form
- description: >-
A cursor for use in pagination. `starting_after` is an object ID
that defines your place in the list. For instance, if you make a
list request and receive 100 objects, ending with `obj_foo`, your
subsequent call can include `starting_after=obj_foo` in order to
fetch the next page of the list.
in: query
name: starting_after
required: false
schema:
maxLength: 5000
type: string
style: form
requestBody:
content:
application/x-www-form-urlencoded:
encoding: {}
schema:
additionalProperties: false
$ref: '#/components/schemas/GetPaymentIntentsRequest'
required: false
responses:
'200':
content:
application/json:
schema:
description: ''
x-expandableFields:
- data
$ref: '#/components/schemas/PaymentFlowsPaymentIntentList'
description: Successful response.
default:
content:
application/json:
schema:
$ref: '#/components/schemas/error'
description: Error response.
summary: Stripe Get Payment Intents
x-api-evangelist-processing:
GenerateOperationSummariesFromPath: true
PascalCaseOperationSummaries: true
CaselCaseOperationIds: true
ChooseTags: true
tags:
- Get
- Intents
- Payments
post:
description: >-
<p>Creates a PaymentIntent object.</p>
<p>After the PaymentIntent is created, attach a payment method and <a
href="/docs/api/payment_intents/confirm">confirm</a>
to continue the payment. Learn more about <a
href="/docs/payments/payment-intents">the available payment flows
with the Payment Intents API</a>.</p>
<p>When you use <code>confirm=true</code> during creation, it’s
equivalent to creating
and confirming the PaymentIntent in the same call. You can use any
parameters
available in the <a href="/docs/api/payment_intents/confirm">confirm
API</a> when you supply
<code>confirm=true</code>.</p>
operationId: postPaymentIntents
requestBody:
content:
application/x-www-form-urlencoded:
encoding:
automatic_payment_methods:
explode: true
style: deepObject
expand:
explode: true
style: deepObject
mandate_data:
explode: true
style: deepObject
metadata:
explode: true
style: deepObject
off_session:
explode: true
style: deepObject
payment_method_data:
explode: true
style: deepObject
payment_method_options:
explode: true
style: deepObject
payment_method_types:
explode: true
style: deepObject
radar_options:
explode: true
style: deepObject
shipping:
explode: true
style: deepObject
transfer_data:
explode: true
style: deepObject
schema:
additionalProperties: false
$ref: '#/components/schemas/PostPaymentIntentsRequest'
required: true
responses:
'200':
content:
application/json:
schema:
$ref: '#/components/schemas/payment_intent'
description: Successful response.
default:
content:
application/json:
schema:
$ref: '#/components/schemas/error'
description: Error response.
summary: Stripe Post Payment Intents
x-api-evangelist-processing:
GenerateOperationSummariesFromPath: true
PascalCaseOperationSummaries: true
CaselCaseOperationIds: true
ChooseTags: true
tags:
- Intents
- Payments
- Post
/v1/payment_intents/search:
get:
description: >-
<p>Search for PaymentIntents you’ve previously created using Stripe’s <a
href="/docs/search#search-query-language">Search Query Language</a>.
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.</p>
operationId: getPaymentIntentsSearch
parameters:
- description: Specifies which fields in the response should be expanded.
explode: true
in: query
name: expand
required: false
schema:
items:
maxLength: 5000
type: string
type: array
style: deepObject
- description: >-
A limit on the number of objects to be returned. Limit can range
between 1 and 100, and the default is 10.
in: query
name: limit
required: false
schema:
type: integer
style: form
- description: >-
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.
in: query
name: page
required: false
schema:
maxLength: 5000
type: string
style: form
- description: >-
The search query string. See [search query
language](https://stripe.com/docs/search#search-query-language) and
the list of supported [query fields for payment
intents](https://stripe.com/docs/search#query-fields-for-payment-intents).
in: query
name: query
required: true
schema:
maxLength: 5000
type: string
style: form
requestBody:
content:
application/x-www-form-urlencoded:
encoding: {}
schema:
additionalProperties: false
$ref: '#/components/schemas/GetPaymentIntentsSearchRequest'
required: false
responses:
'200':
content:
application/json:
schema:
description: ''
x-expandableFields:
- data
$ref: '#/components/schemas/SearchResult'
description: Successful response.
default:
content:
application/json:
schema:
$ref: '#/components/schemas/error'
description: Error response.
summary: Stripe Get Payment Intents Search
x-api-evangelist-processing:
GenerateOperationSummariesFromPath: true
PascalCaseOperationSummaries: true
CaselCaseOperationIds: true
ChooseTags: true
tags:
- Get
- Intents
- Payments
- Search
/v1/payment_intents/{intent}:
get:
description: >-
<p>Retrieves the details of a PaymentIntent that has previously been
created. </p>
<p>You can retrieve a PaymentIntent client-side using a publishable key
when the <code>client_secret</code> is in the query string. </p>
<p>If you retrieve a PaymentIntent with a publishable key, it only
returns a subset of properties. Refer to the <a
href="#payment_intent_object">payment intent</a> object reference for
more details.</p>
operationId: getPaymentIntentsIntent
parameters:
- description: >-
The client secret of the PaymentIntent. We require it if you use a
publishable key to retrieve the source.
in: query
name: client_secret
required: false
schema:
maxLength: 5000
type: string
style: form
- description: Specifies which fields in the response should be expanded.
explode: true
in: query
name: expand
required: false
schema:
items:
maxLength: 5000
type: string
type: array
style: deepObject
- in: path
name: intent
required: true
schema:
maxLength: 5000
type: string
style: simple
requestBody:
content:
application/x-www-form-urlencoded:
encoding: {}
schema:
additionalProperties: false
$ref: '#/components/schemas/GetPaymentIntentsIntentRequest'
required: false
responses:
'200':
content:
application/json:
schema:
$ref: '#/components/schemas/payment_intent'
description: Successful response.
default:
content:
application/json:
schema:
$ref: '#/components/schemas/error'
description: Error response.
summary: Stripe Get Payment Intents
x-api-evangelist-processing:
GenerateOperationSummariesFromPath: true
PascalCaseOperationSummaries: true
CaselCaseOperationIds: true
ChooseTags: true
tags:
- Get
- Intents
- Payments
post:
description: >-
<p>Updates properties on a PaymentIntent object without confirming.</p>
<p>Depending on which properties you update, you might need to confirm
the
PaymentIntent again. For example, updating the
<code>payment_method</code>
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 <a href="/docs/api/payment_intents/confirm">confirm API</a>
instead.</p>
operationId: postPaymentIntentsIntent
parameters:
- in: path
name: intent
required: true
schema:
maxLength: 5000
type: string
style: simple
requestBody:
content:
application/x-www-form-urlencoded:
encoding:
application_fee_amount:
explode: true
style: deepObject
expand:
explode: true
style: deepObject
metadata:
explode: true
style: deepObject
payment_method_data:
explode: true
style: deepObject
payment_method_options:
explode: true
style: deepObject
payment_method_types:
explode: true
style: deepObject
receipt_email:
explode: true
style: deepObject
shipping:
explode: true
style: deepObject
transfer_data:
explode: true
style: deepObject
schema:
additionalProperties: false
$ref: '#/components/schemas/PostPaymentIntentsIntentRequest'
required: false
responses:
'200':
content:
application/json:
schema:
$ref: '#/components/schemas/payment_intent'
description: Successful response.
default:
content:
application/json:
schema:
$ref: '#/components/schemas/error'
description: Error response.
summary: Stripe Post Payment Intents
x-api-evangelist-processing:
GenerateOperationSummariesFromPath: true
PascalCaseOperationSummaries: true
CaselCaseOperationIds: true
ChooseTags: true
tags:
- Intents
- Payments
- Post
/v1/payment_intents/{intent}/apply_customer_balance:
post:
description: >-
<p>Manually reconcile the remaining amount for a
<code>customer_balance</code> PaymentIntent.</p>
operationId: postPaymentIntentsIntentApplyCustomerBalance
parameters:
- in: path
name: intent
required: true
schema:
maxLength: 5000
type: string
style: simple
requestBody:
content:
application/x-www-form-urlencoded:
encoding:
expand:
explode: true
style: deepObject
schema:
additionalProperties: false
$ref: >-
#/components/schemas/PostPaymentIntentsIntentApplyCustomerBalanceRequest
required: false
responses:
'200':
content:
application/json:
schema:
$ref: '#/components/schemas/payment_intent'
description: Successful response.
default:
content:
application/json:
schema:
$ref: '#/components/schemas/error'
description: Error response.
summary: Stripe Post Payment Intents Apply Customer Balance
x-api-evangelist-processing:
GenerateOperationSummariesFromPath: true
PascalCaseOperationSummaries: true
CaselCaseOperationIds: true
ChooseTags: true
tags:
- Apply
- Balance
- Customer
- Intents
- Payments
- Post
/v1/payment_intents/{intent}/cancel:
post:
description: >-
<p>You can cancel a PaymentIntent object when it’s in one of these
statuses: <code>requires_payment_method</code>,
<code>requires_capture</code>, <code>requires_confirmation</code>,
<code>requires_action</code> or, <a href="/docs/payments/intents">in
rare cases</a>, <code>processing</code>. </p>
<p>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 <code>status</code> of
<code>requires_capture</code>, the remaining
<code>amount_capturable</code> is automatically refunded. </p>
<p>You can’t cancel the PaymentIntent for a Checkout Session. <a
href="/docs/api/checkout/sessions/expire">Expire the Checkout
Session</a> instead.</p>
operationId: postPaymentIntentsIntentCancel
parameters:
- in: path
name: intent
required: true
schema:
maxLength: 5000
type: string
style: simple
requestBody:
content:
application/x-www-form-urlencoded:
encoding:
expand:
explode: true
style: deepObject
schema:
additionalProperties: false
$ref: '#/components/schemas/PostPaymentIntentsIntentCancelRequest'
required: false
responses:
'200':
content:
application/json:
schema:
$ref: '#/components/schemas/payment_intent'
description: Successful response.
default:
content:
application/json:
schema:
$ref: '#/components/schemas/error'
description: Error response.
summary: Stripe Post Payment Intents Cancel
x-api-evangelist-processing:
GenerateOperationSummariesFromPath: true
PascalCaseOperationSummaries: true
CaselCaseOperationIds: true
ChooseTags: true
tags:
- Cancel
- Intents
- Payments
- Post
/v1/payment_intents/{intent}/capture:
post:
description: >-
<p>Capture the funds of an existing uncaptured PaymentIntent when its
status is <code>requires_capture</code>.</p>
<p>Uncaptured PaymentIntents are cancelled a set number of days (7 by
default) after their creation.</p>
<p>Learn more about <a href="/docs/payments/capture-later">separate
authorization and capture</a>.</p>
operationId: postPaymentIntentsIntentCapture
parameters:
- in: path
name: intent
required: true
schema:
maxLength: 5000
type: string
style: simple
requestBody:
content:
application/x-www-form-urlencoded:
encoding:
expand:
explode: true
style: deepObject
metadata:
explode: true
style: deepObject
transfer_data:
explode: true
style: deepObject
schema:
additionalProperties: false
$ref: '#/components/schemas/PostPaymentIntentsIntentCaptureRequest'
required: false
responses:
'200':
content:
application/json:
schema:
$ref: '#/components/schemas/payment_intent'
description: Successful response.
default:
content:
application/json:
schema:
$ref: '#/components/schemas/error'
description: Error response.
summary: Stripe Post Payment Intents Capture
x-api-evangelist-processing:
GenerateOperationSummariesFromPath: true
PascalCaseOperationSummaries: true
CaselCaseOperationIds: true
ChooseTags: true
tags:
- Capture
- Intents
- Payments
- Post
/v1/payment_intents/{intent}/confirm:
post:
description: >-
<p>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 <code>requires_action</code> status
and
suggest additional actions via <code>next_action</code>. If payment
fails,
the PaymentIntent transitions to the
<code>requires_payment_method</code> status or the
<code>canceled</code> status if the confirmation limit is reached. If
payment succeeds, the PaymentIntent will transition to the
<code>succeeded</code>
status (or <code>requires_capture</code>, if <code>capture_method</code>
is set to <code>manual</code>).
If the <code>confirmation_method</code> is <code>automatic</code>,
payment may be attempted
using our <a
href="/docs/stripe-js/reference#stripe-handle-card-payment">client
SDKs</a>
and the PaymentIntent’s <a
href="#payment_intent_object-client_secret">client_secret</a>.
After <code>next_action</code>s are handled by the client, no additional
confirmation is required to complete the payment.
If the <code>confirmation_method</code> is <code>manual</code>, all
payment attempts must be
initiated using a secret key.
If any actions are required for the payment, the PaymentIntent will
return to the <code>requires_confirmation</code> state
after those actions are completed. Your server needs to then
explicitly re-confirm the PaymentIntent to initiate the next payment
attempt. Read the <a
href="/docs/payments/payment-intents/web-manual">expanded
documentation</a>
to learn more about manual confirmation.</p>
operationId: postPaymentIntentsIntentConfirm
parameters:
- in: path
name: intent
required: true
schema:
maxLength: 5000
type: string
style: simple
requestBody:
content:
application/x-www-form-urlencoded:
encoding:
expand:
explode: true
style: deepObject
mandate_data:
explode: true
style: deepObject
off_session:
explode: true
style: deepObject
payment_method_data:
explode: true
style: deepObject
payment_method_options:
explode: true
style: deepObject
payment_method_types:
explode: true
style: deepObject
radar_options:
explode: true
style: deepObject
receipt_email:
explode: true
style: deepObject
shipping:
explode: true
style: deepObject
schema:
additionalProperties: false
$ref: '#/components/schemas/PostPaymentIntentsIntentConfirmRequest'
required: false
responses:
'200':
content:
application/json:
schema:
$ref: '#/components/schemas/payment_intent'
description: Successful response.
default:
content:
application/json:
schema:
$ref: '#/components/schemas/error'
description: Error response.
summary: Stripe Post Payment Intents Confirm
x-api-evangelist-processing:
GenerateOperationSummariesFromPath: true
PascalCaseOperationSummaries: true
CaselCaseOperationIds: true
ChooseTags: true
tags:
- Confirm
- Intents
- Payments
- Post
/v1/payment_intents/{intent}/increment_authorization:
post:
description: >-
<p>Perform an incremental authorization on an eligible
<a href="/docs/api/payment_intents/object">PaymentIntent</a>. To be
eligible, the
PaymentIntent’s status must be <code>requires_capture</code> and
<a
href="/docs/api/charges/object#charge_object-payment_method_details-card_present-incremental_authorization_supported">incremental_authorization_supported</a>
must be <code>true</code>.</p>
<p>Incremental authorizations attempt to increase the authorized amount
on
your customer’s card to the new, higher <code>amount</code> 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.</p>
<p>If the incremental authorization succeeds, the PaymentIntent object
returns with the updated
<a
href="/docs/api/payment_intents/object#payment_intent_object-amount">amount</a>.
If the incremental authorization fails, a
<a href="/docs/error-codes#card-declined">card_declined</a> error
returns, and no other
fields on the PaymentIntent or Charge update. The PaymentIntent
object remains capturable for the previously authorized amount.</p>
<p>Each PaymentIntent can have a maximum of 10 incremental authorization
attempts, including declines.
After it’s captured, a PaymentIntent can no longer be incremented.</p>
<p>Learn more about <a
href="/docs/terminal/features/incremental-authorizations">incremental
authorizations</a>.</p>
operationId: postPaymentIntentsIntentIncrementAuthorization
parameters:
- in: path
name: intent
required: true
schema:
maxLength: 5000
type: string
style: simple
requestBody:
content:
application/x-www-form-urlencoded:
encoding:
expand:
explode: true
style: deepObject
metadata:
explode: true
style: deepObject
transfer_data:
explode: true
style: deepObject
schema:
additionalProperties: false
$ref: >-
#/components/schemas/PostPaymentIntentsIntentIncrementAuthorizationRequest
required: true
responses:
'200':
content:
application/json:
schema:
$ref: '#/components/schemas/payment_intent'
description: Successful response.
default:
content:
application/json:
schema:
$ref: '#/components/schemas/error'
description: Error response.
summary: Stripe Post Payment Intents Increment Authorization
x-api-evangelist-processing:
GenerateOperationSummariesFromPath: true
PascalCaseOperationSummaries: true
CaselCaseOperationIds: true
ChooseTags: true
tags:
- Authorization
- Increment
- Intents
- Payments
- Post
/v1/payment_intents/{intent}/verify_microdeposits:
post:
description: <p>Verifies microdeposits on a PaymentIntent object.</p>
operationId: postPaymentIntentsIntentVerifyMicrodeposits
parameters:
- in: path
name: intent
required: true
schema:
maxLength: 5000
type: string
style: simple
requestBody:
content:
application/x-www-form-urlencoded:
encoding:
amounts:
explode: true
style: deepObject
expand:
explode: true
style: deepObject
schema:
additionalProperties: false
$ref: >-
#/components/schemas/PostPaymentIntentsIntentVerifyMicrodepositsRequest
required: false
responses:
'200':
content:
application/json:
schema:
$ref: '#/components/schemas/payment_intent'
description: Successful response.
default:
content:
application/json:
schema:
$ref: '#/components/schemas/error'
description: Error response.
summary: Stripe Post Payment Intents Verify Microdeposits
x-api-evangelist-processing:
GenerateOperationSummariesFromPath: true
PascalCaseOperationSummaries: true
CaselCaseOperationIds: true
ChooseTags: true
tags:
- Intents
- Microdeposits
- Payments
- Post
- Verify
components:
schemas:
error:
description: An error response from the Stripe API
properties:
error:
$ref: '#/components/schemas/api_errors'
required:
- error
type: object
payment_intent:
description: >-
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](https://stripe.com/docs/payments/intents#intent-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](https://stripe.com/docs/payments/payment-intents)
properties:
amount:
description: >-
Amount intended to be collected by this PaymentIntent. A positive
integer representing how much to charge in the [smallest currency
unit](https://stripe.com/docs/currencies#zero-decimal) (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](https://stripe.com/docs/currencies#minimum-and-maximum-charge-amounts).
The amount value supports up to eight digits (e.g., a value of
99999999 for a USD charge of $999,999.99).
type: integer
amount_capturable:
description: Amount that can be captured from this PaymentIntent.
type: integer
amount_details:
$ref: '#/components/schemas/payment_flows_amount_details'
amount_received:
description: Amount that this PaymentIntent collects.
type: integer
application:
anyOf:
- maxLength: 5000
type: string
- $ref: '#/components/schemas/application'
description: ID of the Connect application that created the PaymentIntent.
nullable: true
x-expansionResources:
oneOf:
# --- truncated at 32 KB (227 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/stripe/refs/heads/main/openapi/stripe-payment-intents-api-openapi.yml