Checkout is a low-code payment integration that creates a customizable form for collecting payments. You can embed Checkout directly in your website or redirect customers to a Stripe-hosted payment page. It supports one-time payments and subscriptions and accepts over 40 local payment methods.
openapi: 3.0.0
info:
title: Stripe Checkout API
description: >-
Checkout is a low-code payment integration that creates a customizable form
for collecting payments. You can embed Checkout directly in your website or
redirect customers to a Stripe-hosted payment page. It supports one-time
payments and subscriptions and accepts over 40 local payment methods.
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/checkout/sessions:
get:
description: <p>Returns a list of Checkout Sessions.</p>
operationId: getCheckoutSessions
parameters:
- description: >-
Only return the Checkout Sessions that were created during the given
date interval.
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 the Checkout Sessions for the Customer specified.
in: query
name: customer
required: false
schema:
maxLength: 5000
type: string
style: form
- description: >-
Only return the Checkout Sessions for the Customer details
specified.
explode: true
in: query
name: customer_details
required: false
schema:
properties:
email:
type: string
required:
- email
title: customer_details_params
type: object
style: deepObject
- 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: Only return the Checkout Session for the PaymentIntent specified.
in: query
name: payment_intent
required: false
schema:
maxLength: 5000
type: string
style: form
- description: Only return the Checkout Sessions for the Payment Link specified.
in: query
name: payment_link
required: false
schema:
maxLength: 5000
type: string
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
- description: Only return the Checkout Sessions matching the given status.
in: query
name: status
required: false
schema:
enum:
- complete
- expired
- open
type: string
style: form
- description: Only return the Checkout Session for the subscription specified.
in: query
name: subscription
required: false
schema:
maxLength: 5000
type: string
style: form
requestBody:
content:
application/x-www-form-urlencoded:
encoding: {}
schema:
additionalProperties: false
$ref: '#/components/schemas/GetCheckoutSessionsRequest'
required: false
responses:
'200':
content:
application/json:
schema:
description: ''
x-expandableFields:
- data
$ref: '#/components/schemas/PaymentPagesCheckoutSessionList'
description: Successful response.
default:
content:
application/json:
schema:
$ref: '#/components/schemas/error'
description: Error response.
summary: Stripe Get Checkout Sessions
x-api-evangelist-processing:
GenerateOperationSummariesFromPath: true
PascalCaseOperationSummaries: true
CaselCaseOperationIds: true
ChooseTags: true
tags:
- Checkout
- Get
- Sessions
post:
description: <p>Creates a Session object.</p>
operationId: postCheckoutSessions
requestBody:
content:
application/x-www-form-urlencoded:
encoding:
after_expiration:
explode: true
style: deepObject
automatic_tax:
explode: true
style: deepObject
consent_collection:
explode: true
style: deepObject
custom_fields:
explode: true
style: deepObject
custom_text:
explode: true
style: deepObject
customer_update:
explode: true
style: deepObject
discounts:
explode: true
style: deepObject
expand:
explode: true
style: deepObject
invoice_creation:
explode: true
style: deepObject
line_items:
explode: true
style: deepObject
metadata:
explode: true
style: deepObject
payment_intent_data:
explode: true
style: deepObject
payment_method_options:
explode: true
style: deepObject
payment_method_types:
explode: true
style: deepObject
phone_number_collection:
explode: true
style: deepObject
setup_intent_data:
explode: true
style: deepObject
shipping_address_collection:
explode: true
style: deepObject
shipping_options:
explode: true
style: deepObject
subscription_data:
explode: true
style: deepObject
tax_id_collection:
explode: true
style: deepObject
schema:
additionalProperties: false
$ref: '#/components/schemas/PostCheckoutSessionsRequest'
required: false
responses:
'200':
content:
application/json:
schema:
$ref: '#/components/schemas/checkout.session'
description: Successful response.
default:
content:
application/json:
schema:
$ref: '#/components/schemas/error'
description: Error response.
summary: Stripe Post Checkout Sessions
x-api-evangelist-processing:
GenerateOperationSummariesFromPath: true
PascalCaseOperationSummaries: true
CaselCaseOperationIds: true
ChooseTags: true
tags:
- Checkout
- Post
- Sessions
/v1/checkout/sessions/{session}:
get:
description: <p>Retrieves a Session object.</p>
operationId: getCheckoutSessionsSession
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
- in: path
name: session
required: true
schema:
maxLength: 66
type: string
style: simple
requestBody:
content:
application/x-www-form-urlencoded:
encoding: {}
schema:
additionalProperties: false
$ref: '#/components/schemas/GetCheckoutSessionsSessionRequest'
required: false
responses:
'200':
content:
application/json:
schema:
$ref: '#/components/schemas/checkout.session'
description: Successful response.
default:
content:
application/json:
schema:
$ref: '#/components/schemas/error'
description: Error response.
summary: Stripe Get Checkout Sessions Session
x-api-evangelist-processing:
GenerateOperationSummariesFromPath: true
PascalCaseOperationSummaries: true
CaselCaseOperationIds: true
ChooseTags: true
tags:
- Checkout
- Get
- Sessions
/v1/checkout/sessions/{session}/expire:
post:
description: >-
<p>A Session can be expired when it is in one of these statuses:
<code>open</code> </p>
<p>After it expires, a customer can’t complete a Session and customers
loading the Session see a message saying the Session is expired.</p>
operationId: postCheckoutSessionsSessionExpire
parameters:
- in: path
name: session
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/PostCheckoutSessionsSessionExpireRequest'
required: false
responses:
'200':
content:
application/json:
schema:
$ref: '#/components/schemas/checkout.session'
description: Successful response.
default:
content:
application/json:
schema:
$ref: '#/components/schemas/error'
description: Error response.
summary: Stripe Post Checkout Sessions Session Expire
x-api-evangelist-processing:
GenerateOperationSummariesFromPath: true
PascalCaseOperationSummaries: true
CaselCaseOperationIds: true
ChooseTags: true
tags:
- Checkout
- Expire
- Post
- Sessions
/v1/checkout/sessions/{session}/line_items:
get:
description: >-
<p>When retrieving a Checkout Session, there is an includable
<strong>line_items</strong> property containing the first handful of
those items. There is also a URL where you can retrieve the full
(paginated) list of line items.</p>
operationId: getCheckoutSessionsSessionLineItems
parameters:
- 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
- in: path
name: session
required: true
schema:
maxLength: 5000
type: string
style: simple
- 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/GetCheckoutSessionsSessionLineItemsRequest'
required: false
responses:
'200':
content:
application/json:
schema:
description: ''
x-expandableFields:
- data
$ref: '#/components/schemas/PaymentPagesCheckoutSessionListLineItems'
description: Successful response.
default:
content:
application/json:
schema:
$ref: '#/components/schemas/error'
description: Error response.
summary: Stripe Get Checkout Sessions Session Line Items
x-api-evangelist-processing:
GenerateOperationSummariesFromPath: true
PascalCaseOperationSummaries: true
CaselCaseOperationIds: true
ChooseTags: true
tags:
- Checkout
- Get
- Items
- Line
- Sessions
components:
schemas:
error:
description: An error response from the Stripe API
properties:
error:
$ref: '#/components/schemas/api_errors'
required:
- error
type: object
checkout.session:
description: >-
A Checkout Session represents your customer's session as they pay for
one-time purchases or subscriptions through
[Checkout](https://stripe.com/docs/payments/checkout)
or [Payment Links](https://stripe.com/docs/payments/payment-links). We
recommend creating a
new Session each time your customer attempts to pay.
Once payment is successful, the Checkout Session will contain a
reference
to the [Customer](https://stripe.com/docs/api/customers), and either the
successful
[PaymentIntent](https://stripe.com/docs/api/payment_intents) or an
active
[Subscription](https://stripe.com/docs/api/subscriptions).
You can create a Checkout Session on your server and redirect to its URL
to begin Checkout.
Related guide: [Checkout
quickstart](https://stripe.com/docs/checkout/quickstart)
properties:
after_expiration:
anyOf:
- $ref: >-
#/components/schemas/payment_pages_checkout_session_after_expiration
description: >-
When set, provides configuration for actions to take if this
Checkout Session expires.
nullable: true
allow_promotion_codes:
description: Enables user redeemable promotion codes.
nullable: true
type: boolean
amount_subtotal:
description: Total of all items before discounts or taxes are applied.
nullable: true
type: integer
amount_total:
description: Total of all items after discounts and taxes are applied.
nullable: true
type: integer
automatic_tax:
$ref: '#/components/schemas/payment_pages_checkout_session_automatic_tax'
billing_address_collection:
description: >-
Describes whether Checkout should collect the customer's billing
address.
enum:
- auto
- required
nullable: true
type: string
cancel_url:
description: >-
If set, Checkout displays a back button and customers will be
directed to this URL if they decide to cancel payment and return to
your website.
maxLength: 5000
nullable: true
type: string
client_reference_id:
description: |-
A unique string to reference the Checkout Session. This can be a
customer ID, a cart ID, or similar, and can be used to reconcile the
Session with your internal systems.
maxLength: 5000
nullable: true
type: string
client_secret:
description: >-
Client secret to be used when initializing Stripe.js embedded
checkout.
maxLength: 5000
nullable: true
type: string
consent:
anyOf:
- $ref: '#/components/schemas/payment_pages_checkout_session_consent'
description: Results of `consent_collection` for this session.
nullable: true
consent_collection:
anyOf:
- $ref: >-
#/components/schemas/payment_pages_checkout_session_consent_collection
description: >-
When set, provides configuration for the Checkout Session to gather
active consent from customers.
nullable: true
created:
description: >-
Time at which the object was created. Measured in seconds since the
Unix epoch.
format: unix-time
type: integer
currency:
description: >-
Three-letter [ISO currency
code](https://www.iso.org/iso-4217-currency-codes.html), in
lowercase. Must be a [supported
currency](https://stripe.com/docs/currencies).
nullable: true
type: string
currency_conversion:
anyOf:
- $ref: >-
#/components/schemas/payment_pages_checkout_session_currency_conversion
description: >-
Currency conversion details for automatic currency conversion
sessions
nullable: true
custom_fields:
description: >-
Collect additional information from your customer using custom
fields. Up to 2 fields are supported.
items:
$ref: '#/components/schemas/payment_pages_checkout_session_custom_fields'
type: array
custom_text:
$ref: '#/components/schemas/payment_pages_checkout_session_custom_text'
customer:
anyOf:
- maxLength: 5000
type: string
- $ref: '#/components/schemas/customer'
- $ref: '#/components/schemas/deleted_customer'
description: >-
The ID of the customer for this Session.
For Checkout Sessions in `subscription` mode or Checkout Sessions
with `customer_creation` set as `always` in `payment` mode, Checkout
will create a new customer object based on information provided
during the payment flow unless an existing customer was provided
when
the Session was created.
nullable: true
x-expansionResources:
oneOf:
- $ref: '#/components/schemas/customer'
- $ref: '#/components/schemas/deleted_customer'
customer_creation:
description: >-
Configure whether a Checkout Session creates a Customer when the
Checkout Session completes.
enum:
- always
- if_required
nullable: true
type: string
customer_details:
anyOf:
- $ref: >-
#/components/schemas/payment_pages_checkout_session_customer_details
description: >-
The customer details including the customer's tax exempt status and
the customer's tax IDs. Only the customer's email is present on
Sessions in `setup` mode.
nullable: true
customer_email:
description: >-
If provided, this value will be used when the Customer object is
created.
If not provided, customers will be asked to enter their email
address.
Use this parameter to prefill customer data if you already have an
email
on file. To access information about the customer once the payment
flow is
complete, use the `customer` attribute.
maxLength: 5000
nullable: true
type: string
expires_at:
description: The timestamp at which the Checkout Session will expire.
format: unix-time
type: integer
id:
description: Unique identifier for the object.
maxLength: 5000
type: string
invoice:
anyOf:
- maxLength: 5000
type: string
- $ref: '#/components/schemas/invoice'
description: ID of the invoice created by the Checkout Session, if it exists.
nullable: true
x-expansionResources:
oneOf:
- $ref: '#/components/schemas/invoice'
invoice_creation:
anyOf:
- $ref: >-
#/components/schemas/payment_pages_checkout_session_invoice_creation
description: Details on the state of invoice creation for the Checkout Session.
nullable: true
line_items:
description: The line items purchased by the customer.
properties:
data:
description: Details about each object.
items:
$ref: '#/components/schemas/item'
type: array
has_more:
description: >-
True if this list has another page of items after this one that
can be fetched.
type: boolean
object:
description: >-
String representing the object's type. Objects of the same type
share the same value. Always has the value `list`.
enum:
- list
type: string
url:
description: The URL where this list can be accessed.
maxLength: 5000
type: string
required:
- data
- has_more
- object
- url
title: PaymentPagesCheckoutSessionListLineItems
type: object
x-expandableFields:
- data
livemode:
description: >-
Has the value `true` if the object exists in live mode or the value
`false` if the object exists in test mode.
type: boolean
locale:
description: >-
The IETF language tag of the locale Checkout is displayed in. If
blank or `auto`, the browser's locale is used.
enum:
- auto
- bg
- cs
- da
- de
- el
- en
- en-GB
- es
- es-419
- et
- fi
- fil
- fr
- fr-CA
- hr
- hu
- id
- it
- ja
- ko
- lt
- lv
- ms
- mt
- nb
- nl
- pl
- pt
- pt-BR
- ro
- ru
- sk
- sl
- sv
- th
- tr
- vi
- zh
- zh-HK
- zh-TW
nullable: true
type: string
x-stripeBypassValidation: true
metadata:
additionalProperties:
maxLength: 500
type: string
description: >-
Set of [key-value pairs](https://stripe.com/docs/api/metadata) that
you can attach to an object. This can be useful for storing
additional information about the object in a structured format.
nullable: true
type: object
mode:
description: The mode of the Checkout Session.
enum:
- payment
- setup
- subscription
type: string
object:
description: >-
String representing the object's type. Objects of the same type
share the same value.
enum:
- checkout.session
type: string
payment_intent:
anyOf:
- maxLength: 5000
type: string
- $ref: '#/components/schemas/payment_intent'
description: The ID of the PaymentIntent for Checkout Sessions in `payment` mode.
nullable: true
x-expansionResources:
oneOf:
- $ref: '#/components/schemas/payment_intent'
payment_link:
anyOf:
- maxLength: 5000
type: string
- $ref: '#/components/schemas/payment_link'
description: The ID of the Payment Link that created this Session.
nullable: true
x-expansionResources:
oneOf:
- $ref: '#/components/schemas/payment_link'
payment_method_collection:
description: >-
Configure whether a Checkout Session should collect a payment
method.
enum:
- always
- if_required
nullable: true
type: string
payment_method_configuration_details:
anyOf:
- $ref: >-
#/components/schemas/payment_method_config_biz_payment_method_configuration_details
description: >-
Information about the payment method configuration used for this
Checkout session if using dynamic payment methods.
nullable: true
payment_method_options:
anyOf:
- $ref: '#/components/schemas/checkout_session_payment_method_options'
description: >-
Payment-method-specific configuration for the PaymentIntent or
SetupIntent of this CheckoutSession.
nullable: true
payment_method_types:
description: |-
A list of the types of payment methods (e.g. card) this Checkout
Session is allowed to accept.
items:
maxLength: 5000
type: string
type: array
payment_status:
description: >-
The payment status of the Checkout Session, one of `paid`, `unpaid`,
or `no_payment_required`.
You can use this value to decide when to fulfill your customer's
order.
enum:
- no_payment_required
- paid
- unpaid
type: string
phone_number_collection:
$ref: >-
#/components/schemas/payment_pages_checkout_session_phone_number_collection
recovered_from:
description: >-
The ID of the original expired Checkout Session that triggered the
recovery flow.
maxLength: 5000
nullable: true
type: string
redirect_on_completion:
description: >-
Applies to Checkout Sessions with `ui_mode: embedded`. By default,
Stripe will always redirect to your return_url after a successful
confirmation. If you set `redirect_on_completion: 'if_required'`,
then we will only redirect if your user chooses a redirect-based
payment method.
enum:
- always
- if_required
- never
type: string
return_url:
description: >-
Applies to Checkout Sessions with `ui_mode: embedded`. The URL to
redirect your customer back to after they authenticate or cancel
their payment on the payment method's app or site.
maxLength: 5000
type: string
setup_intent:
anyOf:
- maxLength: 5000
type: string
- $ref: '#/components/schemas/setup_intent'
description: The ID of the SetupIntent for Checkout Sessions in `setup` mode.
nullable: true
x-expansionResources:
oneOf:
- $ref: '#/components/schemas/setup_intent'
shipping_address_collection:
anyOf:
- $ref: >-
#/components/schemas/payment_pages_checkout_session_shipping_address_collection
description: >-
When set, provides configuration for Checkout to collect a shipping
address from a customer.
nullable: true
shipping_cost:
anyOf:
- $ref: >-
#/components/schemas/payment_pages_checkout_session_shipping_cost
description: >-
The details of the customer cost of shipping, including the customer
chosen ShippingRate.
nullable: true
shipping_details:
anyOf:
- $ref: '#/components/schemas/shipping'
description: Shipping information for this Checkout Session.
nullable: true
shipping_options:
description: The shipping rate options applied to this Session.
items:
$ref: >-
#/components/schemas/payment_pages_checkout_session_shipping_option
type: array
status:
description: >-
The status of the Checkout Session, one of `open`, `complete`, or
`expired`.
enum:
- complete
- expired
- open
nullable: true
type: string
submit_type:
description: >-
Describes the type of transaction being performed by Checkout in
order to customize
relevant text on the page, such as the submit button. `submit_type`
can only be
specified on Checkout Sessions in `payment` mode, but not Checkout
Sessions
in `subscription` or `setup` mode. Possible values are `auto`,
`pay`, `book`, `donate`. If blank or `auto`, `pay` is used.
enum:
- auto
- book
- donate
- pay
nullable: true
type: string
subscription:
anyOf:
- maxLength: 5000
type: string
- $ref: '#/
# --- truncated at 32 KB (90 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/stripe/refs/heads/main/openapi/stripe-checkout-api-openapi.yml