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 Accounts Account Checkout API
description: This is an object representing a Stripe account. You can retrieve it to see properties on the account like its current requirements or if the account is enabled to make live charges or receive payouts.
contact:
email: dev-platform@stripe.com
name: Stripe Dev Platform Team
url: https://stripe.com
termsOfService: https://stripe.com/us/terms/
version: '2023-10-16'
x-stripeSpecFilename: spec3
servers:
- url: https://api.stripe.com/
security:
- basicAuth: []
- bearerAuth: []
tags:
- name: Checkout
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.
tags:
- Checkout
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.
tags:
- Checkout
/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.
tags:
- Checkout
/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.
tags:
- Checkout
/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.
tags:
- Checkout
components:
schemas:
GetCheckoutSessionsRequest:
type: object
properties: {}
error:
description: An error response from the Stripe API
properties:
error:
$ref: '#/components/schemas/api_errors'
required:
- error
type: object
GetCheckoutSessionsSessionLineItemsRequest:
type: object
properties: {}
PostCheckoutSessionsSessionExpireRequest:
type: object
properties:
expand:
description: Specifies which fields in the response should be expanded.
items:
maxLength: 5000
type: string
type: array
PostCheckoutSessionsRequest:
type: object
properties:
after_expiration:
description: Configure actions after a Checkout Session has expired.
properties:
recovery:
properties:
allow_promotion_codes:
type: boolean
enabled:
type: boolean
required:
- enabled
title: recovery_params
type: object
title: after_expiration_params
type: object
allow_promotion_codes:
description: Enables user redeemable promotion codes.
type: boolean
automatic_tax:
description: Settings for automatic tax lookup for this session and resulting payments, invoices, and subscriptions.
properties:
enabled:
type: boolean
required:
- enabled
title: automatic_tax_params
type: object
billing_address_collection:
description: Specify whether Checkout should collect the customer's billing address.
enum:
- auto
- required
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
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: 200
type: string
consent_collection:
description: Configure fields for the Checkout Session to gather active consent from customers.
properties:
payment_method_reuse_agreement:
properties:
position:
enum:
- auto
- hidden
type: string
required:
- position
title: payment_method_reuse_agreement_params
type: object
promotions:
enum:
- auto
- none
type: string
terms_of_service:
enum:
- none
- required
type: string
title: consent_collection_params
type: object
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). Required in `setup` mode when `payment_method_types` is not set.
type: string
custom_fields:
description: Collect additional information from your customer using custom fields. Up to 2 fields are supported.
items:
properties:
dropdown:
properties:
options:
items:
properties:
label:
maxLength: 100
type: string
value:
maxLength: 100
type: string
required:
- label
- value
title: custom_field_option_param
type: object
type: array
required:
- options
title: custom_field_dropdown_param
type: object
key:
maxLength: 200
type: string
label:
properties:
custom:
maxLength: 50
type: string
type:
enum:
- custom
type: string
required:
- custom
- type
title: custom_field_label_param
type: object
numeric:
properties:
maximum_length:
type: integer
minimum_length:
type: integer
title: custom_field_numeric_param
type: object
optional:
type: boolean
text:
properties:
maximum_length:
type: integer
minimum_length:
type: integer
title: custom_field_text_param
type: object
type:
enum:
- dropdown
- numeric
- text
type: string
required:
- key
- label
- type
title: custom_field_param
type: object
type: array
custom_text:
description: Display additional text for your customers using custom text.
properties:
after_submit:
anyOf:
- properties:
message:
maxLength: 1200
type: string
required:
- message
title: custom_text_position_param
type: object
- enum:
- ''
type: string
shipping_address:
anyOf:
- properties:
message:
maxLength: 1200
type: string
required:
- message
title: custom_text_position_param
type: object
- enum:
- ''
type: string
submit:
anyOf:
- properties:
message:
maxLength: 1200
type: string
required:
- message
title: custom_text_position_param
type: object
- enum:
- ''
type: string
terms_of_service_acceptance:
anyOf:
- properties:
message:
maxLength: 1200
type: string
required:
- message
title: custom_text_position_param
type: object
- enum:
- ''
type: string
title: custom_text_param
type: object
customer:
description: 'ID of an existing Customer, if one exists. In `payment` mode, the customer’s most recently saved card
payment method will be used to prefill the email, name, card details, and billing address
on the Checkout page. In `subscription` mode, the customer’s [default payment method](https://stripe.com/docs/api/customers/update#update_customer-invoice_settings-default_payment_method)
will be used if it’s a card, otherwise the most recently saved card will be used. A valid billing address, billing name and billing email are required on the payment method for Checkout to prefill the customer''s card details.
If the Customer already has a valid [email](https://stripe.com/docs/api/customers/object#customer_object-email) set, the email will be prefilled and not editable in Checkout.
If the Customer does not have a valid `email`, Checkout will set the email entered during the session on the Customer.
If blank for Checkout Sessions in `subscription` mode or with `customer_creation` set as `always` in `payment` mode, Checkout will create a new Customer object based on information provided during the payment flow.
You can set [`payment_intent_data.setup_future_usage`](https://stripe.com/docs/api/checkout/sessions/create#create_checkout_session-payment_intent_data-setup_future_usage) to have Checkout automatically attach the payment method to the Customer you pass in for future reuse.'
maxLength: 5000
type: string
customer_creation:
description: 'Configure whether a Checkout Session creates a [Customer](https://stripe.com/docs/api/customers) during Session confirmation.
When a Customer is not created, you can still retrieve email, address, and other customer data entered in Checkout
with [customer_details](https://stripe.com/docs/api/checkout/sessions/object#checkout_session_object-customer_details).
Sessions that don''t create Customers instead are grouped by [guest customers](https://stripe.com/docs/payments/checkout/guest-customers)
in the Dashboard. Promotion codes limited to first time customers will return invalid for these Sessions.
Can only be set in `payment` and `setup` mode.'
enum:
- always
- if_required
type: string
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 a session is
complete, use the `customer` field.'
type: string
customer_update:
description: Controls what fields on Customer can be updated by the Checkout Session. Can only be provided when `customer` is provided.
properties:
address:
enum:
- auto
- never
type: string
x-stripeBypassValidation: true
name:
enum:
- auto
- never
type: string
x-stripeBypassValidation: true
shipping:
enum:
- auto
- never
type: string
x-stripeBypassValidation: true
title: customer_update_params
type: object
discounts:
description: The coupon or promotion code to apply to this Session. Currently, only up to one may be specified.
items:
properties:
coupon:
maxLength: 5000
type: string
promotion_code:
maxLength: 5000
type: string
title: discount_params
type: object
type: array
expand:
description: Specifies which fields in the response should be expanded.
items:
maxLength: 5000
type: string
type: array
expires_at:
description: The Epoch time in seconds at which the Checkout Session will expire. It can be anywhere from 30 minutes to 24 hours after Checkout Session creation. By default, this value is 24 hours from creation.
format: unix-time
type: integer
invoice_creation:
description: Generate a post-purchase Invoice for one-time payments.
properties:
enabled:
type: boolean
invoice_data:
properties:
account_tax_ids:
anyOf:
- items:
maxLength: 5000
type: string
type: array
- enum:
- ''
type: string
custom_fields:
anyOf:
- items:
properties:
name:
maxLength: 30
type: string
value:
maxLength: 30
type: string
required:
- name
- value
title: custom_field_params
type: object
type: array
- enum:
- ''
type: string
description:
maxLength: 1500
type: string
footer:
maxLength: 5000
type: string
metadata:
additionalProperties:
type: string
type: object
rendering_options:
anyOf:
- properties:
amount_tax_display:
enum:
- ''
- exclude_tax
- include_inclusive_tax
type: string
title: rendering_options_param
type: object
- enum:
- ''
type: string
title: invoice_data_params
type: object
required:
- enabled
title: invoice_creation_params
type: object
line_items:
description: 'A list of items the customer is purchasing. Use this parameter to pass one-time or recurring [Prices](https://stripe.com/docs/api/prices).
For `payment` mode, there is a maximum of 100 line items, however it is recommended to consolidate line items if there are more than a few dozen.
For `subscription` mode, there is a maximum of 20 line items with recurring Prices and 20 line items with one-time Prices. Line items with one-time Prices will be on the initial invoice only.'
items:
properties:
adjustable_quantity:
properties:
enabled:
type: boolean
maximum:
type: integer
minimum:
type: integer
required:
- enabled
title: adjustable_quantity_params
type: object
dynamic_tax_rates:
items:
maxLength: 5000
type: string
type: array
price:
maxLength: 5000
type: string
price_data:
properties:
currency:
type: string
product:
maxLength: 5000
type: string
product_data:
properties:
description:
maxLength: 40000
type: string
images:
items:
type: string
type: array
metadata:
additionalProperties:
type: string
type: object
name:
maxLength: 5000
type: string
tax_code:
maxLength: 5000
type: string
required:
- name
title: product_data
type: object
recurring:
properties:
interval:
enum:
- day
- month
- week
- year
type: string
interval_count:
type: integer
required:
- interval
title: recurring_adhoc
type: object
tax_behavior:
enum:
- exclusive
- inclusive
- unspecified
type: string
unit_amount:
type: integer
unit_amount_decimal:
format: decimal
type: string
required:
- currency
title: price_data_with_product_data
type: object
quantity:
type: integer
tax_rates:
items:
maxLength: 5000
type: string
type: array
title: line_item_params
type: object
type: array
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
type: string
x-stripeBypassValidation: true
metadata:
additionalProperties:
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. Individual keys can be unset by posting an empty value to them. All keys can be unset by posting an empty value to `metadata`.
type: object
mode:
description: The mode of the Checkout Session. Pass `subscription` if the Checkout Session includes at least one recurring item.
enum:
- payment
- setup
- subscription
type: string
payment_intent_data:
description: A subset of parameters to be passed to PaymentIntent creation for Checkout Sessions in `payment` mode.
properties:
application_fee_amount:
type: integer
capture_method:
enum:
# --- truncated at 32 KB (83 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/stripe/refs/heads/main/openapi/stripe-checkout-api-openapi.yml