Setting up
Introduction
Stripe.js reference
This reference documents every object and method available in Stripe’s browser-side JavaScript library, Stripe.js. Use our React Stripe.js reference if you want to add Elements to your React based app.
You can use Stripe.js’ APIs to tokenize customer information, collect sensitive payment details using customizable Stripe Elements, and accept payments with browser payment APIs like Apple Pay and the Payment Request API.
Need to upgrade?
If you are currently using Stripe.js v2 to collect card information, check out our migration guide to learn how to switch.
Not a developer?
Use Stripe’s no-code options or apps from our partners to get started with Stripe and to do more with your Stripe account — no code required.
Setting up
Including Stripe.js
Including Stripe.js
Include the Stripe.js script on each page of your site—it should always be loaded directly from https://js.stripe.com, rather than included in a bundle or hosted yourself.
To best leverage Stripe’s advanced fraud functionality, include this script on every page, not just the checkout page. This allows Stripe to detect suspicious behavior that may be indicative of fraud as customers browse your website.
Using Stripe.js as a module
We also provide an npm package that makes it easier to load and use Stripe.js as a module. For more information, check out the project on GitHub.
Asynchronous and deferred loading of Stripe.js
Asynchronous loading of JavaScript is generally recommended, as it can improve the user experience of your site by not blocking DOM rendering during script loading. The easiest way to asynchronously load Stripe.js is to use the npm module as described above. It does asynchronous loading by default.
You can also load Stripe.js using the async or defer attribute on the script tag. Note, however, that with asynchronous loading any API calls will have to be made only after the script execution has finished.
Versioning
The Stripe.js URL is versioned—we recommend keeping up to date with the latest version. For more information, see the Stripe.js versioning and support policy.
Setting up
Initializing Stripe.js
Stripe(publishableKey,options?)
Use Stripe(publishableKey, options?) to create an instance of the Stripe object. The Stripe object is your entrypoint to the rest of the Stripe.js SDK.
Your Stripe publishable API key is required when calling this function, as it identifies your website to Stripe.
When you’re ready to accept live payments, replace the test key with your live key in production. Learn more about how API keys work in test mode and live mode.
When you use the same publishable API key and options, create and share a single instance of the Stripe object. Creating multiple instances might lead to performance issues.
Method parameters
publishableKey required string
options optional object
Hide options properties
stripeAccount string
For usage with Connect only. Specifying a connected account ID (e.g., acct_24BFMpJ1svR5A89k) allows you to perform actions on behalf of that account.
apiVersion string
locale string
A locale used to globally configure localization in Stripe. Setting the locale here will localize error strings for all Stripe.js methods. It will also configure the locale for Elements. Default is auto (Stripe detects the locale of the browser).
developerTools object
Stripe.js developer tooling options.
Hide developerTools properties
assistant object
Hide assistant properties
enabled boolean
Set to false to disable the sandbox assistant UI. Defaults to true.
The Elements object
Introduction
The Elements object
Stripe Elements are customizable UI components used to collect sensitive information in your payment forms.
Use an Elements instance to create and manage a group of individual Element instances.
The Elements object
Create an Elements object
stripe.elements(options?)
Method parameters
options optional object
A set of options to create this Elements instance with.
Hide options properties
fonts array
An array of custom fonts, which elements created from the Elements object can use. Fonts can be specified as CssFontSource or CustomFontSource objects.
locale string
A locale to display placeholders and error strings in. Default is auto (Stripe detects the locale of the browser).
Setting the locale does not affect the behavior of postal code validation—a valid postal code for the billing country of the card is still required.
To indicate the direction of text for right to left languages such as Arabic and Hebrew, mount Elements underneath an HTML element that includes the dir="rtl" attribute.
clientSecret Conditionally required string
appearance object
loader 'auto' | 'always' | 'never'
currency string
customerSessionClientSecret string
syncAddressCheckbox 'billing' | 'shipping' | 'none'
Used with the Address Element.
The syncAddressCheckbox parameter configures which Address Element to show the checkbox above.
The checkbox allows the customer the option to sync billing and shipping addresses when multiple Address Elements are used, one of each mode, in a single Elements instance.
Default is 'billing'. 'none' opts out of showing the checkbox in either Address Element.
customPaymentMethods array
Hide customPaymentMethods properties
id required string
options object
A set of options to configure the custom payment method with.
Hide options properties
type required 'static'
The form type of the custom payment method.
subtitle string
A subtitle contains additional information about the custom payment method.
externalPaymentMethodTypes (deprecated) string
Create an Elements instance
The Elements object
Create an Elements object without an Intent
stripe.elements(options?)
Method parameters
options optional object
A set of options to create this Elements instance with.
Hide options properties
fonts array
An array of custom fonts, which elements created from the Elements object can use. Fonts can be specified as CssFontSource or CustomFontSource objects.
locale string
A locale to display placeholders and error strings in. Default is auto (Stripe detects the locale of the browser).
Setting the locale does not affect the behavior of postal code validation—a valid postal code for the billing country of the card is still required.
To indicate the direction of text for right to left languages such as Arabic and Hebrew, mount Elements underneath an HTML element that includes the dir="rtl" attribute.
mode Conditionally required 'payment' | 'setup' | 'subscription'
currency Conditionally required string
amount Conditionally required number
Used with the Payment Element and Express Checkout Element. Required when mode is payment or subscription.
Shown in Apple Pay, Google Pay, or Buy now, pay later UIs. The amount intended to be collected from the customer right now. A positive integer representing how much to charge in the smallest currency unit (e.g., 100 cents to charge 1.00 USD or 100 to charge 100 JPY, a zero-decimal currency).
The minimum amount is 0.50 USD or equivalent in charge currency. If mode is subscription, the value supports 0 to account for coupons and free trials, but any amount above 0 is subject to the minimum.
The amount value supports up to eight digits (e.g., a value of 99999999 for a 999,999.99 USD charge).
setupFutureUsage 'on_session' | 'off_session'
captureMethod 'automatic' | 'automatic_async' | 'manual'
onBehalfOf Connect only string
paymentMethodTypes array
paymentMethodConfiguration string
paymentMethodOptions object
Hide paymentMethodOptions properties
card object
If this is a card PaymentMethod, this sub-hash contains details about the card payment method options.
Hide card properties
require_cvc_recollection boolean
When enabled, using a card that is attached to a customer will require the CVC to be provided again. When providing a customerSessionClientSecret and using the Payment Element, the Payment Element will prompt for CVC recollection.
installments object
Installment configuration.
Hide installments properties
enabled boolean
When true, shows the card installment plan selection UI (depending on issuer and country support) if you don't manage your payment methods in the Stripe Dashboard. You must set mode='payment' and explicitly specify paymentMethodTypes in the Elements options. Setting installments to true without these settings returns an error. Incompatible with paymentMethodCreation='manual'.
us_bank_account object
If this is a us_bank_account PaymentMethod, this sub-hash contains details about the US bank account payment method options.
Hide us_bank_account properties
verification_method 'automatic' | 'instant'
Verification method for the US bank account collection flow
financial_connections object
Additional fields for Financial Connections session creation
Hide financial_connections properties
permissions array
The list of permissions to request. If this parameter is passed, the payment_method permission must be included. Valid permissions include: balances, ownership, payment_method, and transactions.
prefetch array
The list of permissions that you would like to retrieve upon creation. Valid permissions include: balances, ownership, and transactions.
appearance object
loader 'auto' | 'always' | 'never'
customerSessionClientSecret string
syncAddressCheckbox 'billing' | 'shipping' | 'none'
Used with the Address Element.
The syncAddressCheckbox parameter configures which Address Element to show the checkbox above.
The checkbox allows the customer the option to sync billing and shipping addresses when multiple Address Elements are used, one of each mode, in a single Elements instance.
Default is 'billing'. 'none' opts out of showing the checkbox in either Address Element.
paymentMethodCreation 'manual'
customPaymentMethods array
Hide customPaymentMethods properties
id required string
options object
A set of options to configure the custom payment method with.
Hide options properties
type required 'static'
The form type of the custom payment method.
subtitle string
A subtitle contains additional information about the custom payment method.
Create an Elements instance without an intent
The Elements object
Update an Elements object
This method updates options on an existing instance of Elements. Note that not all options (e.g. fonts) are updatable.
Method parameters
options required object
A set of options to update this Elements instance with.
Hide options properties
locale string
A locale to display placeholders and error strings in. Default is auto (Stripe detects the locale of the browser).
Setting the locale does not affect the behavior of postal code validation—a valid postal code for the billing country of the card is still required.
To indicate the direction of text for right to left languages such as Arabic and Hebrew, mount Elements underneath an HTML element that includes the dir="rtl" attribute.
mode 'payment' | 'setup' | 'subscription'
Used with the Payment Element.
Filters out payment methods based on intended use.
currency string
amount number
Used with the Payment Element and the Express Checkout Element.
Shown in Apple Pay, Google Pay, or Buy now pay later UIs. The amount intended to be collected from the customer right now. 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).
setupFutureUsage 'on_session' | 'off_session'
captureMethod 'automatic' | 'automatic_async' | 'manual'
onBehalfOf Connect only string
paymentMethodTypes array
paymentMethodOptions object
Hide paymentMethodOptions properties
card object
If this is a card PaymentMethod, this sub-hash contains details about the card payment method options.
Hide card properties
require_cvc_recollection boolean
When enabled, using a card that is attached to a customer will require the CVC to be provided again. When providing a customerSessionClientSecret and using the Payment Element, the Payment Element will prompt for CVC recollection.
installments object
Installment configuration.
Hide installments properties
enabled boolean
When true, shows the card installment plan selection UI (depending on issuer and country support) if you don't manage your payment methods in the Stripe Dashboard. You must set mode='payment' and explicitly specify paymentMethodTypes in the Elements options. Setting installments to true without these settings returns an error. Incompatible with paymentMethodCreation='manual'.
us_bank_account object
If this is a us_bank_account PaymentMethod, this sub-hash contains details about the US bank account payment method options.
Hide us_bank_account properties
verification_method 'automatic' | 'instant'
Verification method for the US bank account collection flow
financial_connections object
Additional fields for Financial Connections session creation
Hide financial_connections properties
permissions array
The list of permissions to request. If this parameter is passed, the payment_method permission must be included. Valid permissions include: balances, ownership, payment_method, and transactions.
prefetch array
The list of permissions that you would like to retrieve upon creation. Valid permissions include: balances, ownership, and transactions.
appearance object
customerSessionClientSecret string
Used with the Payment Element and Address Element.
The client_secret returned from create a CustomerSession associated with the Customer ID. When the customerSessionClientSecret is used with element.update(), saved payment methods associated with the previous session are cleared, and the payment element is re-rendered with any saved payment methods associated with the updated secret.
customPaymentMethods array
Hide customPaymentMethods properties
id required string
options object
A set of options to configure the custom payment method with.
Hide options properties
type required 'static'
The form type of the custom payment method.
subtitle string
A subtitle contains additional information about the custom payment method.
The Elements object
Update-end event
elements.on('update-end',handler)
Triggered when the call to elements.update() is complete.
Method parameters
event required 'update-end'
The name of the event. In this case, update-end.
handler required function
handler() => void is a callback function that you provide that will be called when the event is fired.
Handle an Elements update-end event
The Elements object
Submit an Elements object
Use elements.submit() when creating the Elements object without an Intent.
Before confirming a payment, call elements.submit() to validate the form fields and collect any data required for wallets. You must wait for this function's promise to resolve (using async or .then) before performing any other operations.
This method returns a Promise which resolves with a result object. If this method succeeds, the result object contains the selected payment method type in the selectedPaymentMethod field. If this method fails, the result object contains a localized error message in the error.message field.
The Element
Introduction
The Element
Use Element instances to collect sensitive information in your checkout flow.
The Element
Payment Element
The Payment Element
The Payment Element is an embeddable component for securely collecting payment details. The Payment Element supports dozens of payment methods with a single integration.
The Element
Payment Element
Create a Payment Element
elements.create('payment',options?)
This method creates an instance of the Payment Element.
Method parameters
type required 'payment'
The type of Element being created, which is payment in this case.
options optional object
Options for creating the Payment Element.
Hide options properties
layout 'accordion' | 'tabs' | object
Specify the layout for the Payment Element. If you only pass a layout type ('accordion' or ‘tabs’) without any additional parameters, the Payment Element renders using that layout and the default values associated with it.
An object can also be passed to specify the layout with additional configuration.
Hide layout properties
type required 'accordion' | 'tabs'
Defines the layout to render the Payment Element.
defaultCollapsed boolean
Controls if the Payment Element renders in a collapsed state (where no payment method is selected by default). When you leave this undefined, Stripe renders the experience that it determines will have the best conversion.
radios boolean
Renders each Payment Method with a radio input next to its logo. The radios visually indicate the current selection of the Payment Element.
This property is only applicable to the accordion layout.
spacedAccordionItems boolean
When true, the Payment Methods render as standalone buttons with space in between them.
This property is only applicable to the accordion layout.
visibleAccordionItemsCount number
Sets the max number of Payment Methods visible before using the "More" button to hide additional Payment Methods. Set this value to 0 to disable the "More" button and render all available Payment Methods. Default is 5.
This property is only applicable to the accordion layout.
defaultValues object
Provide initial customer information that will be displayed in the Payment Element. The form will render with empty fields if not provided.
Hide defaultValues properties
billingDetails object
Specify customer's billing details, which lets you pre-fill a customer’s name, email, phone number and address if required by payment method. Pre-filling as much information as possible streamlines the checkout process.
Hide billingDetails properties
name string
email string
phone string
address object
Hide address properties
line1 string
line2 string
city string
The name of a city, town, village, etc.
state string
The most coarse subdivision of a country. Depending on the country, this might correspond to a state, a province, an oblast, a prefecture, or something else along these lines.
country string
Two-letter country code, capitalized. Valid two-letter country codes are specified by ISO3166 alpha-2.
postal_code string
The postal code or ZIP code, also known as PIN code in India.
paymentMethods object
Specify customer's default information for different payment methods. Pre-filling as much information as possible streamlines the checkout process.
Hide paymentMethods properties
ideal object
Hide ideal properties
bank string
A pre-filled iDEAL bank value for the Payment Element. Can only be one of the banks listed in the iDEAL guide (e.g., abn_amro).
payto object
Hide payto properties
usePayId boolean
When true, the PayTo payment method will default to showing the PayID input instead of BSB/account number fields. Customers can still switch between PayID and BSB/account number using the toggle link.
card object
Specify default settings for card payments.
Hide card properties
network array
Specifies a network preference for Card Brand Choice. The first network in the array that matches a network on the entered co-branded card will be selected by default in the Card Brand Choice dropdown. See the supported networks for valid values.
business object
Provide information about your business that will be displayed in the Payment Element. This information will be retrieved from your Stripe account if not provided.
Hide business properties
name string
The name of your business. Your business name will be used to render mandate text for some payment methods.
paymentMethodOrder array
By default, the Payment Element will use a dynamic ordering that optimizes payment method display for each user.
You can override the default order in which payment methods are displayed in the Payment Element with a list of payment method types.
If the associated PaymentIntent has payment method types not specified in paymentMethodOrder, they will be displayed after the payment methods you specify. If you specify payment method types not on the associated PaymentIntent, they will be ignored.
fields object
By default, the Payment Element will collect all necessary details to complete a payment.
For some payment methods, this means that the Payment Element will collect details like name or email that you may have already collected from the user. If this is the case, you can prevent the Payment Element from collecting these data by using the fields option.
If you disable the collection of a certain field with the fields option, you must pass that same data to stripe.confirmPayment or the payment will be rejected.
Learn more about how to customize which billing details to collect and see below for details.
Hide fields properties
billingDetails 'never' | 'auto' | object
Specify never to avoid collecting all billing details in the Payment Element. If you would like to disable only certain billing details, pass an object specifying which fields you would like to disable collection for. The default setting for each field or object is auto.
Hide billingDetails properties
name 'never' | 'auto'
email 'never' | 'auto'
phone 'never' | 'auto'
address 'never' | 'if_required' | 'auto' | object
Specify if_required to collect only billing address fields required to complete the payment. You can omit and hide optional address fields in the card form, such as country and postal code. This differs from the never option, where you don't need to include fields omitted in the Payment Element when confirming the payment. Use if_required to collect only the minimum address information required for the payment method. This can reduce the amount of information required to complete the form.
Disabling address collection can negatively impact authorization rates and network fees for users on a network cost plus pricing plan.
Hide address properties
line1 'never' | 'auto'
line2 'never' | 'auto'
city 'never' | 'auto'
The name of a city, town, village, etc.
state 'never' | 'auto'
The most coarse subdivision of a country. Depending on the country, this might correspond to a state, a province, an oblast, a prefecture, or something else along these lines.
country 'never' | 'auto'
Two-letter country code, capitalized. Valid two-letter country codes are specified by ISO3166 alpha-2.
postalCode 'never' | 'auto'
The postal code or ZIP code, also known as PIN code in India.
readOnly boolean
Applies a read-only state to the Payment Element so that payment details can’t be changed. Default is false.
Enabling the readOnly option doesn't change the Payment Element's visual appearance. If you want to adjust the way the Payment Element looks, use the Appearance API.
terms object
Control how mandates or other legal agreements are displayed in the Payment Element. Use never to never display legal agreements. The default setting is auto, which causes legal agreements to only be shown when necessary.
Hide terms properties
applePay 'auto' | 'always' | 'never'
auBecsDebit 'auto' | 'always' | 'never'
bancontact 'auto' | 'always' | 'never'
card 'auto' | 'always' | 'never'
cashapp 'auto' | 'always' | 'never'
googlePay 'auto' | 'always' | 'never'
ideal 'auto' | 'always' | 'never'
paypal 'auto' | 'always' | 'never'
sepaDebit 'auto' | 'always' | 'never'
sofort 'auto' | 'always' | 'never'
usBankAccount 'auto' | 'always' | 'never'
wallets object
By default, the Payment Element will display all the payment methods that the underlying Payment Intent was created with.
However, wallets like Apple Pay and Google Pay are not payment methods per the Payment Intent API. They will show when the Payment Intent has the card payment method and the customer is using a supported platform and have an active card in their account. This is the auto behavior, and it is the default for choice for all wallets.
If you do not want to show a given wallet as a payment option, you can set its property in wallets to never.
Hide wallets properties
applePay 'auto' | 'never'
googlePay 'auto' | 'never'
link 'auto' | 'never'
applePay object
Specify Apple Pay specific options. These are passed through to the Apple Pay API.
Hide applePay properties
recurringPaymentRequest object
Hide recurringPaymentRequest properties
paymentDescription required string
managementURL required string
regularBilling required object
Hide regularBilling properties
amount required number
label required string
recurringPaymentStartDate Date
recurringPaymentEndDate Date
recurringPaymentIntervalUnit 'year' | 'month' | 'day' | 'hour' | 'minute'
recurringPaymentIntervalCount number
trialBilling object
Hide trialBilling properties
amount required number
label required string
recurringPaymentStartDate Date
recurringPaymentEndDate Date
recurringPaymentIntervalUnit 'year' | 'month' | 'day' | 'hour' | 'minute'
recurringPaymentIntervalCount number
billingAgreement string
deferredPaymentRequest object
Hide deferredPaymentRequest properties
paymentDescription required string
managementURL required string
deferredBilling required object
Hide deferredBilling properties
amount required number
label required string
deferredPaymentDate required Date
billingAgreement string
freeCancellationDate Date
If set, you must also supply a freeCancellationDateTimeZone.,
freeCancellationDateTimeZone string
"If set, you must also supply a freeCancellationDate.,
automaticReloadPaymentRequest object
Hide automaticReloadPaymentRequest properties
paymentDescription required string
managementURL required string
automaticReloadBilling required object
Hide automaticReloadBilling properties
amount required number
label required string
automaticReloadPaymentThresholdAmount required Date
billingAgreement string
Create the Payment Element
with customized fields
Option parameter
fields object
Pass an object to specify payment fields you don't want to collect with the Payment Element.
Hide fields properties
billingDetails 'never' | 'auto' | object
Specify never to avoid collecting all billing details in the Payment Element. If you would like to disable only certain billing details, pass an object specifying which fields you would like to disable collection for. The default setting for each field or object is auto.
Hide billingDetails properties
name 'never' | 'auto'
email 'never' | 'auto'
phone 'never' | 'auto'
address 'never' | 'if_required' | 'auto' | object
Specify if_required to collect only billing address fields required to complete the payment. You can omit and hide optional address fields in the card form, such as country and postal code. This differs from the never option, where you don't need to include fields omitted in the Payment Element when confirming the payment. Use if_required to collect only the minimum address information required for the payment method. This can reduce the amount of information required to complete the form.
Disabling address collection can negatively impact authorization rates and network fees for users on a network cost plus pricing plan.
Hide address properties
line1 'never' | 'auto'
line2 'never' | 'auto'
city 'never' | 'auto'
The name of a city, town, village, etc.
state 'never' | 'auto'
The most coarse subdivision of a country. Depending on the country, this might correspond to a state, a province, an oblast, a prefecture, or something else along these lines.
country 'never' | 'auto'
Two-letter country code, capitalized. Valid two-letter country codes are specified by ISO3166 alpha-2.
postalCode 'never' | 'auto'
The postal code or ZIP code, also known as PIN code in India.
Create a Payment Element with customized fields
The Element
Payment Element
Get a Payment Element
elements.getElement('payment')
This method retrieves a previously created Payment Element.
Method parameters
type required 'payment'
The type of Element being retrieved, which is payment in this case.
elements.getElement('payment') returns one of the following:
- An instance of a Payment Element.
null, when no Payment Element has been created.
The Element
Payment Element
Update a Payment Element
Method parameters
options optional object
Options for updating the Payment Element.
Hide options properties
defaultValues object
Provide initial customer information that will be displayed in the Payment Element. The form will render with empty fields if not provided.
Hide defaultValues properties
billingDetails object
Specify customer's billing details, which lets you pre-fill a customer’s name, email, phone number and address if required by payment method. Pre-filling as much information as possible streamlines the checkout process.
Hide billingDetails properties
name string
email string
phone string
address object
Hide address properties
line1 string
line2 string
city string
The name of a city, town, village, etc.
state string
The most coarse subdivision of a country. Depending on the country, this might correspond to a state, a province, an oblast, a prefecture, or something else along these lines.
country string
Two-letter country code, capitalized. Valid two-letter country codes are specified by ISO3166 alpha-2.
postal_code string
The postal code or ZIP code, also known as PIN code in India.
paymentMethods object
Specify customer's default information for different payment methods. Pre-filling as much information as possible streamlines the checkout process.
Hide paymentMethods properties
ideal object
Hide ideal properties
bank string
A pre-filled iDEAL bank value for the Payment Element. Can only be one of the banks listed in the iDEAL guide (e.g., abn_amro).
payto object
Hide payto properties
usePayId boolean
When true, the PayTo payment method will default to showing the PayID input instead of BSB/account number fields. Customers can still switch between PayID and BSB/account number using the toggle link.
card object
Specify default settings for card payments.
Hide card properties
network array
Specifies a network preference for Card Brand Choice. The first network in the array that matches a network on the entered co-branded card will be selected by default in the Card Brand Choice dropdown. See the supported networks for valid values.
business object
Provide information about your business that will be displayed in the Payment Element. This information will be retrieved from your Stripe account if not provided.
Hide business properties
name string
The name of your business. Your business name will be used to render mandate text for some payment methods.
paymentMethodOrder array
By default, the Payment Element will use a dynamic ordering that optimizes payment method display for each user.
You can override the default order in which payment methods are displayed in the Payment Element with a list of payment method types.
If the associated PaymentIntent has payment method types not specified in paymentMethodOrder, they will be displayed after the payment methods you specify. If you specify payment method types not on the associated PaymentIntent, they will be ignored.
fields object
By default, the Payment Element will collect all necessary details to complete a payment.
For some payment methods, this means that the Payment Element will collect details like name or email that you may have already collected from the user. If this is the case, you can prevent the Payment Element from collecting these data by using the fields option.
If you disable the collection of a certain field with the fields option, you must pass that same data to stripe.confirmPayment or the payment will be rejected.
Learn more about how to customize which billing details to collect and see below for details.
Hide fields properties
billingDetails 'never' | 'auto' | object
Specify never to avoid collecting all billing details in the Payment Element. If you would like to disable only certain billing details, pass an object specifying which fields you would like to disable collection for. The default setting for each field or object is auto.
Hide billingDetails properties
name 'never' | 'auto'
email 'never' | 'auto'
phone 'never' | 'auto'
address 'never' | 'if_required' | 'auto' | object
Specify if_required to collect only billing address fields required to complete the payment. You can omit and hide optional address fields in the card form, such as country and postal code. This differs from the never option, where you don't need to include fields omitted in the Payment Element when confirming the payment. Use if_required to collect only the minimum address information required for the payment method. This can reduce the amount of information required to complete the form.
Disabling address collection can negatively impact authorization rates and network fees for users on a network cost plus pricing plan.
Hide address properties
line1 'never' | 'auto'
line2 'never' | 'auto'
city 'never' | 'auto'
The name of a city, town, village, etc.
state 'never' | 'auto'
The most coarse subdivision of a country. Depending on the country, this might correspond to a state, a province, an oblast, a prefecture, or something else along these lines.
country 'never' | 'auto'
Two-letter country code, capitalized. Valid two-letter country codes are specified by ISO3166 alpha-2.
postalCode 'never' | 'auto'
The postal code or ZIP code, also known as PIN code in India.
readOnly boolean
Applies a read-only state to the Payment Element so that payment details can’t be changed. Default is false.
Enabling the readOnly option doesn't change the Payment Element's visual appearance. If you want to adjust the way the Payment Element looks, use the Appearance API.
terms object
Control how mandates or other legal agreements are displayed in the Payment Element. Use never to never display legal agreements. The default setting is auto, which causes legal agreements to only be shown when necessary.
Hide terms properties
applePay 'auto' | 'always' | 'never'
auBecsDebit 'auto' | 'always' | 'never'
bancontact 'auto' | 'always' | 'never'
card 'auto' | 'always' | 'never'
cashapp 'auto' | 'always' | 'never'
googlePay 'auto' | 'always' | 'never'
ideal 'auto' | 'always' | 'never'
paypal 'auto' | 'always' | 'never'
sepaDebit 'auto' | 'always' | 'never'
sofort 'auto' | 'always' | 'never'
usBankAccount 'auto' | 'always' | 'never'
applePay object
Specify Apple Pay specific options. These are passed through to the Apple Pay API.
Hide applePay properties
recurringPaymentRequest object
Hide recurringPaymentRequest properties
paymentDescription required string
managementURL required string
regularBilling required object
Hide regularBilling properties
amount required number
label required string
recurringPaymentStartDate Date
recurringPaymentEndDate Date
recurringPaymentIntervalUnit 'year' | 'month' | 'day' | 'hour' | 'minute'
recurringPaymentIntervalCount number
trialBilling object
Hide trialBilling properties
amount required number
label required string
recurringPaymentStartDate Date
recurringPaymentEndDate Date
recurringPaymentIntervalUnit 'year' | 'month' | 'day' | 'hour' | 'minute'
recurringPaymentIntervalCount number
billingAgreement string
deferredPaymentRequest object
Hide deferredPaymentRequest properties
paymentDescription required string
managementURL required string
deferredBilling required object
Hide deferredBilling properties
amount required number
label required string
deferredPaymentDate required Date
billingAgreement string
freeCancellationDate Date
If set, you must also supply a freeCancellationDateTimeZone.
freeCancellationDateTimeZone string
If set, you must also supply a freeCancellationDate.
These are tz timezones such as America/Los_Angeles, Europe/Dublin, and Asia/Singapore.
automaticReloadPaymentRequest object
Hide automaticReloadPaymentRequest properties
paymentDescription required string
managementURL required string
automaticReloadBilling required object
Hide automaticReloadBilling properties
amount required number
label required string
automaticReloadPaymentThresholdAmount required number
billingAgreement string
The Element
Payment Element
Fetch Elements Updates
This method returns a Promise which resolves with a result object. If this method succeeds, the result object will be empty. If this method fails, the result object will contain a localized error message in the error.message field. If the associated PaymentIntent or SetupIntent is in an unexpected status, the result object will also contain the intent's status in the error.status field.
The Element
Payment Element
Collapse a Payment Element
This method collapses the Payment Element into a row of payment method tabs.
Collapse a Payment Element
The Element
Express Checkout Element
The Express Checkout Element
The Express Checkout Element is an embeddable component for accepting payments through one-click payment buttons.
The Element
Express Checkout Element
Create an Express Checkout Element
elements.create('expressCheckout',options?)
This method creates an instance of the Express Checkout Element.
Method parameters
type required 'expressCheckout'
The type of Element being created, which is expressCheckout in this case.
options optional object
Options for creating the Express Checkout Element.
Hide options properties
allowedShippingCountries array
By default, the Express Checkout Element allows all countries for shipping.
You can specify which countries are allowed for shipping in the Express Checkout Element with a list of two-letter country codes.
applePay object
Specify Apple Pay specific options. These are passed through to the Apple Pay API.
Hide applePay properties
recurringPaymentRequest object
Hide recurringPaymentRequest properties
paymentDescription required string
managementURL required string
regularBilling required object
Hide regularBilling properties
amount required number
label required string
recurringPaymentStartDate Date
recurringPaymentEndDate Date
recurringPaymentIntervalUnit 'year' | 'month' | 'day' | 'hour' | 'minute'
recurringPaymentIntervalCount number
trialBilling object
Hide trialBilling properties
amount required number
label required string
recurringPaymentStartDate Date
recurringPaymentEndDate Date
recurringPaymentIntervalUnit 'year' | 'month' | 'day' | 'hour' | 'minute'
recurringPaymentIntervalCount number
billingAgreement string
deferredPaymentRequest object
Hide deferredPaymentRequest properties
paymentDescription required string
managementURL required string
deferredBilling required object
Hide deferredBilling properties
amount required number
label required string
deferredPaymentDate required Date
billingAgreement string
freeCancellationDate Date
If set, you must also supply a freeCancellationDateTimeZone.
freeCancellationDateTimeZone string
If set, you must also supply a freeCancellationDate.
These are tz timezones such as America/Los_Angeles, Europe/Dublin, and Asia/Singapore.
automaticReloadPaymentRequest object
Hide automaticReloadPaymentRequest properties
paymentDescription required string
managementURL required string
automaticReloadBilling required object
Hide automaticReloadBilling properties
amount required number
label required string
automaticReloadPaymentThresholdAmount required number
billingAgreement string
billingAddressRequired boolean
By default, the Express Checkout Element collects the billing address. You can disable this by setting billingAddressRequired to false.
We highly recommend that you collect the billing address because it can be used to perform address verifications and block fraudulent payments.
business object
Provide information about your business that's displayed in the Express Checkout Element. This information will be retrieved from your Stripe account if it's not provided.
Hide business properties
name string
The name of your business. Your business name is used to signal to the customer who they're paying.
Klarna always retrieves the business name from your Stripe account, even when this option is set.
buttonHeight number
By default, the height of the buttons are 44px.
You can override this to specify a custom button height in the range of 40px-55px.
buttonTheme object
Specify the preferred button theme to use. By default, Elements determines the themes based on the specified appearance option.
Hide buttonTheme properties
applePay 'black' | 'white' | 'white-outline'
googlePay 'black' | 'white'
paypal 'gold' | 'blue' | 'silver' | 'white' | 'black'
klarna 'dark' | 'light' | 'outlined'
buttonType object
Specify the preferred button type to display.
Hide buttonType properties
applePay 'add-money' | 'book' | 'buy' | 'check-out' | 'contribute' | 'donate' | 'order' | 'plain' | 'reload' | 'rent' | 'subscribe' | 'support' | 'tip' | 'top-up'
googlePay 'book' | 'buy' | 'checkout' | 'donate' | 'order' | 'pay' | 'plain' | 'subscribe'
paypal 'paypal' | 'checkout' | 'buynow' | 'pay'
klarna 'continue' | 'pay'
emailRequired boolean
Collect the customer's email by setting this option to true.
layout object
Specify how the buttons are arranged in a grid-like layout in the Express Checkout Element. Elements determines the layout by using certain factors, such as available space, number of buttons, and the defined layout object.
Hide layout properties
maxColumns number
Defines the maximum number of columns the Express Checkout Element can use to render. Default is 0, meaning unlimited.
maxRows number
Defines the maximum number of rows the Express Checkout Element can use to render. Default is 0, meaning unlimited.
overflow 'auto' | 'never'
Specify whether or not to always hide the overflow menu or allow Elements to determine when to show the overflow menu. Default is auto. You can't specify both overflow: 'never' and set maxRows to a number greater than 0.
lineItems array
An array of LineItem objects. These LineItems are shown as line items in the payment interface, if line items are supported. You can represent discounts as negative amount LineItems.
Hide lineItems properties
name required string
The name of the line item surfaced to the customer in the payment interface.
amount required number
The amount in the currency's subunit (for example, cents, yen, etc.).
paymentMethods object
By default, the Express Checkout Element displays all payment methods possible as a result of your Dashboard configuration. This is the auto behavior.
If you don't want to show a given payment method as a payment option, set its property in paymentMethods to never.
Hide paymentMethods properties
amazonPay 'auto' | 'never'
applePay 'always' | 'auto' | 'never'
Apple Pay has additional configurations that determine when Stripe can show it. By default, Apple Pay shows when the customer is using a supported platform and when we determine it's advantageous for your conversion. This is the auto behavior.
If you want to always show Apple Pay when the customer is using a supported platform, you can set its property in paymentMethods to always. This causes Apple Pay to be shown in supported browsers even when the customer isn't logged in to Apple Pay, resulting in a sign-in flow.
Apple Pay on desktop Chromium browsers is only supported on MacOS when its property in paymentMethods is set to always.
googlePay 'always' | 'auto' | 'never'
Google Pay has additional configurations that determine when Stripe can show it. By default, Google Pay shows when the customer is using a supported platform and when we determine it's advantageous for your conversion. This is the auto behavior.
If you want to always show Google Pay when the customer is using a supported platform, you can set its property in paymentMethods to always. This causes Google Pay to be shown in supported browsers even when the customer isn't logged in to Google Pay, resulting in a sign-in flow.
link 'auto' | 'never'
paypal 'auto' | 'never'
klarna 'auto' | 'never'
paymentMethodOrder array
By default, the Express Checkout Element uses a dynamic ordering that optimizes payment method display for each user.
You can override the default order in which payment methods display in the Express Checkout Element with a list of payment method types.
If there are payment methods that will show that are not specified in paymentMethodOrder, they display after the payment methods you specify. If you specify payment methods that will not show, they are ignored.
phoneNumberRequired boolean
Collect the customer's phone number by setting this option to true.
PayPal doesn't provide a phone number, even when this option is set to true.
shippingAddressRequired boolean
Collect the customer's shipping address by setting this option to true.
If true, you must also supply a valid shippingRates option in either the create, click, or shippingaddresschange events.
shippingRates array
An array of ShippingRate objects. The first shipping rate listed appears in the payment interface as the default option.
Hide shippingRates properties
id required string
Unique identifier for the object.
amount required number
The amount to charge for shipping.
displayName required string
The name of the shipping rate, displayed to the customer in the payment interface.
deliveryEstimate object | string
The estimated range for how long shipping takes, displayed to the customer in the payment interface. We recommended using the object format, but you can use a string instead.
Hide deliveryEstimate properties
maximum object
The upper bound of the estimated range. If empty, it represents no upper bound (for example, infinite).
Hide maximum properties
unit 'hour' | 'day' | 'business_day' | 'week' | 'month'
value number
minimum object
The lower bound of the estimated range. If empty, it represents no lower bound.
Hide minimum properties
unit 'hour' | 'day' | 'business_day' | 'week' | 'month'
value number
Create an Express Checkout Element
The Element
Express Checkout Element
Get an Express Checkout Element
elements.getElement('expressCheckout')
This method retrieves a previously created Express Checkout Element.
Method parameters
type required 'expressCheckout'
The type of Element being retrieved, which is expressCheckout in this case.
elements.getElement('expressCheckout') returns one of the following:
- An instance of an Express Checkout Element.
null, when no Express Checkout Element has been created.
Get an Express Checkout Element
The Element
Express Checkout Element
Update an Express Checkout Element
Method parameters
options optional object
Options for updating the Express Checkout Element.
Hide options properties
allowedShippingCountries array
By default, the Express Checkout Element allows all countries for shipping.
You can specify which countries are allowed for shipping in the Express Checkout Element with a list of two-letter country codes.
billingAddressRequired boolean
By default, the Express Checkout Element collects the billing address. You can disable this by setting billingAddressRequired to false.
We highly recommend that you collect the billing address because it can be used to perform address verifications and block fraudulent payments.
emailRequired boolean
Collect the customer's email by setting this option to true.
layout object
Specify how the buttons are arranged in a grid-like layout in the Express Checkout Element. Elements determines the layout by using certain factors, such as available space, number of buttons, and the defined layout object.
Hide layout properties
maxColumns number
Defines the maximum number of columns the Express Checkout Element can use to render. Default is 0, meaning unlimited.
maxRows number
Defines the maximum number of rows the Express Checkout Element can use to render. Default is 0, meaning unlimited.
overflow 'auto' | 'never'
Specify whether or not to always hide the overflow menu or allow Elements to determine when to show the overflow menu. Default is auto. You can't specify both overflow: 'never' and set maxRows to a number greater than 0.
paymentMethodOrder array
By default, the Express Checkout Element uses a dynamic ordering that optimizes payment method display for each user.
You can override the default order in which payment methods display in the Express Checkout Element with a list of payment method types.
If there are payment methods that will show that are not specified in paymentMethodOrder, they display after the payment methods you specify. If you specify payment methods that will not show, they are ignored.
phoneNumberRequired boolean
Collect the customer's phone number by setting this option to true.
PayPal doesn't provide a phone number, even when this option is set to true.
shippingAddressRequired boolean
Collect the customer's shipping address by setting this option to true.
If true, you must also supply a valid shippingRates option in either the create, click, or shippingaddresschange events.
Update an Express Checkout Element
The Element
Express Checkout Element
Click event
expressCheckoutElement.on('click',handler)
The click event is triggered from an Express Checkout Element when the customer clicks a payment button. Use this event to configure the payment interface.
Method parameters
event required 'click'
The name of the event. In this case, click.
handler required function
handler(event) => void is a callback function you provide that's called after the event is fired.
After it's called, it passes an event object with the following properties:
Hide handler event object properties
elementType required 'expressCheckout'
The type of element the event is fired from, which is expressCheckout in this case.
expressPaymentType required 'apple_pay' | 'google_pay' | 'amazon_pay' | 'paypal' | 'link' | 'klarna'
The payment method the customer checks out with.
resolve required function
A function resolve(payload) => void that's called to show the payment interface. You must call this function within 1 second if you handle the click event.
Hide resolve parameters
allowedShippingCountries (deprecated) array
This parameter has been deprecated in favor of the allowedShippingCountries param on the create function.
By default, the Express Checkout Element allows all countries for shipping.
You can specify which countries are allowed for shipping in the Express Checkout Element with a list of two-letter country codes.
applePay object
Specify Apple Pay specific options. These are passed through to the Apple Pay API.
Hide applePay properties
recurringPaymentRequest object
Hide recurringPaymentRequest properties
paymentDescription required string
managementURL required string
regularBilling required object
Hide regularBilling properties
amount required number
label required string
recurringPaymentStartDate Date
recurringPaymentEndDate Date
recurringPaymentIntervalUnit 'year' | 'month' | 'day' | 'hour' | 'minute'
recurringPaymentIntervalCount number
trialBilling object
Hide trialBilling properties
amount required number
label required string
recurringPaymentStartDate Date
recurringPaymentEndDate Date
recurringPaymentIntervalUnit 'year' | 'month' | 'day' | 'hour' | 'minute'
recurringPaymentIntervalCount number
billingAgreement string
deferredPaymentRequest object
Hide deferredPaymentRequest properties
paymentDescription required string
managementURL required string
deferredBilling required object
Hide deferredBilling properties
amount required number
label required string
deferredPaymentDate required Date
billingAgreement string
freeCancellationDate Date
If set, you must also supply a freeCancellationDateTimeZone.
freeCancellationDateTimeZone string
If set, you must also supply a freeCancellationDate.
These are tz timezones such as America/Los_Angeles, Europe/Dublin, and Asia/Singapore.
automaticReloadPaymentRequest object
Hide automaticReloadPaymentRequest properties
paymentDescription required string
managementURL required string
automaticReloadBilling required object
Hide automaticReloadBilling properties
amount required number
label required string
automaticReloadPaymentThresholdAmount required number
billingAgreement string
billingAddressRequired (deprecated) boolean
This parameter has been deprecated in favor of the billingAddressRequired param on the create function.
By default, the Express Checkout Element collects the billing address. You can disable this by setting billingAddressRequired to false.
We highly recommend that you collect the billing address because it can be used to perform address verifications and block fraudulent payments.
business (deprecated) object
This parameter has been deprecated in favor of the business param on the create function.
Provide information about your business that's displayed in the Express Checkout Element. This information will be retrieved from your Stripe account if it's not provided.
Hide business (deprecated) properties
name string
The name of your business. Your business name is used to signal to the customer who they're paying.
Klarna always retrieves the business name from your Stripe account, even when this option is set.
emailRequired (deprecated) boolean
This parameter has been deprecated in favor of the emailRequired param on the create function.
Collect the customer's email by setting this option to true.
lineItems array
An array of LineItem objects. These LineItems are shown as line items in the payment interface, if line items are supported. You can represent discounts as negative amount LineItems.
Hide lineItems properties
name required string
The name of the line item surfaced to the customer in the payment interface.
amount required number
The amount in the currency's subunit (for example, cents, yen, etc.).
phoneNumberRequired (deprecated) boolean
This parameter has been deprecated in favor of the phoneNumberRequired param on the create function.
Collect the customer's phone number by setting this option to true.
PayPal doesn't provide a phone number, even when this option is set to true.
shippingAddressRequired (deprecated) boolean
This parameter has been deprecated in favor of the shippingAddressRequired param on the create function.
Collect the customer's shipping address by setting this option to true.
If true, you must also supply a valid shippingRates option in either the create, click, or shippingaddresschange events.
shippingRates array
An array of ShippingRate objects. The first shipping rate listed appears in the payment interface as the default option.
Hide shippingRates properties
id required string
Unique identifier for the object.
amount required number
The amount to charge for shipping.
displayName required string
The name of the shipping rate, displayed to the customer in the payment interface.
deliveryEstimate object | string
The estimated range for how long shipping takes, displayed to the customer in the payment interface. We recommended using the object format, but you can use a string instead.
Hide deliveryEstimate properties
maximum object
The upper bound of the estimated range. If empty, it represents no upper bound (for example, infinite).
Hide maximum properties
unit 'hour' | 'day' | 'business_day' | 'week' | 'month'
value number
minimum object
The lower bound of the estimated range. If empty, it represents no lower bound.
Hide minimum properties
unit 'hour' | 'day' | 'business_day' | 'week' | 'month'
value number
reject required function
A function reject() => void that's called to cancel the payment interface. You must call this function within 1 second if you handle the click event.
Handle an express checkout element click event
The Element
Express Checkout Element
Confirm event
expressCheckoutElement.on('confirm',handler)
The confirm event is triggered from an Express Checkout Element when the customer finalizes their payment. Use this event to trigger payment confirmation.
Method parameters
event required string
The name of the event. In this case, confirm.
handler required function
A callback function handler(event) => void you provide that's called after the event is fired. When called, it passes an event object with the following properties:
Hide handler event object properties
elementType required 'expressCheckout'
The type of element the event fires from, which is expressCheckout in this case.
expressPaymentType required 'apple_pay' | 'google_pay' | 'amazon_pay' | 'paypal' | 'link' | 'klarna'
The payment method the customer checks out with.
paymentFailed required function
A function paymentFailed(payload) => void that's called if you're unable to process the customer's payment.
Hide paymentFailed parameters
reason 'fail' | 'invalid_shipping_address' | 'invalid_billing_address' | 'invalid_payment_data' | 'address_unserviceable'
Default is 'fail'. The payment interface might surface the reason to provide a hint to the customer on why their payment failed.
message string
A short, concise, localized error message to display on the payment sheet. If none is provided, the payment sheet will display a generic error message for the given reason.
Note: Custom error messages may not be supported or may be truncated by certain wallets.
billingDetails object
Object containing information about the customer's billing details.
Hide billingDetails properties
name string
The name of the customer.
email string
The email address of the customer.
phone string
The phone number of the customer.
address string
The billing address of the customer.
Note: When using PayPal, the full billing address of the customer is not always exposed. Typically, only the country code is passed back from PayPal. To access the full billing address, you would need to request it from PayPal directly.
Hide address properties
line1 string
line2 string
city string
state string
postal_code string
country string
shippingAddress object
Object containing information about the customer's shipping address.
Hide shippingAddress properties
name string
The name of the recipient.
address string
The shipping address of the customer.
Hide address properties
line1 string
line2 string
city string
state string
postal_code string
country string
shippingRate object
Object containing information about the selected shipping rate.
Hide shippingRate properties
id required string
Unique identifier for the object.
amount required number
The amount to charge for shipping.
displayName required string
The name of the shipping rate, displayed to the customer in the payment interface.
deliveryEstimate object | string
The estimated range for how long shipping takes, displayed to the customer in the payment interface. We recommended using the object format, but you can use a string instead.
Hide deliveryEstimate properties
maximum object
The upper bound of the estimated range. If empty, it represents no upper bound (for example, infinite).
Hide maximum properties
unit 'hour' | 'day' | 'business_day' | 'week' | 'month'
value number
minimum object
The lower bound of the estimated range. If empty, it represents no lower bound.
Hide minimum properties
unit 'hour' | 'day' | 'business_day' | 'week' | 'month'
value number
The Element
Express Checkout Element
Cancel event
expressCheckoutElement.on('cancel',handler)
The cancel event is triggered from an Express Checkout Element when the payment interface is dismissed.
Note that in some browsers, the payment interface might be dismissed by the customer even after they authorize the payment. This means that you might receive a cancel event after receiving a confirm event. If you're using the cancel event as a hook for canceling the customer's order, make sure you also refund the payment that you just created.
Method parameters
event required string
The name of the event. In this case, cancel.
handler required function
A callback function that you provide that's called after the event is fired.
The Element
Express Checkout Element
Shipping address change event
expressCheckoutElement.on('shippingaddresschange',handler)
The shippingaddresschange event is triggered from an Express Checkout Element whenever the customer selects a new address in the payment interface.
Method parameters
event required string
The name of the event. In this case, shippingaddresschange.
handler required function
A callback function handler(event) => void you provide that's called after the event is fired. After it's called, it passes an event object with the following properties:
Hide handler event object properties
elementType required 'expressCheckout'
The type of element the event is fired from, which is expressCheckout in this case.
resolve required function
A function resolve(payload) => void that's called if the recipient's shipping address is valid.
Hide resolve parameters
applePay object
Specify Apple Pay specific options. These are passed through to the Apple Pay API.
Hide applePay properties
recurringPaymentRequest object
Hide recurringPaymentRequest properties
paymentDescription required string
managementURL required string
regularBilling required object
Hide regularBilling properties
amount required number
label required string
recurringPaymentStartDate Date
recurringPaymentEndDate Date
recurringPaymentIntervalUnit 'year' | 'month' | 'day' | 'hour' | 'minute'
recurringPaymentIntervalCount number
trialBilling object
Hide trialBilling properties
amount required number
label required string
recurringPaymentStartDate Date
recurringPaymentEndDate Date
recurringPaymentIntervalUnit 'year' | 'month' | 'day' | 'hour' | 'minute'
recurringPaymentIntervalCount number
automaticReloadPaymentRequest object
Hide automaticReloadPaymentRequest properties
paymentDescription required string
managementURL required string
automaticReloadBilling required object
Hide automaticReloadBilling properties
amount required number
label required string
automaticReloadPaymentThresholdAmount required number
lineItems array
An array of LineItem objects. These LineItems are shown as line items in the payment interface, if line items are supported.
Hide lineItems properties
name required string
The name of the line item surfaced to the customer in the payment interface.
amount required number
The amount in the currency's subunit (for example, cents, yen, etc.).
shippingRates array
An array of ShippingRate objects. The first shipping rate listed appears in the payment interface as the default option.
Hide shippingRates properties
id required string
Unique identifier for the object.
amount required number
The amount to charge for shipping.
displayName required string
The name of the shipping rate, displayed to the customer in the payment interface.
deliveryEstimate object | string
The estimated range for how long shipping takes, displayed to the customer in the payment interface. We recommended using the object format, but you can use a string instead.
Hide deliveryEstimate properties
maximum object
The upper bound of the estimated range. If empty, it represents no upper bound (for example, infinite).
Hide maximum properties
unit 'hour' | 'day' | 'business_day' | 'week' | 'month'
value number
minimum object
The lower bound of the estimated range. If empty, it represents no lower bound.
Hide minimum properties
unit 'hour' | 'day' | 'business_day' | 'week' | 'month'
value number
reject required function
A function reject() => void that's called if the recipient's shipping address is invalid.
name string
The name of the recipient.
address string
The shipping address of the recipient.
To maintain privacy, browsers might anonymize the shipping address by removing sensitive information that isn't necessary to calculate shipping costs. Depending on the country, some fields can be missing or partially redacted. For example, the shipping address in the US can only contain a city, state, and ZIP code. The full shipping address appears in the confirm event object after the purchase is confirmed in the browser’s payment interface.
Hide address properties
city string
state string
postal_code string
country string
Handle 'shippingaddresschange' event
The Element
Express Checkout Element
Shipping rate change event
expressCheckoutElement.on('shippingratechange',handler)
The shippingratechange event is triggered from an Express Checkout Element whenever the customer selects a new shipping rate in the payment interface.
Method parameters
event required string
The name of the event. In this case, shippingratechange.
handler required function
A callback function handler(event) => void you provide that's called after the event is fired. After it's called, it passes an event object with the following properties:
Hide handler event object properties
elementType required 'expressCheckout'
The type of element the event is fired from, which is expressCheckout in this case.
resolve required function
A function resolve(payload) => void that's called if the customer's shipping rate is valid.
Hide resolve parameters
applePay object
Specify Apple Pay specific options. These are passed through to the Apple Pay API.
Hide applePay properties
recurringPaymentRequest object
Hide recurringPaymentRequest properties
paymentDescription required string
managementURL required string
regularBilling required object
Hide regularBilling properties
amount required number
label required string
recurringPaymentStartDate Date
recurringPaymentEndDate Date
recurringPaymentIntervalUnit 'year' | 'month' | 'day' | 'hour' | 'minute'
recurringPaymentIntervalCount number
trialBilling object
Hide trialBilling properties
amount required number
label required string
recurringPaymentStartDate Date
recurringPaymentEndDate Date
recurringPaymentIntervalUnit 'year' | 'month' | 'day' | 'hour' | 'minute'
recurringPaymentIntervalCount number
automaticReloadPaymentRequest object
Hide automaticReloadPaymentRequest properties
paymentDescription required string
managementURL required string
automaticReloadBilling required object
Hide automaticReloadBilling properties
amount required number
label required string
automaticReloadPaymentThresholdAmount required number
lineItems array
An array of LineItem objects. These LineItems are shown as line items in the payment interface, if line items are supported.
Hide lineItems properties
name required string
The name of the line item surfaced to the customer in the payment interface.
amount required number
The amount in the currency's subunit (for example, cents, yen, etc.).
shippingRates array
An array of ShippingRate objects. The first shipping rate listed appears in the payment interface as the default option.
Hide shippingRates properties
id required string
Unique identifier for the object.
amount required number
The amount to charge for shipping.
displayName required string
The name of the shipping rate, displayed to the customer in the payment interface.
deliveryEstimate object | string
The estimated range for how long shipping takes, displayed to the customer in the payment interface. We recommended using the object format, but you can use a string instead.
Hide deliveryEstimate properties
maximum object
The upper bound of the estimated range. If empty, it represents no upper bound (for example, infinite).
Hide maximum properties
unit 'hour' | 'day' | 'business_day' | 'week' | 'month'
value number
minimum object
The lower bound of the estimated range. If empty, it represents no lower bound.
Hide minimum properties
unit 'hour' | 'day' | 'business_day' | 'week' | 'month'
value number
reject required function
A function reject() => void that's called if the customer's shipping rate is invalid.
shippingRate object
The shipping rate selected by the customer.
Hide shippingRate properties
id required string
Unique identifier for the object.
amount required number
The amount to charge for shipping.
displayName required string
The name of the shipping rate, displayed to the customer in the payment interface.
deliveryEstimate object | string
The estimated range for how long shipping takes, displayed to the customer in the payment interface. We recommended using the object format, but you can use a string instead.
Hide deliveryEstimate properties
maximum object
The upper bound of the estimated range. If empty, it represents no upper bound (for example, infinite).
Hide maximum properties
unit 'hour' | 'day' | 'business_day' | 'week' | 'month'
value number
minimum object
The lower bound of the estimated range. If empty, it represents no lower bound.
Hide minimum properties
unit 'hour' | 'day' | 'business_day' | 'week' | 'month'
value number
Handle 'shippingratechange' event
The Element
Link Authentication Element
The Link Authentication Element
The Link Authentication Element is an embeddable component for collecting email addresses and allow users to log into Link on your checkout page.
The Element
Link Authentication Element
Create a Link Authentication Element
elements.create('linkAuthentication',options?)
This method creates an instance of the Link Authentication Element.
Method parameters
type required 'linkAuthentication'
The type of Element being created, which is linkAuthentication in this case.
options optional object
Options for creating the Link Authentication Element.
Hide options properties
defaultValues object
Provide the initial contact information that will be displayed in the Link Authentication Element. The form will render with empty fields if not provided.
Hide defaultValues properties
Create a Link Authentication Element
The Element
Link Authentication Element
Get a Link Authentication Element
elements.getElement('linkAuthentication')
This method retrieves a previously created Link Authentication Element.
Method parameters
type required 'linkAuthentication'
The type of Element being retrieved, which is linkAuthentication in this case.
elements.getElement('linkAuthentication') returns one of the following:
- An instance of a Link Authentication Element.
null, when no Link Authentication Element has been created.
Get a Link Authentication Element
The Element
Address Element
The Address Element
The Address Element is an embeddable component for collecting local and international billing and shipping addresses.
The Element
Address Element
Create an Address Element
elements.create('address',options)
This method creates an instance of the Address Element.
NOTE: If you are creating multiple instances of the Address Element, configuration of the checkbox to sync shipping and billing addresses exists in the creation of the Elements instance.
Method parameters
type required 'address'
The type of Element being created, which is address in this case.
You can create multiple Address Elements, one of each mode, in a single Elements instance.
options required object
Options for creating the Address Element.
Hide options properties
mode required 'shipping' | 'billing'
Specify which mode you would like to use Address Element for.
When shipping mode is used with the Payment Element and Link Authentication Element, it will automatically pass shipping information when confirming Payment Intent or Setup Intent.
When billing mode is used with the Payment Element, it will automatically pass the billing information when confirming Payment Intent or Setup Intent.
autocomplete object
By default, the Address Element will have autocomplete enabled with Stripe provided Google Maps API key for certain countries if any of the following condition is met:
- If Payment Element is mounted in the same elements group as Address Element in a single page application.
- If the Address Element is used in an active Link session.
By using autocomplete, you agree to comply with the Google Maps Platform Acceptable Use Policy. If you violate this policy, we might disable autocomplete, or take any other action as necessary.
You can customize the autocomplete setting with this option.
Hide autocomplete properties
mode required ‘automatic’ | ‘disabled’ | ‘google_maps_api’
Specify disabled to disable autocomplete in the Address Element.
Specify google_maps_api to enable Google Maps API with your own key. It will only be used when Stripe provided Google Maps API key is not available.
The default setting is automatic, where we’ll support autocomplete when possible.
apiKey string
Specify your own Google Maps API key with it.
Only needs to be passed in when autocomplete.mode is set to google_maps_api.
allowedCountries array
By default, the Address Element will display all countries for selection.
You can specify which countries are displayed in the Address Element with a list of two-letter country codes. If only one country is specified, the country field will not display.
blockPoBox boolean
By default, PO boxes are considered a valid address type.
You can override this to invalidate PO Boxes.
contacts array
An array of Contact objects that can be displayed as saved addresses in the Address Element. The first contact will be automatically selected.
If using a CustomerSession, Address Element will ignore contacts and render saved billing addresses instead.
defaultValues object
Provide the initial information that will be displayed in the Address Element. The form will render with empty fields if not provided.
Hide defaultValues properties
name string
Provide the initial full name or organization name.
firstName string
Provide the initial first name. The display.name option must be set to split if this property is specified.
lastName string
Provide the initial last name. The display.name option must be set to split if this property is specified.
phone string
Provide the initial phone number value. The fields.phone option must be set to always if this property is specified.
address object
Provide the initial address details.
Hide address properties
line1 string
line2 string
city string
state string
postal_code string
country required string
fields object
By default, the Address Element will collect all the necessary information needed for an address. In some cases, it might be necessary to collect other types of information. You can specify other types of fields to render in the form with this option.
Hide fields properties
phone 'always' | 'auto' | 'never'
Specify always to enable phone number collection in the Address Element. Only collect phone numbers if you need them for the transaction. Default is auto.
validation object
By default, the Address Element will enforce preset validation for each field. You can customize the settings by using this option.
Hide validation properties
phone object
Hide phone properties
required 'always' | 'auto' | 'never'
Specify always to make phone number a required field. The fields.phone option must be set to always if this property is specified. Default is auto.
display object
You can customize how certain fields are displayed.
Hide display properties
name 'full' | 'split' | 'organization'
By default, the Address Element will display a full name field. Specify 'split' to display a first name field and a last name field. Specify 'organization' to display an organization field.
Create an Address Element
The Element
Address Element
Get an Address Element
elements.getElement('address',options?)
This method retrieves a previously created Address Element.
Method parameters
type required 'address'
The type of Element being retrieved, which is address in this case.
options optional object
Options for retrieving the Address Element.
Hide options properties
mode 'shipping' | 'billing'
Required when using multiple Address Elements.
Specify which mode of the Address Element you would like to retrieve.
elements.getElement('address') returns one of the following:
- An instance of an Address Element.
null, when no Address Element has been created.
The Element
Address Element
Update an Address Element
Updates the options the Address Element was initialized with. Updates are merged into the existing configuration.
Method parameters
options optional object
Options for updating the Address Element.
Hide options properties
fields object
By default, the Address Element will collect all the necessary information needed for an address. In some cases, it might be necessary to collect other types of information. You can specify other types of fields to render in the form with this option.
Hide fields properties
phone 'always' | 'auto' | 'never'
Specify always to enable phone number collection in the Address Element. Only collect phone numbers if you need them for the transaction. Default is auto.
validation object
By default, the Address Element will enforce preset validation for each field. You can customize the settings by using this option.
Hide validation properties
phone object
Hide phone properties
required 'always' | 'auto' | 'never'
Specify always to make phone number a required field. The fields.phone option must be set to always if this property is specified. Default is auto.
Update an Address Element
The Element
Address Element
Get value from an Address Element
Validates and retrieves form values from an Address Element. If there are any input validation errors, the errors will display by their respective fields.
addressElement.getValue() returns a promise. This promise will return an object with the following:
complete, true if the value is well-formed and potentially complete. The complete value can be used to progressively disclose the next parts of your form or to enable form submission. It is not an indicator of whether a customer is done with their input—it only indicates that the Element contains a potentially complete, well-formed value. In many cases the customer could still add further input.isNewAddress, true if the Address Element is currently displaying the form collection view.value, an object containing the current address information. The firstName and lastName properties only appear if the display.name option is set to split. The phone property only appears if the fields.phone option is set to always.
Get value from an Address Element
The Element
Issuing Elements
Issuing Elements
Issuing Elements allows you to display the sensitive data of your Issuing cards in a PCI-compliant manner.
The Element
Issuing Elements
Create an Issuing Element
elements.create('issuingCardNumberDisplay'
This method creates an instance of an individual Issuing Element.
It takes the type of Element to create as well as an options object.
Method parameters
type required string
The type of Element being created. One of: issuingCardNumberDisplay, issuingCardCvcDisplay, issuingCardExpiryDisplay, issuingCardPinDisplay, or issuingCardCopyButton.
options required object
Options for creating an Issuing element.
Hide options properties
issuingCard string
ephemeralKeySecret string
The secret component of the ephemeral key created to display this Element.
nonce string
The ephemeral key nonce used to create the ephemeral key provided to this Element.
style object
Customize the appearance of this Element using CSS properties passed in a Style object.
Create a issuingCardNumberDisplay Element
The Element
Other Elements
The Element
Other Elements
Create an Element
elements.create(,options?)
This method creates an instance of an individual Element.
It takes the type of Element to create as well as an options object.
Method parameters
type required 'card'
The type of element you are creating. In this case, card.
options optional object
Options for creating a card element.
Hide options properties
classes object
Set custom class names on the container DOM element when the Stripe element is in a particular state.
Hide classes properties
base string
The base class applied to the container. Defaults to StripeElement.
complete string
The class name to apply when the Element is complete. Defaults to StripeElement--complete.
empty string
The class name to apply when the Element is empty. Defaults to StripeElement--empty.
focus string
The class name to apply when the Element is focused. Defaults to StripeElement--focus.
invalid string
The class name to apply when the Element is invalid. Defaults to StripeElement--invalid.
webkitAutofill string
The class name to apply when the Element has its value autofilled by the browser (only on Chrome and Safari). Defaults to StripeElement--webkit-autofill.
style object
Customize the appearance of this element using CSS properties passed in a Style object.
value object
A pre-filled set of values to include in the input. Note that sensitive card information (card number, CVC, and expiration date) cannot be pre-filled.
hidePostalCode boolean
Hide the postal code field. Default is false. If you are already collecting a full billing address or postal code elsewhere, set this to true.
iconStyle string
Appearance of the icon in the Element. Either solid or default.
hideIcon boolean
Hides the icon in the Element. Default is false.
disabled boolean
Applies a disabled state to the Element such that user input is not accepted. Default is false.
disableLink boolean
Disables and hides the Link button in the Element. Default is false. You can also disable Link across all instances of card and cardNumber elements in your payment method settings.
preferredNetwork array
Specifies a network preference for Card Brand Choice. The first network in the array that matches a network on the entered co-branded card will be selected by default in the Card Brand Choice dropdown. See the supported networks for valid values.
If you specify a value for preferredNetwork at create time, hideIcon must not be true (so that the Card Brand Choice dropdown can appear) and you cannot specify payment_method_options.card.network at confirm time.
The Element
Other Elements
Get an Element
elements.getElement(type)
This method looks up a previously created Element by its type.
elements.getElement returns one of the following:
- An instance of an
Element with a matching type. null, when no Element with a matching type has been created.
The Element
Other Elements
Update an Element
Updates the options the Element was initialized with. Updates are merged into the existing configuration.
If you collect certain information in a different part of your interface (e.g., ZIP or postal code), use element.update with the appropriate information.
The styles of an Element can be dynamically changed using element.update. This method can be used to simulate CSS media queries that automatically adjust the size of elements when viewed on different devices.
Method parameters
options optional object
Options for updating a card element.
Hide options properties
classes object
Set custom class names on the container DOM element when the Stripe element is in a particular state.
Hide classes properties
base string
The base class applied to the container. Defaults to StripeElement.
complete string
The class name to apply when the Element is complete. Defaults to StripeElement--complete.
empty string
The class name to apply when the Element is empty. Defaults to StripeElement--empty.
focus string
The class name to apply when the Element is focused. Defaults to StripeElement--focus.
invalid string
The class name to apply when the Element is invalid. Defaults to StripeElement--invalid.
webkitAutofill string
The class name to apply when the Element has its value autofilled by the browser (only on Chrome and Safari). Defaults to StripeElement--webkit-autofill.
style object
Customize the appearance of this element using CSS properties passed in a Style object.
value object
A pre-filled set of values to include in the input. Note that sensitive card information (card number, CVC, and expiration date) cannot be pre-filled.
hidePostalCode boolean
Hide the postal code field. Default is false. If you are already collecting a full billing address or postal code elsewhere, set this to true.
iconStyle string
Appearance of the icon in the Element. Either solid or default.
hideIcon boolean
Hides the icon in the Element. Default is false.
disabled boolean
Applies a disabled state to the Element such that user input is not accepted. Default is false.
The Element
Other Elements
Style the Element container
Style the Element container
Style the container you mount an Element to as if it were an <input> on your page. For example, to control padding and border on an Element, set these properties on the container. This is usually done by re-using the classes that you have applied to your DOM <input> elements. After the Element is mounted, the .StripeElement class is added to the container. Additionally, the following classes are automatically added to the container when the Element is complete, empty, focused, invalid, or autofilled by the browser:
.StripeElement--complete.StripeElement--empty.StripeElement--focus.StripeElement--invalid.StripeElement--webkit-autofill (Chrome and Safari only)
These class names can be customized using the classes option when you create an Element.
The Element
Mount an Element
element.mount(domElement)
The element.mount method attaches your Element to the DOM. element.mount accepts either a CSS Selector (e.g., '#card-element') or a DOM element.
You need to create a container DOM element to mount an Element. If the container DOM element has a label, the Element is automatically focused when its label is clicked. There are two ways to do this:
- Mount the instance within a
<label>. - Create a
<label> with a for attribute, referencing the ID of your container.
Method parameters
domElement required string | DOM element
The CSS selector or DOM element where your Element will be mounted.
The Element
Element methods
Element methods
Below are a number of methods that are in common between all Element UIs. Wait until the ready event is triggered before calling these methods.
The Element
Element methods
Blur an Element
The Element
Element methods
Clear an Element's values
Clears the value(s) of the Element.
The Element
Element methods
Destroy an Element
Removes the Element from the DOM and destroys it. A destroyed Element can not be re-activated or re-mounted to the DOM.
The Element
Element methods
Focus an Element
This method will currently not work on iOS 13+ due to a system limitation.
The Element
Element methods
Unmount an Element
The Element
Listen to Element events
Element events
The only way to communicate with your Element is by listening to an event. An Element might emit any of the events below. All events have a payload object that has an elementType property with the type of the Element that emitted the event.
The Element
Listen to Element events
Change event
The change event is triggered when the Element's value changes. The event payload always contains certain keys, in addition to some Element-specific keys.
Method parameters
event required 'change'
The name of the event. In this case, change.
handler required function
handler(event) => void is a callback function that you provide that will be called when the event is fired. When called it will be passed an event object with the following properties:
Hide handler event object properties
elementType string
The type of element that emitted this event.
empty boolean
true if the value is empty.
complete boolean
true if all required fields for the selected payment method in the Payment Element have been filled with potentially valid input.
collapsed boolean
true if the Payment Element is currently collapsed
value object
An object containing the current selected PaymentMethod type. If a saved payment method is selected, it will be included in the object.
Consult with your legal counsel regarding your requirements and obligations about how you collect, use, and store customers' personal data
Handle a payment element change event
The Element
Listen to Element events
Ready event
element.on('ready',handler)
Triggered when the Element is fully rendered and methods on the instance, like element.focus() and element.update(), can be called.
Method parameters
event required 'ready'
The name of the event. In this case, ready.
handler required function
handler(event) => void is a callback function that you provide that will be called when the event is fired.
After it's called, it passes an event object with the following properties:
Hide handler event object properties
elementType required string
The type of element the event is fired from.
availablePaymentMethods object | undefined
This field is only present on the expressCheckout Element. Describes which buttons render in the Element. Returns undefined if no buttons will render.
Hide availablePaymentMethods properties
link boolean
applePay boolean
googlePay boolean
paypal boolean
amazonPay boolean
klarna boolean
Handle an Element ready event
The Element
Listen to Element events
Focus event
element.on('focus',handler)
Triggered when the Element gains focus.
Method parameters
event required 'focus'
The name of the event. In this case, focus.
handler required function
handler(event) => void is a callback function that you provide that will be called when the event is fired.
Handle an Element focus event
The Element
Listen to Element events
Blur event
element.on('blur',handler)
Triggered when the Element loses focus.
Method parameters
event required 'blur'
The name of the event. In this case, blur.
handler required function
handler(event) => void is a callback function that you provide that will be called when the event is fired.
Handle an Element blur event
The Element
Listen to Element events
Escape event
element.on('escape',handler)
Triggered when the escape key is pressed within an Element.
Method parameters
event required 'escape'
The name of the event. In this case, escape.
handler required function
handler(event) => void is a callback function that you provide that will be called when the event is fired.
Handle an Element escape event
The Element
Listen to Element events
Click event
The click event is triggered from an Express Checkout Element when the customer clicks a payment button. Use this event to configure the payment interface.
Method parameters
event required 'click'
The name of the event. In this case, click.
handler required function
handler(event) => void is a callback function you provide that's called after the event is fired.
After it's called, it passes an event object with the following properties:
Hide handler event object properties
elementType required 'expressCheckout'
The type of element the event is fired from, which is expressCheckout in this case.
expressPaymentType required 'apple_pay' | 'google_pay' | 'amazon_pay' | 'paypal' | 'link' | 'klarna'
The payment method the customer checks out with.
resolve required function
A function resolve(payload) => void that's called to show the payment interface. You must call this function within 1 second if you handle the click event.
Hide resolve parameters
allowedShippingCountries (deprecated) array
This parameter has been deprecated in favor of the allowedShippingCountries param on the create function.
By default, the Express Checkout Element allows all countries for shipping.
You can specify which countries are allowed for shipping in the Express Checkout Element with a list of two-letter country codes.
applePay object
Specify Apple Pay specific options. These are passed through to the Apple Pay API.
Hide applePay properties
recurringPaymentRequest object
Hide recurringPaymentRequest properties
paymentDescription required string
managementURL required string
regularBilling required object
Hide regularBilling properties
amount required number
label required string
recurringPaymentStartDate Date
recurringPaymentEndDate Date
recurringPaymentIntervalUnit 'year' | 'month' | 'day' | 'hour' | 'minute'
recurringPaymentIntervalCount number
trialBilling object
Hide trialBilling properties
amount required number
label required string
recurringPaymentStartDate Date
recurringPaymentEndDate Date
recurringPaymentIntervalUnit 'year' | 'month' | 'day' | 'hour' | 'minute'
recurringPaymentIntervalCount number
billingAgreement string
deferredPaymentRequest object
Hide deferredPaymentRequest properties
paymentDescription required string
managementURL required string
deferredBilling required object
Hide deferredBilling properties
amount required number
label required string
deferredPaymentDate required Date
billingAgreement string
freeCancellationDate Date
If set, you must also supply a freeCancellationDateTimeZone.
freeCancellationDateTimeZone string
If set, you must also supply a freeCancellationDate.
These are tz timezones such as America/Los_Angeles, Europe/Dublin, and Asia/Singapore.
automaticReloadPaymentRequest object
Hide automaticReloadPaymentRequest properties
paymentDescription required string
managementURL required string
automaticReloadBilling required object
Hide automaticReloadBilling properties
amount required number
label required string
automaticReloadPaymentThresholdAmount required number
billingAgreement string
billingAddressRequired (deprecated) boolean
This parameter has been deprecated in favor of the billingAddressRequired param on the create function.
By default, the Express Checkout Element collects the billing address. You can disable this by setting billingAddressRequired to false.
We highly recommend that you collect the billing address because it can be used to perform address verifications and block fraudulent payments.
business (deprecated) object
This parameter has been deprecated in favor of the business param on the create function.
Provide information about your business that's displayed in the Express Checkout Element. This information will be retrieved from your Stripe account if it's not provided.
Hide business (deprecated) properties
name string
The name of your business. Your business name is used to signal to the customer who they're paying.
Klarna always retrieves the business name from your Stripe account, even when this option is set.
emailRequired (deprecated) boolean
This parameter has been deprecated in favor of the emailRequired param on the create function.
Collect the customer's email by setting this option to true.
lineItems array
An array of LineItem objects. These LineItems are shown as line items in the payment interface, if line items are supported. You can represent discounts as negative amount LineItems.
Hide lineItems properties
name required string
The name of the line item surfaced to the customer in the payment interface.
amount required number
The amount in the currency's subunit (for example, cents, yen, etc.).
phoneNumberRequired (deprecated) boolean
This parameter has been deprecated in favor of the phoneNumberRequired param on the create function.
Collect the customer's phone number by setting this option to true.
PayPal doesn't provide a phone number, even when this option is set to true.
shippingAddressRequired (deprecated) boolean
This parameter has been deprecated in favor of the shippingAddressRequired param on the create function.
Collect the customer's shipping address by setting this option to true.
If true, you must also supply a valid shippingRates option in either the create, click, or shippingaddresschange events.
shippingRates array
An array of ShippingRate objects. The first shipping rate listed appears in the payment interface as the default option.
Hide shippingRates properties
id required string
Unique identifier for the object.
amount required number
The amount to charge for shipping.
displayName required string
The name of the shipping rate, displayed to the customer in the payment interface.
deliveryEstimate object | string
The estimated range for how long shipping takes, displayed to the customer in the payment interface. We recommended using the object format, but you can use a string instead.
Hide deliveryEstimate properties
maximum object
The upper bound of the estimated range. If empty, it represents no upper bound (for example, infinite).
Hide maximum properties
unit 'hour' | 'day' | 'business_day' | 'week' | 'month'
value number
minimum object
The lower bound of the estimated range. If empty, it represents no lower bound.
Hide minimum properties
unit 'hour' | 'day' | 'business_day' | 'week' | 'month'
value number
reject required function
A function reject() => void that's called to cancel the payment interface. You must call this function within 1 second if you handle the click event.
Handle an express checkout element click event
The Element
Listen to Element events
LoadError event
element.on('loaderror',handler)
Triggered when the Element fails to load.
This event is only emitted from the payment, linkAuthentication, address, expressCheckout, card, and cardNumber Elements.
Method parameters
event required 'loaderror'
The name of the event. In this case, loaderror.
handler required function
handler(event) => void is a callback function that you provide that will be called when the event is fired.
When called it will be passed an event object with the following properties:
Hide handler event object properties
elementType string
The type of element that emitted this event.
error object
An error object that describes the failure.
Handle an Element loaderror event
The Element
Listen to Element events
LoaderStart event
element.on('loaderstart',handler)
Triggered when the loader UI is mounted to the DOM and ready to be displayed.
This event is only emitted from the payment, linkAuthentication, and address Elements.
Method parameters
event required 'loaderstart'
The name of the event. In this case, loaderstart.
handler required function
handler(event) => void is a callback function that you provide that will be called when the event is fired.
When called it will be passed an event object with the following properties:
Hide handler event object properties
elementType string
The type of element that emitted this event.
Handle an Element loaderstart event
The Element
Listen to Element events
NetworksChange event
.on('networkschange',handler)
Deprecated
Triggered when there is a change to the available networks the provided card can run on. If the list of available networks is still loading, an event with networks: null and loading: true is triggered. When the list of available networks loads, Stripe triggers an additional event that contains the list of these networks and shows loading: false. Refer to our card brand choice guide for further details.
Method parameters
event required 'networkschange'
The name of the event. In this case, networkschange.
handler required function
handler(event) => void is a callback function that you provide that will be called when the event is fired. When called it will be passed an event object with the following properties:
Hide handler event object properties
loading boolean
true if the networks are loading. false when Stripe returns all the available networks.
networks stringArray | null
All available networks for the card number provided. null if the networks are still loading.
If eligible for the Card Element's Card Brand Choice dropdown, this array will be truncated to a single network so that the user is not presented with multiple network selections.
Handle a card networkschange event
The Element
Postal code formatting
Postal code formatting
The card element automatically determines your customer’s billing address country based on their card number. Using this information, the postal code field validation reflects whether that country uses numeric or alphanumeric-formatted postal codes, or if the country uses postal codes at all. For instance, if a U.S. card is entered, the postal code field only accepts a five-digit numeric value. If it’s a UK card, an alphanumeric value can be provided instead.
Many of our test cards have a U.S. billing address country. When using these to test your payment form, you must also use a five-digit U.S. ZIP code (e.g., 12345). To test elements with other postal code formats, use our international test card numbers.
Embedded Checkout
Embedded Checkout
Checkout
Checkout is a low-code payment integration that creates a customizable payment form so you can quickly collect payments on desktop and mobile devices.
Embedded Checkout
Initialize embedded Checkout
stripe.initEmbeddedCheckout(options)
This method initializes embedded Checkout.
Method parameters
options required object
Embedded Checkout initialization options.
Hide options properties
fetchClientSecret Required function
clientSecret (deprecated) Required string
This param has been deprecated in favor of the fetchClientSecret param, which offers a faster loading experience.
The client secret for the Checkout Session.
onComplete function
An optional callback function onComplete() => void that is called on completion for Checkout Sessions with redirect_on_completion: if_required.
This method returns a Promise which resolves with an embedded Checkout instance.
Initialize embedded Checkout
Embedded Checkout
Mount embedded Checkout
checkout.mount(domElement)
The checkout.mount method attaches Checkout to the DOM. checkout.mount accepts either a CSS Selector (e.g., '#checkout') or a DOM element.
You need to create a container DOM element to mount Checkout.
Method parameters
domElement required string | DOM element
The CSS selector or DOM element where Checkout will be mounted.
Embedded Checkout
Unmount embedded Checkout
Unmounts Checkout from the DOM. Call checkout.mount to reattach it to the DOM.
Unmount embedded Checkout
Embedded Checkout
Destroy embedded Checkout
Removes Checkout from the DOM and destroys it. Once destroyed, an embedded Checkout instance cannot be reattached to the DOM.
Call checkout.initEmbeddedCheckout to create a new embedded Checkout instance after unmounting the previous instance from the DOM.
Destroy embedded Checkout
Checkout
Introduction
Elements with the Checkout Sessions API
Build an online checkout page using React, Stripe Elements, and the Checkout Sessions API.
See build a checkout page for steps on using Elements with the Checkout Sessions API.
The following Stripe.js methods are available to use as part of your integration.
Checkout
Initialize Checkout
stripe.initCheckout(options?)
This method initializes Checkout.
Method parameters
options optional object
Checkout initialization options.
Hide options properties
fetchClientSecret Required function
A function that retrieves the Checkout Session client secret from the server. This function should return a Promise resolving to a string client secret.
elementsOptions object
A set of options to configure Elements created with Checkout.
Hide elementsOptions properties
appearance object
Match the design of your site with the appearance option. The layout of each Element stays consistent, but you can modify colors, fonts, borders, padding, and more.
loader 'auto' | 'always' | 'never'
Display skeleton loader UI while waiting for Elements to fully load after they're mounted. Default is 'auto' (Stripe determines whether or not to show a loader UI).
fonts array
An array of custom fonts that elements created from the Elements object can use. You can specify fonts as CssFontSource or CustomFontSource objects.
This method returns a Promise that resolves with a Checkout instance.
Checkout
The Checkout object
The Checkout object
Use a Checkout instance to read and manipulate Checkout Sessions from your front end.
Checkout
The Checkout object
Read session data
This method returns an object that contains data about the Checkout Session.
Checkout
The Checkout object
Update the customer's shipping address
checkout.updateShippingAddress(shippingAddress)
Use this method to update the Customer's shipping address.
Method parameters
shippingAddress required nullable object
New shipping address for the Customer.
Hide shippingAddress properties
name optional string
address optional object
Hide address properties
country required string
line1 required string
Address line 1 (e.g., street, PO Box, or company name).
line2 optional string
Address line 2 (e.g., apartment, suite, unit, or building).
city optional string
City, district, suburb, town, or village.
postal_code optional string
state optional string
State, county, province, or region.
This method returns a Promise that resolves with an object containing the following fields:
type: one of either "success" or "error"session: only populated when type is "success". Contains a Session instance representing the updated state.error: only populated when type is "error". Contains an object with a string message field which can be displayed to your customer.
Update the Customer's shipping address
Checkout
The Checkout object
Update the customer's billing address
checkout.updateBillingAddress(billingAddress)
Use this method to update the Customer's billing address.
Method parameters
billingAddress required nullable object
New billing information for the Customer.
Hide billingAddress properties
name optional string
address optional object
Hide address properties
country required string
line1 optional string
Address line 1 (e.g., street, PO Box, or company name).
line2 optional string
Address line 2 (e.g., apartment, suite, unit, or building).
city optional string
City, district, suburb, town, or village.
postal_code optional string
state optional string
State, county, province, or region.
This method returns a Promise that resolves with an object containing the following fields:
type: one of either "success" or "error"session: only populated when type is "success". Contains a Session instance representing the updated state.error: only populated when type is "error". Contains an object with a string message field which can be displayed to your customer.
Update the Customer's billing address
Checkout
The Checkout object
Update the customer's email address
checkout.updateEmail(email)
Use this method to update the Customer's email address.
Method parameters
email required nullable string
The Customer's email address.
This method returns a Promise that resolves with an object containing the following fields:
type: one of either "success" or "error"session: only populated when type is "success". Contains a Session instance representing the updated state.error: only populated when type is "error". Contains an object with a string message field which can be displayed to your customer.
Update the Customer's email address
Checkout
The Checkout object
Update the customer's phone number
checkout.updatePhoneNumber(phoneNumber)
Use this method to update the Customer's phone number.
Method parameters
phoneNumber required nullable string
The Customer's phone number.
This method returns a Promise that resolves with an object containing the following fields:
type: one of either "success" or "error"session: only populated when type is "success". Contains a Session instance representing the updated state.error: only populated when type is "error". Contains an object with a string message field which can be displayed to your customer.
Update the Customer's phone number
Checkout
The Checkout object
Update the customer's business name and tax ID
checkout.updateTaxIdInfo(taxIdInfo?)
Use this method to update the Customer's business name and tax ID.
Method parameters
taxIdInfo optional
The Customer's tax ID information including the business name and tax ID.
Hide taxIdInfo properties
businessName required nullable string
The Customer's business name.
taxId required
Hide taxId properties
type required
value required nullable string
This method returns a Promise that resolves with an object containing the following fields:
type: one of either "success" or "error"session: only populated when type is "success". Contains a Session instance representing the updated state.error: only populated when type is "error". Contains an object with a string message field which can be displayed to your customer.
Update the Customer's business name and tax ID
Checkout
The Checkout object
Update line item quantities
checkout.updateLineItemQuantity(options)
Use this method to change the quantity of a line item.
Method parameters
options required object
Options for updateLineItemQuantity.
Hide options properties
lineItem required string
The ID of the line item to update.
quantity required integer
The new quantity of the line item.
This method returns a Promise that resolves with an object containing the following fields:
type: one of either "success" or "error"session: only populated when type is "success". Contains a Session instance representing the updated state.error: only populated when type is "error". Contains an object with a string message field which can be displayed to your customer.
Update line item quantities
Checkout
The Checkout object
Update shipping option
checkout.updateShippingOption(shippingOption?)
Use this method to update the selected shipping option. See shippingOptions for a list of the available shipping options.
Method parameters
shippingOption optional string
The ID of the shipping option to select.
This method returns a Promise that resolves with an object containing the following fields:
type: one of either "success" or "error"session: only populated when type is "success". Contains a Session instance representing the updated state.error: only populated when type is "error". Contains an object with a string message field which can be displayed to your customer.
Update the selected shipping option
Checkout
The Checkout object
Confirm the session
checkout.confirm(options?)
Use this method to confirm the Checkout Session.
You must either read total.total.amount or each of total.total.minorUnitsAmount and currency and minorUnitsAmountDivisor from the checkout object and display in your UI, otherwise an error will be thrown. This helps keep your checkout page in sync as the Checkout Session updates, including adding future Stripe features, with minimal UI code changes.
Method parameters
options optional object
Hide options properties
returnUrl string
The URL to redirect your customer to after they authenticate or cancel their payment on the payment method’s app or site. This parameter is only required if you didn't specify the return_url when creating the Checkout Session.
paymentMethod string
The ID of a previously collected PaymentMethod to use for confirmation.
When this option is provided, Custom Checkout will ignore the payment method collected by the PaymentElement and attempt confirmation using the provided PaymentMethod.
savePaymentMethod boolean
Whether your Customer has provided consent to save the payment method for future purchases.
Learn how to save payment methods.
redirect 'always' | 'if_required'
By default, confirm will always redirect to your returnUrl after a successful confirmation. If you set redirect: "if_required", then confirm will only redirect if your user chooses a redirect-based payment method.
email string
The Customer's email address.
If provided, this value overrides any values previously set using updateEmail.
phoneNumber string
The Customer's phone number.
If provided, this value overrides any values previously set using updatePhoneNumber.
billingAddress object
The Customer's billing address.
If provided, this value overrides any values previously set using updateBillingAddress.
Hide billingAddress properties
name optional string
address optional object
Hide address properties
country required string
line1 optional string
Address line 1 (e.g., street, PO Box, or company name).
line2 optional string
Address line 2 (e.g., apartment, suite, unit, or building).
city optional string
City, district, suburb, town, or village.
postal_code optional string
state optional string
State, county, province, or region.
shippingAddress object
The Customer's shipping address.
If provided, this value overrides any values previously set using updateShippingAddress.
Hide shippingAddress properties
name optional string
address optional object
Hide address properties
country required string
line1 required string
Address line 1 (e.g., street, PO Box, or company name).
line2 optional string
Address line 2 (e.g., apartment, suite, unit, or building).
city optional string
City, district, suburb, town, or village.
postal_code optional string
state optional string
State, county, province, or region.
This method returns a Promise that resolves with an object containing the following fields:
type: one of either "success" or "error"session: only populated when type is "success". Contains a Session instance representing the updated state.error: only populated when type is "error". Contains an object with a string message field which can be displayed to your customer.
Confirm the Checkout Session
Checkout
The Checkout object
Run a server update
checkout.runServerUpdate(userFunction)
Use this method to wrap an async function that makes a request to your server to update the Checkout Session.
Method parameters
userFunction required function
An async function to make a request to your server to update the Checkout Session.
This method returns a Promise that resolves with an object containing the following fields:
type: one of either "success" or "error"session: only populated when type is "success". Contains a Session instance representing the updated state.error: only populated when type is "error". Contains an object with a string message field which can be displayed to your customer.
Checkout
The Session object
The Session object
The Session object is a view of the Checkout Session API object and represents your customer's session on your checkout page.
Because data can change over the lifecycle of a session, avoid storing a reference to the Session object. Instead, call session() to retrieve the current value and listen to the change event to subscribe to updates.
Object Properties
id string
The ID of the Checkout Session.
billingAddress nullable object
Billing details of the Customer.
Hide billingAddress properties
name nullable string
address nullable object
Hide address properties
country string
line1 nullable string
Address line 1 (e.g., street, PO Box, or company name).
line2 nullable string
Address line 2 (e.g., apartment, suite, unit, or building).
city nullable string
City, district, suburb, town, or village.
postal_code nullable string
state nullable string
State, county, province, or region.
businessName nullable string
The business name as configured in the Business Public Details settings of your Stripe account.
canConfirm boolean
Whether the Checkout Session has collected enough data to confirm. Use this field to indicate to your customer if they can proceed, such as disabling the pay button.
currency enum
discountAmounts array of objects
The aggregate amounts calculated per discount for all line items.
Hide discountAmounts properties
amount string
A formatted string representing the discount amount, including currency symbols.
minorUnitsAmount integer
An integer representing the discount amount in the smallest currency unit (e.g., 100 cents to charge $1.00 or 100 to charge ¥100, a zero-decimal currency).
displayName string
A user-facing description of the discount.
promotionCode nullable string
The customer-facing promotion code that was used to apply this discount, if any.
recurring nullable object
Details of how the discount applies to recurring payments.
Hide recurring properties
type enum
One of forever or repeating.
forever: Applies to all charges from a subscription with this coupon applied.repeating: Applies to charges in the first durationInMonths months from a subscription with this coupon applied.
durationInMonths nullable integer
If duration is repeating, the number of months the coupon applies. Null otherwise.
percentOff nullable integer
An integer representing the discount amount as a percentage.
email nullable string
The Customer's email address.
lastPaymentError nullable object
The error encountered the last time the Checkout Session was confirmed.
Hide lastPaymentError properties
message string
An error message to be displayed to the customer.
lineItems array of objects
A list of items the customer is purchasing.
Hide lineItems properties
id string
Unique identifier for the object.
subtotal nullable object
Total before any discounts or exclusive taxes are applied.
Hide subtotal properties
amount string
A formatted string representing the subtotal amount, including currency symbols.
minorUnitsAmount integer
An integer representing the subtotal amount in the smallest currency unit (e.g., 100 cents to charge $1.00 or 100 to charge ¥100, a zero-decimal currency).
discount nullable object
Total discount amount. A positive number reduces the amount to be paid.
Hide discount properties
amount string
A formatted string representing the discount amount, including currency symbols.
minorUnitsAmount integer
An integer representing the discount amount in the smallest currency unit (e.g., 100 cents to charge $1.00 or 100 to charge ¥100, a zero-decimal currency).
taxExclusive nullable object
Total amount of exclusive tax (tax that is collected in addition to the subtotal).
Hide taxExclusive properties
amount string
A formatted string representing the exclusive tax amount, including currency symbols.
minorUnitsAmount integer
An integer representing the exclusive tax amount in the smallest currency unit (e.g., 100 cents to charge $1.00 or 100 to charge ¥100, a zero-decimal currency).
taxInclusive nullable object
Total amount of inclusive tax (tax that is already included in the subtotal).
Hide taxInclusive properties
amount string
A formatted string representing the inclusive tax amount, including currency symbols.
minorUnitsAmount integer
An integer representing the inclusive tax amount in the smallest currency unit (e.g., 100 cents to charge $1.00 or 100 to charge ¥100, a zero-decimal currency).
total nullable object
Total amount for this line item, including discounts and tax.
Hide total properties
amount string
A formatted string representing the total amount, including currency symbols.
minorUnitsAmount integer
An integer representing the total amount in the smallest currency unit (e.g., 100 cents to charge $1.00 or 100 to charge ¥100, a zero-decimal currency).
unitAmount nullable object
The amount representing the cost of a single unit of the item.
Hide unitAmount properties
amount string
A formatted string representing the unit amount, including currency symbols.
minorUnitsAmount integer
An integer representing the unit amount in the smallest currency unit (e.g., 100 cents to charge $1.00 or 100 to charge ¥100, a zero-decimal currency).
description optional string
An arbitrary string attached to the object. Often useful for displaying to users.
name string
The item's name, meant to be displayable to users.
images array of strings
An array of image URLs for the line item. Specify images on the Product when creating the Checkout Session.
quantity integer
The quantity of products being purchased.
discountAmounts array of objects
The amount of discount calculated per discount for this line item.
Hide discountAmounts properties
amount string
A formatted string representing the discount amount, including currency symbols.
minorUnitsAmount integer
An integer representing the discount amount in the smallest currency unit (e.g., 100 cents to charge $1.00 or 100 to charge ¥100, a zero-decimal currency).
displayName string
A user-facing description of the discount.
promotionCode nullable string
The customer-facing promotion code that was used to apply this discount, if any.
recurring nullable object
Details of how the discount applies to recurring payments.
Hide recurring properties
type enum
One of forever or repeating.
forever: Applies to all charges from a subscription with this coupon applied.repeating: Applies to charges in the first durationInMonths months from a subscription with this coupon applied.
durationInMonths nullable integer
If duration is repeating, the number of months the coupon applies. Null otherwise.
percentOff nullable integer
An integer representing the discount amount as a percentage.
taxAmounts nullable array of objects
The amount of tax calculated per tax rate for this line item.
Hide taxAmounts properties
amount string
A formatted string representing the tax amount, including currency symbols.
minorUnitsAmount integer
An integer representing the tax amount in the smallest currency unit (e.g., 100 cents to charge $1.00 or 100 to charge ¥100, a zero-decimal currency).
inclusive boolean
displayName string
A user-facing description of the tax.
recurring nullable object
The recurring components of a price such as interval and intervalCount.
Hide recurring properties
interval enum
Specifies billing frequency. Either day, week, month, or year.
intervalCount integer
The number of intervals between subscription billings. For example, interval=month and intervalCount=3 bills every 3 months.
usageType enum
One of licensed or metered. licensed automatically bills the quantity set when adding it to a subscription. metered aggregates the total usage based on usage records.
isProrated boolean
When true, the amount to be collected today is a prorated amount for a partial billing period, such as when using billing_cycle_anchor.
adjustableQuantity nullable object
Configuration for this item's quantity to be adjusted by the customer during checkout.
Hide adjustableQuantity properties
maximum integer
The maximum quantity the customer can purchase for the Checkout Session.
minimum integer
The minimum quantity the customer can purchase for the Checkout Session.
livemode boolean
Has the value true if the object exists in live mode or the value false if the object exists in test mode.
minorUnitsAmountDivisor integer
The factor used to convert between minor and major currency units.
This value represents the number of minor currency units per one major unit. For example, in USD, where cents are the minor unit, the divisor is 100. In JPY, which has no minor units, the divisor is 1.
phoneNumber nullable string
The Customer's phone number.
recurring object
Details about recurring payments set up by the Checkout Session.
Hide recurring properties
interval enum
Specifies billing frequency. Either day, week, month, or year.
intervalCount integer
The number of intervals between subscription billings. For example, interval=month and intervalCount=3 bills every 3 months.
dueNext object
Details about the next scheduled recurring payment.
Hide dueNext properties
subtotal nullable object
Total before any discounts or exclusive taxes are applied.
Hide subtotal properties
amount string
A formatted string representing the subtotal amount, including currency symbols.
minorUnitsAmount integer
An integer representing the subtotal amount in the smallest currency unit (e.g., 100 cents to charge $1.00 or 100 to charge ¥100, a zero-decimal currency).
discount nullable object
Total discount amount. A positive number reduces the amount to be paid.
Hide discount properties
amount string
A formatted string representing the discount amount, including currency symbols.
minorUnitsAmount integer
An integer representing the discount amount in the smallest currency unit (e.g., 100 cents to charge $1.00 or 100 to charge ¥100, a zero-decimal currency).
taxExclusive nullable object
Total amount of exclusive tax (tax that is collected in addition to the subtotal).
Hide taxExclusive properties
amount string
A formatted string representing the exclusive tax amount, including currency symbols.
minorUnitsAmount integer
An integer representing the exclusive tax amount in the smallest currency unit (e.g., 100 cents to charge $1.00 or 100 to charge ¥100, a zero-decimal currency).
taxInclusive nullable object
Total amount of inclusive tax (tax that is already included in the subtotal).
Hide taxInclusive properties
amount string
A formatted string representing the inclusive tax amount, including currency symbols.
minorUnitsAmount integer
An integer representing the inclusive tax amount in the smallest currency unit (e.g., 100 cents to charge $1.00 or 100 to charge ¥100, a zero-decimal currency).
billingCycleAnchor nullable integer
A future Unix timestamp to anchor the subscription's billing cycle. The anchor is the reference point that aligns future billing cycle dates. If not present, the subscription starts immediately.
trial nullable object
Details about a free trial, if there is one.
Hide trial properties
trialEnd integer
Unix timestamp representing the end of the trial period the customer will get before being charged for the first time.
trialPeriodDays integer
Integer representing the number of trial period days before the customer is charged for the first time.
savedPaymentMethods array of objects
An array of payment methods attached to the Customer.
Hide savedPaymentMethods properties
id string
ID of the PaymentMethod object
type enum
The type of the PaymentMethod
billingDetails object
Billing information associated with the PaymentMethod that may be used or required by particular types of payment methods.
Hide billingDetails properties
email nullable string
phone nullable string
Billing phone number (including extension).
name nullable string
address nullable object
Hide address properties
country string
line1 nullable string
Address line 1 (e.g., street, PO Box, or company name).
line2 nullable string
Address line 2 (e.g., apartment, suite, unit, or building).
city nullable string
City, district, suburb, town, or village.
postal_code nullable string
state nullable string
State, county, province, or region.
card object
If this is a card PaymentMethod, this hash contains the user's card details.
Hide card properties
brand string
The brand to use when displaying the card, this accounts for customer's brand choice on dual-branded cards. Can be american_express, cartes_bancaires, diners_club, discover, eftpos_australia, interac, jcb, mastercard, union_pay, visa, or other and may contain more values in the future.
expMonth integer
Two-digit number representing the card's expiration month.
expYear integer
Four-digit number representing the card's expiration year.
last4 string
The last four digits of the card.
shipping nullable object
The selected shipping option, if any.
Hide shipping properties
shippingOption object
Details of the selected shipping option.
Hide shippingOption properties
id string
Unique identifier for the object.
amount string
A formatted string representing the shipping amount, including currency symbols.
minorUnitsAmount integer
An integer representing the shipping amount in the smallest currency unit (e.g., 100 cents to charge $1.00 or 100 to charge ¥100, a zero-decimal currency).
currency string
displayName nullable string
A user-facing description of the shipping option.
deliveryEstimate nullable object
The estimated range for how long shipping will take.
Hide deliveryEstimate properties
maximum nullable object
The upper bound of the estimated range. If empty, represents no upper bound i.e., infinite.
Hide maximum properties
unit string
A unit of time. Either business_day, day, hour, week, or month.
value integer
minimum nullable object
The lower bound of the estimated range. If empty, represents no lower bound.
Hide minimum properties
unit string
A unit of time. Either business_day, day, hour, week, or month.
value integer
taxAmounts array of objects
The amount of tax calculated per tax rate for shipping costs.
Hide taxAmounts properties
amount string
A formatted string representing the tax amount, including currency symbols.
minorUnitsAmount integer
An integer representing the tax amount in the smallest currency unit (e.g., 100 cents to charge $1.00 or 100 to charge ¥100, a zero-decimal currency).
inclusive boolean
displayName string
A user-facing description of the tax.
shippingAddress nullable object
Shipping address of the Customer.
Hide shippingAddress properties
name nullable string
address nullable object
Hide address properties
country string
line1 string
Address line 1 (e.g., street, PO Box, or company name).
line2 nullable string
Address line 2 (e.g., apartment, suite, unit, or building).
city nullable string
City, district, suburb, town, or village.
postal_code nullable string
state nullable string
State, county, province, or region.
shippingOptions array of objects
The list of shipping options that can be selected.
Hide shippingOptions properties
id string
Unique identifier for the object.
amount string
A formatted string representing the shipping amount, including currency symbols.
minorUnitsAmount integer
An integer representing the shipping amount in the smallest currency unit (e.g., 100 cents to charge $1.00 or 100 to charge ¥100, a zero-decimal currency).
currency string
displayName nullable string
A user-facing description of the shipping option.
deliveryEstimate nullable object
The estimated range for how long shipping will take.
Hide deliveryEstimate properties
maximum nullable object
The upper bound of the estimated range. If empty, represents no upper bound i.e., infinite.
Hide maximum properties
unit string
A unit of time. Either business_day, day, hour, week, or month.
value integer
minimum nullable object
The lower bound of the estimated range. If empty, represents no lower bound.
Hide minimum properties
unit string
A unit of time. Either business_day, day, hour, week, or month.
value integer
status object
Status of the Checkout Session.
Hide status properties
type enum
One of open, expired, or complete.
open: The Checkout Session is still in progress.expired: The Checkout Session has expired. No further processing will occur.complete: The Checkout Session is complete. Payment processing may still be in progress.
paymentStatus nullable enum
One of paid, unpaid, or no_payment_required. Only present when type=complete.
paid: The payment funds are available in your account.unpaid: The payment funds are not yet available in your account.no_payment_requried: The payment is delayed to a future date, or the Checkout Session is in setup mode and doesn't require a payment at this time.
tax object
Details about the tax computation status.
Hide tax properties
status enum
One of ready, requires_shipping_address, or requires_billing_address.
ready: The final tax amount is computed, and the session is ready for confirmation.requires_shipping_address: A shipping address must be provided to calculate tax.requires_billing_address: A billing address must be provided to calculate tax.
taxAmounts nullable array of objects
The aggregate amounts calculated per tax rate for all line items. This value is null if tax has not yet been computed, i.e. the Customer's address has not been collected yet.
Hide taxAmounts properties
amount string
A formatted string representing the tax amount, including currency symbols.
minorUnitsAmount integer
An integer representing the tax amount in the smallest currency unit (e.g., 100 cents to charge $1.00 or 100 to charge ¥100, a zero-decimal currency).
inclusive boolean
displayName string
A user-facing description of the tax.
total object
Tax and discount details for the computed total amount. Use this field to render an amount breakdown to your customer, such as in an order summary.
Hide total properties
subtotal object
The total amount of line items, excluding tax, discounts, and shipping.
Hide subtotal properties
amount string
A formatted string representing the subtotal amount, including currency symbols.
minorUnitsAmount integer
An integer representing the subtotal amount in the smallest currency unit (e.g., 100 cents to charge $1.00 or 100 to charge ¥100, a zero-decimal currency).
taxExclusive object
Hide taxExclusive properties
amount string
A formatted string representing the exclusive tax amount, including currency symbols.
minorUnitsAmount integer
An integer representing the exclusive tax amount in the smallest currency unit (e.g., 100 cents to charge $1.00 or 100 to charge ¥100, a zero-decimal currency).
taxInclusive object
Hide taxInclusive properties
amount string
A formatted string representing the inclusive tax amount, including currency symbols.
minorUnitsAmount integer
An integer representing the inclusive tax amount in the smallest currency unit (e.g., 100 cents to charge $1.00 or 100 to charge ¥100, a zero-decimal currency).
shippingRate object
The sum of all shipping amounts.
Hide shippingRate properties
amount string
A formatted string representing the total shipping amount, including currency symbols.
minorUnitsAmount integer
An integer representing the total shipping amount in the smallest currency unit (e.g., 100 cents to charge $1.00 or 100 to charge ¥100, a zero-decimal currency).
discount object
The sum of all the discounts. A positive number reduces the amount to be paid.
Hide discount properties
amount string
A formatted string representing the discount amount, including currency symbols.
minorUnitsAmount integer
An integer representing the discount amount in the smallest currency unit (e.g., 100 cents to charge $1.00 or 100 to charge ¥100, a zero-decimal currency).
total object
Total computed amount, including discounts and tax.
Hide total properties
amount string
A formatted string representing the total amount, including currency symbols.
minorUnitsAmount integer
An integer representing the total amount in the smallest currency unit (e.g., 100 cents to charge $1.00 or 100 to charge ¥100, a zero-decimal currency).
appliedBalance object
Total amount of customer credit balance to be applied to the payment. A positive number increases the amount to be paid, and a negative number decreases the amount to be paid.
Hide appliedBalance properties
amount string
A formatted string representing the applied customer balance amount, including currency symbols.
minorUnitsAmount integer
An integer representing the applied customer balance amount in the smallest currency unit (e.g., 100 cents to charge $1.00 or 100 to charge ¥100, a zero-decimal currency).
balanceAppliedToNextInvoice boolean
When true, no payment will be collected immediately. Instead, the amount due will be added to the Customer's next invoice. This can happen when the amount due today is less than the minimum chargeable amount.
Checkout
Listen to Checkout events
Checkout events
Listen to Checkout events to respond to changes caused by customer actions on your checkout page.
Checkout
Listen to Checkout events
Change event
checkout.on('change',handler)
The change event is triggered when Checkout Session data changes, such as when the customer changes their shipping address. The event payload is always a Checkout Session object.
Method parameters
event required 'change'
The name of the event. In this case, change.
handler required function
handler(session) => void is a callback function that you provide that will be called when the event is fired. When called it will be passed a Checkout Session object.
Checkout
Elements methods
Use Elements with Custom Checkout
Stripe Elements are customizable UI components you can use to build your checkout page.
Use the Custom Checkout instance to create and manage Elements.
Checkout
Elements methods
Create a Payment Element
checkout.createPaymentElement(options?)
This method creates an instance of a Payment Element.
Method parameters
options optional object
Payment Element initialization options.
Hide options properties
fields object
By default, the Payment Element will collect only the necessary billing details to complete a payment.
If you intend to collect billing details fields outside of the Payment Element, you can disable Payment Element collection of certain fields with the fields option.
Hide fields properties
billingDetails 'never' | 'auto' | object
Specify never to avoid collecting all billing details in the Payment Element. If you would like to disable only certain billing details, pass an object specifying which fields you would like to disable collection for. The default setting for each field or object is auto.
Hide billingDetails properties
name 'never' | 'auto'
email 'never' | 'auto'
phone 'never' | 'auto'
address 'never' | 'if_required' | 'auto' | object
Specify if_required to collect only billing address fields required to complete the payment. You can omit and hide optional address fields in the card form, such as country and postal code. This differs from the never option, where you don't need to include fields omitted in the Payment Element when confirming the payment. Use if_required to collect only the minimum address information required for the payment method. This can reduce the amount of information required to complete the form.
Disabling address collection can negatively impact authorization rates and network fees for users on a network cost plus pricing plan.
Hide address properties
line1 'never' | 'auto'
line2 'never' | 'auto'
city 'never' | 'auto'
The name of a city, town, village, etc.
state 'never' | 'auto'
The most coarse subdivision of a country. Depending on the country, this might correspond to a state, a province, an oblast, a prefecture, or something else along these lines.
country 'never' | 'auto'
Two-letter country code, capitalized. Valid two-letter country codes are specified by ISO3166 alpha-2.
postalCode 'never' | 'auto'
The postal code or ZIP code, also known as PIN code in India.
layout 'accordion' | 'tabs' | object
Specify the layout for the Payment Element. If you only pass a layout type ('accordion' or ‘tabs’) without any additional parameters, the Payment Element renders using that layout and the default values associated with it.
An object can also be passed to specify the layout with additional configuration.
Hide layout properties
type required 'accordion' | 'tabs'
Defines the layout to render the Payment Element.
defaultCollapsed boolean
Controls if the Payment Element renders in a collapsed state (where no payment method is selected by default). When you leave this undefined, Stripe renders the experience that it determines will have the best conversion.
radios boolean
Renders each Payment Method with a radio input next to its logo. The radios visually indicate the current selection of the Payment Element.
This property is only applicable to the accordion layout.
spacedAccordionItems boolean
When true, the Payment Methods render as standalone buttons with space in between them.
This property is only applicable to the accordion layout.
visibleAccordionItemsCount number
Sets the max number of Payment Methods visible before using the "More" button to hide additional Payment Methods. Set this value to 0 to disable the "More" button and render all available Payment Methods. Default is 5.
This property is only applicable to the accordion layout.
paymentMethodOrder array
By default, the Payment Element will use a dynamic ordering that optimizes payment method display for each user.
You can override the default order in which payment methods are displayed in the Payment Element with a list of payment method types.
If the associated Checkout Session has payment method types not specified in paymentMethodOrder, they will be displayed after the payment methods you specify. If you specify payment method types not on the associated PaymentIntent, they will be ignored.
readOnly boolean
Applies a read-only state to the Payment Element so that payment details can’t be changed. Default is false.
Enabling the readOnly option doesn't change the Payment Element's visual appearance. If you want to adjust the way the Payment Element looks, use the Appearance API.
terms object
Control how mandates or other legal agreements are displayed in the Payment Element. Use never to never display legal agreements. The default setting is auto, which causes legal agreements to only be shown when necessary.
Hide terms properties
applePay 'auto' | 'always' | 'never'
auBecsDebit 'auto' | 'always' | 'never'
bancontact 'auto' | 'always' | 'never'
card 'auto' | 'always' | 'never'
cashapp 'auto' | 'always' | 'never'
googlePay 'auto' | 'always' | 'never'
ideal 'auto' | 'always' | 'never'
paypal 'auto' | 'always' | 'never'
sepaDebit 'auto' | 'always' | 'never'
sofort 'auto' | 'always' | 'never'
usBankAccount 'auto' | 'always' | 'never'
This method returns the newly created Payment Element instance.
Checkout
Elements methods
Create a Billing Address Element
checkout.createBillingAddressElement(options?)
This method creates an instance of a Billing Address Element.
Method parameters
options optional object
Billing Address Element initialization options.
Hide options properties
contacts array
An array of Contact objects that can be displayed as saved addresses in the Billing Address Element. The first contact is automatically selected.
display object
You can customize how certain fields are displayed.
Hide display properties
name 'full' | 'split' | 'organization'
By default, the Billing Address Element displays a full name field. Specify 'split' to display a first name field and a last name field. Specify 'organization' to display an organization field.
This method returns the newly created Billing Address Element instance.
Create a Billing Address Element
Checkout
Elements methods
Create a Shipping Address Element
checkout.createShippingAddressElement(options?)
This method creates an instance of a Shipping Address Element.
Method parameters
options optional object
Shipping Address Element initialization options.
Hide options properties
contacts array
An array of Contact objects that can be displayed as saved addresses in the Shipping Address Element. The first contact is automatically selected.
display object
You can customize how certain fields are displayed.
Hide display properties
name 'full' | 'split' | 'organization'
By default, the Shipping Address Element displays a full name field. Specify 'split' to display a first name field and a last name field. Specify 'organization' to display an organization field.
This method returns the newly created Shipping Address Element instance.
Create a Shipping Address Element
Checkout
Elements methods
Create an Express Checkout Element
checkout.createExpressCheckoutElement(options?)
This method creates an instance of an Express Checkout Element.
Method parameters
options optional object
Express Checkout Element initialization options.
Hide options properties
buttonHeight number
By default, the height of the buttons are 44px.
You can override this to specify a custom button height in the range of 40px-55px.
buttonTheme object
Specify the preferred button theme to use. By default, Elements determines the themes based on the specified appearance option.
Hide buttonTheme properties
applePay 'black' | 'white' | 'white-outline'
googlePay 'black' | 'white'
paypal 'gold' | 'blue' | 'silver' | 'white' | 'black'
klarna 'dark' | 'light' | 'outlined'
buttonType object
Specify the preferred button type to display.
Hide buttonType properties
applePay 'add-money' | 'book' | 'buy' | 'check-out' | 'contribute' | 'donate' | 'order' | 'plain' | 'reload' | 'rent' | 'subscribe' | 'support' | 'tip' | 'top-up'
googlePay 'book' | 'buy' | 'checkout' | 'donate' | 'order' | 'pay' | 'plain' | 'subscribe'
paypal 'paypal' | 'checkout' | 'buynow' | 'pay'
klarna 'continue' | 'pay'
layout object
Specify how the buttons are arranged in a grid-like layout in the Express Checkout Element. Elements determines the layout by using certain factors, such as available space, number of buttons, and the defined layout object.
Hide layout properties
maxColumns number
Defines the maximum number of columns the Express Checkout Element can use to render. Default is 0, meaning unlimited.
maxRows number
Defines the maximum number of rows the Express Checkout Element can use to render. Default is 0, meaning unlimited.
overflow 'auto' | 'never'
Specify whether or not to always hide the overflow menu or allow Elements to determine when to show the overflow menu. Default is auto. You can't specify both overflow: 'never' and set maxRows to a number greater than 0.
paymentMethodOrder array
By default, the Express Checkout Element uses a dynamic ordering that optimizes payment method display for each user.
You can override the default order in which payment methods display in the Express Checkout Element with a list of payment method types.
If there are payment methods that will show that are not specified in paymentMethodOrder, they display after the payment methods you specify. If you specify payment methods that will not show, they are ignored.
paymentMethods object
Besides your Dashboard configuration, the availability of payment methods in the Express Checkout Element is influenced by the CheckoutSession configuration. By default, it displays all available payment methods based on both configurations. When setting the paymentMethods option, the Express Checkout Element merges your specified options with the default logic to determine the final set of payment methods displayed.
Hide paymentMethods properties
amazonPay 'auto' | 'never'
applePay 'always' | 'auto' | 'never'
Apple Pay has additional configurations that determine when Stripe can show it. By default, Apple Pay shows when the customer is using a supported platform and when we determine it's advantageous for your conversion. This is the auto behavior. If you want to always show Apple Pay when the customer is using a supported platform, you can set its property in paymentMethods to always.
googlePay 'always' | 'auto' | 'never'
Google Pay has additional configurations that determine when Stripe can show it. By default, Google Pay shows when the customer is using a supported platform and when we determine it's advantageous for your conversion. This is the auto behavior. If you want to always show Google Pay when the customer is using a supported platform, you can set its property in paymentMethods to always.
link 'auto' | 'never'
paypal 'auto' | 'never'
This method returns the newly created Express Checkout Element instance.
Create an Express Checkout Element
Checkout
Elements methods
Get the Payment Element
checkout.getPaymentElement()
This method gets the previously created Payment Element instance, if it exists.
getPaymentElement() returns one of the following:
- The Payment Element instance.
null, when no Payment Element has been created.
Checkout
Elements methods
Get the Billing Address Element
checkout.getBillingAddressElement()
This method gets the previously created Billing Address Element instance, if it exists.
getBillingAddressElement() returns one of the following:
- The Billing Address Element instance.
null, when no Billing Address Element has been created.
Get the Billing Address Element
Checkout
Elements methods
Get the Shipping Address Element
checkout.getShippingAddressElement()
This method gets the previously created Shipping Address Element instance, if it exists.
getShippingAddressElement() returns one of the following:
- The Shipping Address Element instance.
null, when no Shipping Address Element has been created.
Get the Shipping Address Element
Checkout
Elements methods
Get the Express Checkout Element
checkout.getExpressCheckoutElement()
This method gets the previously created Express Checkout Element instance, if it exists.
getExpressCheckoutElement() returns one of the following:
- The Express Checkout Element instance.
null, when no Express Checkout Element has been created.
Get the Express Checkout Address Element
Checkout
Elements methods
Update Elements appearance
checkout.changeAppearance(appearance)
Change the visual customization of Elements created with Custom Checkout using the Appearance API
Method parameters
appearance required object
Match the design of your site with the appearance option. The layout of each Element stays consistent, but you can modify colors, fonts, borders, padding, and more.
Change the visual customization of Elements
Checkout (React)
Introduction
Elements with Checkout Sessions API (React)
Build an online checkout page using Stripe Elements and the Checkout Sessions API.
See build a checkout page for steps on using Elements with the Checkout Sessions API.
The following components and functions are available in react-stripe-js to use as part of your integration.
Checkout (React)
CheckoutProvider
CheckoutProvider
The CheckoutProvider component allows you to use Element components and access data from your Checkout Session in any nested component. Render a CheckoutProvider at the root of your React app so that it is available everywhere you need it.
To use CheckoutProvider, call loadStripe from @stripe/stripe-js with your publishable key. The loadStripe function asynchronously loads the Stripe.js script and initializes a Stripe object. Pass the returned Promise to CheckoutProvider along with the client secret of your Checkout Session.
Props
stripe required `Stripe` or `Promise<Stripe>`
A Stripe object or a Promise resolving to a Stripe object. The easiest way to initialize a Stripe object is with the Stripe.js wrapper module. After this prop has been set, it can not be changed.
options required object
Options for CheckoutProvider.
Hide options properties
fetchClientSecret required string
A function that retrieves the Checkout Session client secret from the server. This function should return a Promise resolving to a string client secret.
elementsOptions object
Hide elementsOptions properties
appearance object
Match the design of your site with the appearance option. The layout of each Element stays consistent, but you can modify colors, fonts, borders, padding, and more.
loader 'auto' | 'always' | 'never'
Display skeleton loader UI while waiting for Elements to fully load after they're mounted. Default is 'auto' (Stripe determines whether or not to show a loader UI).
fonts array
An array of custom fonts that elements created from the Elements object can use. You can specify fonts as CssFontSource or CustomFontSource objects.
Checkout (React)
useCheckout hook
useCheckout hook
The useCheckout hook returns an object containing Checkout Session data as well as functions to update the Checkout Session.
Object properties
id string
The ID of the Checkout Session.
billingAddress nullable object
Billing details of the Customer.
Hide billingAddress properties
name nullable string
address nullable object
Hide address properties
country string
line1 nullable string
Address line 1 (e.g., street, PO Box, or company name).
line2 nullable string
Address line 2 (e.g., apartment, suite, unit, or building).
city nullable string
City, district, suburb, town, or village.
postal_code nullable string
state nullable string
State, county, province, or region.
businessName nullable string
The business name as configured in the Business Public Details settings of your Stripe account.
canConfirm boolean
Whether the Checkout Session has collected enough data to confirm. Use this field to indicate to your customer if they can proceed, such as disabling the pay button.
currency enum
discountAmounts array of objects
The aggregate amounts calculated per discount for all line items.
Hide discountAmounts properties
amount string
A formatted string representing the discount amount, including currency symbols.
minorUnitsAmount integer
An integer representing the discount amount in the smallest currency unit (e.g., 100 cents to charge $1.00 or 100 to charge ¥100, a zero-decimal currency).
displayName string
A user-facing description of the discount.
promotionCode nullable string
The customer-facing promotion code that was used to apply this discount, if any.
recurring nullable object
Details of how the discount applies to recurring payments.
Hide recurring properties
type enum
One of forever or repeating.
forever: Applies to all charges from a subscription with this coupon applied.repeating: Applies to charges in the first durationInMonths months from a subscription with this coupon applied.
durationInMonths nullable integer
If duration is repeating, the number of months the coupon applies. Null otherwise.
percentOff nullable integer
An integer representing the discount amount as a percentage.
email nullable string
The Customer's email address.
lastPaymentError nullable object
The error encountered the last time the Checkout Session was confirmed.
Hide lastPaymentError properties
message string
An error message to be displayed to the customer.
lineItems array of objects
A list of items the customer is purchasing.
Hide lineItems properties
id string
Unique identifier for the object.
subtotal nullable object
Total before any discounts or exclusive taxes are applied.
Hide subtotal properties
amount string
A formatted string representing the subtotal amount, including currency symbols.
minorUnitsAmount integer
An integer representing the subtotal amount in the smallest currency unit (e.g., 100 cents to charge $1.00 or 100 to charge ¥100, a zero-decimal currency).
discount nullable object
Total discount amount. A positive number reduces the amount to be paid.
Hide discount properties
amount string
A formatted string representing the discount amount, including currency symbols.
minorUnitsAmount integer
An integer representing the discount amount in the smallest currency unit (e.g., 100 cents to charge $1.00 or 100 to charge ¥100, a zero-decimal currency).
taxExclusive nullable object
Total amount of exclusive tax (tax that is collected in addition to the subtotal).
Hide taxExclusive properties
amount string
A formatted string representing the exclusive tax amount, including currency symbols.
minorUnitsAmount integer
An integer representing the exclusive tax amount in the smallest currency unit (e.g., 100 cents to charge $1.00 or 100 to charge ¥100, a zero-decimal currency).
taxInclusive nullable object
Total amount of inclusive tax (tax that is already included in the subtotal).
Hide taxInclusive properties
amount string
A formatted string representing the inclusive tax amount, including currency symbols.
minorUnitsAmount integer
An integer representing the inclusive tax amount in the smallest currency unit (e.g., 100 cents to charge $1.00 or 100 to charge ¥100, a zero-decimal currency).
total nullable object
Total amount for this line item, including discounts and tax.
Hide total properties
amount string
A formatted string representing the total amount, including currency symbols.
minorUnitsAmount integer
An integer representing the total amount in the smallest currency unit (e.g., 100 cents to charge $1.00 or 100 to charge ¥100, a zero-decimal currency).
unitAmount nullable object
The amount representing the cost of a single unit of the item.
Hide unitAmount properties
amount string
A formatted string representing the unit amount, including currency symbols.
minorUnitsAmount integer
An integer representing the unit amount in the smallest currency unit (e.g., 100 cents to charge $1.00 or 100 to charge ¥100, a zero-decimal currency).
description optional string
An arbitrary string attached to the object. Often useful for displaying to users.
name string
The item's name, meant to be displayable to users.
images array of strings
An array of image URLs for the line item. Specify images on the Product when creating the Checkout Session.
quantity integer
The quantity of products being purchased.
discountAmounts array of objects
The amount of discount calculated per discount for this line item.
Hide discountAmounts properties
amount string
A formatted string representing the discount amount, including currency symbols.
minorUnitsAmount integer
An integer representing the discount amount in the smallest currency unit (e.g., 100 cents to charge $1.00 or 100 to charge ¥100, a zero-decimal currency).
displayName string
A user-facing description of the discount.
promotionCode nullable string
The customer-facing promotion code that was used to apply this discount, if any.
recurring nullable object
Details of how the discount applies to recurring payments.
Hide recurring properties
type enum
One of forever or repeating.
forever: Applies to all charges from a subscription with this coupon applied.repeating: Applies to charges in the first durationInMonths months from a subscription with this coupon applied.
durationInMonths nullable integer
If duration is repeating, the number of months the coupon applies. Null otherwise.
percentOff nullable integer
An integer representing the discount amount as a percentage.
taxAmounts nullable array of objects
The amount of tax calculated per tax rate for this line item.
Hide taxAmounts properties
amount string
A formatted string representing the tax amount, including currency symbols.
minorUnitsAmount integer
An integer representing the tax amount in the smallest currency unit (e.g., 100 cents to charge $1.00 or 100 to charge ¥100, a zero-decimal currency).
inclusive boolean
displayName string
A user-facing description of the tax.
recurring nullable object
The recurring components of a price such as interval and intervalCount.
Hide recurring properties
interval enum
Specifies billing frequency. Either day, week, month, or year.
intervalCount integer
The number of intervals between subscription billings. For example, interval=month and intervalCount=3 bills every 3 months.
usageType enum
One of licensed or metered. licensed automatically bills the quantity set when adding it to a subscription. metered aggregates the total usage based on usage records.
isProrated boolean
When true, the amount to be collected today is a prorated amount for a partial billing period, such as when using billing_cycle_anchor.
adjustableQuantity nullable object
Configuration for this item's quantity to be adjusted by the customer during checkout.
Hide adjustableQuantity properties
maximum integer
The maximum quantity the customer can purchase for the Checkout Session.
minimum integer
The minimum quantity the customer can purchase for the Checkout Session.
livemode boolean
Has the value true if the object exists in live mode or the value false if the object exists in test mode.
minorUnitsAmountDivisor integer
The factor used to convert between minor and major currency units.
This value represents the number of minor currency units per one major unit. For example, in USD, where cents are the minor unit, the divisor is 100. In JPY, which has no minor units, the divisor is 1.
phoneNumber nullable string
The Customer's phone number.
recurring object
Details about recurring payments set up by the Checkout Session.
Hide recurring properties
interval enum
Specifies billing frequency. Either day, week, month, or year.
intervalCount integer
The number of intervals between subscription billings. For example, interval=month and intervalCount=3 bills every 3 months.
dueNext object
Details about the next scheduled recurring payment.
Hide dueNext properties
subtotal nullable object
Total before any discounts or exclusive taxes are applied.
Hide subtotal properties
amount string
A formatted string representing the subtotal amount, including currency symbols.
minorUnitsAmount integer
An integer representing the subtotal amount in the smallest currency unit (e.g., 100 cents to charge $1.00 or 100 to charge ¥100, a zero-decimal currency).
discount nullable object
Total discount amount. A positive number reduces the amount to be paid.
Hide discount properties
amount string
A formatted string representing the discount amount, including currency symbols.
minorUnitsAmount integer
An integer representing the discount amount in the smallest currency unit (e.g., 100 cents to charge $1.00 or 100 to charge ¥100, a zero-decimal currency).
taxExclusive nullable object
Total amount of exclusive tax (tax that is collected in addition to the subtotal).
Hide taxExclusive properties
amount string
A formatted string representing the exclusive tax amount, including currency symbols.
minorUnitsAmount integer
An integer representing the exclusive tax amount in the smallest currency unit (e.g., 100 cents to charge $1.00 or 100 to charge ¥100, a zero-decimal currency).
taxInclusive nullable object
Total amount of inclusive tax (tax that is already included in the subtotal).
Hide taxInclusive properties
amount string
A formatted string representing the inclusive tax amount, including currency symbols.
minorUnitsAmount integer
An integer representing the inclusive tax amount in the smallest currency unit (e.g., 100 cents to charge $1.00 or 100 to charge ¥100, a zero-decimal currency).
billingCycleAnchor nullable integer
A future Unix timestamp to anchor the subscription's billing cycle. The anchor is the reference point that aligns future billing cycle dates. If not present, the subscription starts immediately.
trial nullable object
Details about a free trial, if there is one.
Hide trial properties
trialEnd integer
Unix timestamp representing the end of the trial period the customer will get before being charged for the first time.
trialPeriodDays integer
Integer representing the number of trial period days before the customer is charged for the first time.
savedPaymentMethods array of objects
An array of payment methods attached to the Customer.
Hide savedPaymentMethods properties
id string
ID of the PaymentMethod object
type enum
The type of the PaymentMethod
billingDetails object
Billing information associated with the PaymentMethod that may be used or required by particular types of payment methods.
Hide billingDetails properties
email nullable string
phone nullable string
Billing phone number (including extension).
name nullable string
address nullable object
Hide address properties
country string
line1 nullable string
Address line 1 (e.g., street, PO Box, or company name).
line2 nullable string
Address line 2 (e.g., apartment, suite, unit, or building).
city nullable string
City, district, suburb, town, or village.
postal_code nullable string
state nullable string
State, county, province, or region.
card object
If this is a card PaymentMethod, this hash contains the user's card details.
Hide card properties
brand string
The brand to use when displaying the card, this accounts for customer's brand choice on dual-branded cards. Can be american_express, cartes_bancaires, diners_club, discover, eftpos_australia, interac, jcb, mastercard, union_pay, visa, or other and may contain more values in the future.
expMonth integer
Two-digit number representing the card's expiration month.
expYear integer
Four-digit number representing the card's expiration year.
last4 string
The last four digits of the card.
shipping nullable object
The selected shipping option, if any.
Hide shipping properties
shippingOption object
Details of the selected shipping option.
Hide shippingOption properties
id string
Unique identifier for the object.
amount string
A formatted string representing the shipping amount, including currency symbols.
minorUnitsAmount integer
An integer representing the shipping amount in the smallest currency unit (e.g., 100 cents to charge $1.00 or 100 to charge ¥100, a zero-decimal currency).
currency string
displayName nullable string
A user-facing description of the shipping option.
deliveryEstimate nullable object
The estimated range for how long shipping will take.
Hide deliveryEstimate properties
maximum nullable object
The upper bound of the estimated range. If empty, represents no upper bound i.e., infinite.
Hide maximum properties
unit string
A unit of time. Either business_day, day, hour, week, or month.
value integer
minimum nullable object
The lower bound of the estimated range. If empty, represents no lower bound.
Hide minimum properties
unit string
A unit of time. Either business_day, day, hour, week, or month.
value integer
taxAmounts array of objects
The amount of tax calculated per tax rate for shipping costs.
Hide taxAmounts properties
amount string
A formatted string representing the tax amount, including currency symbols.
minorUnitsAmount integer
An integer representing the tax amount in the smallest currency unit (e.g., 100 cents to charge $1.00 or 100 to charge ¥100, a zero-decimal currency).
inclusive boolean
displayName string
A user-facing description of the tax.
shippingAddress nullable object
Shipping address of the Customer.
Hide shippingAddress properties
name nullable string
address nullable object
Hide address properties
country string
line1 string
Address line 1 (e.g., street, PO Box, or company name).
line2 nullable string
Address line 2 (e.g., apartment, suite, unit, or building).
city nullable string
City, district, suburb, town, or village.
postal_code nullable string
state nullable string
State, county, province, or region.
shippingOptions array of objects
The list of shipping options that can be selected.
Hide shippingOptions properties
id string
Unique identifier for the object.
amount string
A formatted string representing the shipping amount, including currency symbols.
minorUnitsAmount integer
An integer representing the shipping amount in the smallest currency unit (e.g., 100 cents to charge $1.00 or 100 to charge ¥100, a zero-decimal currency).
currency string
displayName nullable string
A user-facing description of the shipping option.
deliveryEstimate nullable object
The estimated range for how long shipping will take.
Hide deliveryEstimate properties
maximum nullable object
The upper bound of the estimated range. If empty, represents no upper bound i.e., infinite.
Hide maximum properties
unit string
A unit of time. Either business_day, day, hour, week, or month.
value integer
minimum nullable object
The lower bound of the estimated range. If empty, represents no lower bound.
Hide minimum properties
unit string
A unit of time. Either business_day, day, hour, week, or month.
value integer
status object
Status of the Checkout Session.
Hide status properties
type enum
One of open, expired, or complete.
open: The Checkout Session is still in progress.expired: The Checkout Session has expired. No further processing will occur.complete: The Checkout Session is complete. Payment processing may still be in progress.
paymentStatus nullable enum
One of paid, unpaid, or no_payment_required. Only present when type=complete.
paid: The payment funds are available in your account.unpaid: The payment funds are not yet available in your account.no_payment_requried: The payment is delayed to a future date, or the Checkout Session is in setup mode and doesn't require a payment at this time.
tax object
Details about the tax computation status.
Hide tax properties
status enum
One of ready, requires_shipping_address, or requires_billing_address.
ready: The final tax amount is computed, and the session is ready for confirmation.requires_shipping_address: A shipping address must be provided to calculate tax.requires_billing_address: A billing address must be provided to calculate tax.
taxAmounts nullable array of objects
The aggregate amounts calculated per tax rate for all line items. This value is null if tax has not yet been computed, i.e. the Customer's address has not been collected yet.
Hide taxAmounts properties
amount string
A formatted string representing the tax amount, including currency symbols.
minorUnitsAmount integer
An integer representing the tax amount in the smallest currency unit (e.g., 100 cents to charge $1.00 or 100 to charge ¥100, a zero-decimal currency).
inclusive boolean
displayName string
A user-facing description of the tax.
total object
Tax and discount details for the computed total amount. Use this field to render an amount breakdown to your customer, such as in an order summary.
Hide total properties
subtotal object
The total amount of line items, excluding tax, discounts, and shipping.
Hide subtotal properties
amount string
A formatted string representing the subtotal amount, including currency symbols.
minorUnitsAmount integer
An integer representing the subtotal amount in the smallest currency unit (e.g., 100 cents to charge $1.00 or 100 to charge ¥100, a zero-decimal currency).
taxExclusive object
Hide taxExclusive properties
amount string
A formatted string representing the exclusive tax amount, including currency symbols.
minorUnitsAmount integer
An integer representing the exclusive tax amount in the smallest currency unit (e.g., 100 cents to charge $1.00 or 100 to charge ¥100, a zero-decimal currency).
taxInclusive object
Hide taxInclusive properties
amount string
A formatted string representing the inclusive tax amount, including currency symbols.
minorUnitsAmount integer
An integer representing the inclusive tax amount in the smallest currency unit (e.g., 100 cents to charge $1.00 or 100 to charge ¥100, a zero-decimal currency).
shippingRate object
The sum of all shipping amounts.
Hide shippingRate properties
amount string
A formatted string representing the total shipping amount, including currency symbols.
minorUnitsAmount integer
An integer representing the total shipping amount in the smallest currency unit (e.g., 100 cents to charge $1.00 or 100 to charge ¥100, a zero-decimal currency).
discount object
The sum of all the discounts. A positive number reduces the amount to be paid.
Hide discount properties
amount string
A formatted string representing the discount amount, including currency symbols.
minorUnitsAmount integer
An integer representing the discount amount in the smallest currency unit (e.g., 100 cents to charge $1.00 or 100 to charge ¥100, a zero-decimal currency).
total object
Total computed amount, including discounts and tax.
Hide total properties
amount string
A formatted string representing the total amount, including currency symbols.
minorUnitsAmount integer
An integer representing the total amount in the smallest currency unit (e.g., 100 cents to charge $1.00 or 100 to charge ¥100, a zero-decimal currency).
appliedBalance object
Total amount of customer credit balance to be applied to the payment. A positive number increases the amount to be paid, and a negative number decreases the amount to be paid.
Hide appliedBalance properties
amount string
A formatted string representing the applied customer balance amount, including currency symbols.
minorUnitsAmount integer
An integer representing the applied customer balance amount in the smallest currency unit (e.g., 100 cents to charge $1.00 or 100 to charge ¥100, a zero-decimal currency).
balanceAppliedToNextInvoice boolean
When true, no payment will be collected immediately. Instead, the amount due will be added to the Customer's next invoice. This can happen when the amount due today is less than the minimum chargeable amount.
Checkout (React)
useCheckout hook
Update the customer's shipping address
updateShippingAddress(shippingAddress)
Use this method to update the Customer's shipping address.
Method parameters
shippingAddress required nullable object
New shipping address for the Customer.
Hide shippingAddress properties
name optional string
address optional object
Hide address properties
country required string
line1 required string
Address line 1 (e.g., street, PO Box, or company name).
line2 optional string
Address line 2 (e.g., apartment, suite, unit, or building).
city optional string
City, district, suburb, town, or village.
postal_code optional string
state optional string
State, county, province, or region.
This method returns a Promise that resolves with an object containing the following fields:
type: one of either "success" or "error"session: only populated when type is "success". Contains a Session instance representing the updated state.error: only populated when type is "error". Contains an object with a string message field which can be displayed to your customer.
Update the Customer's shipping address
Checkout (React)
useCheckout hook
Update the customer's billing address
updateBillingAddress(billingAddress)
Use this method to update the Customer's billing address.
Method parameters
billingAddress required nullable object
New billing information for the Customer.
Hide billingAddress properties
name optional string
address optional object
Hide address properties
country required string
line1 optional string
Address line 1 (e.g., street, PO Box, or company name).
line2 optional string
Address line 2 (e.g., apartment, suite, unit, or building).
city optional string
City, district, suburb, town, or village.
postal_code optional string
state optional string
State, county, province, or region.
This method returns a Promise that resolves with an object containing the following fields:
type: one of either "success" or "error"session: only populated when type is "success". Contains a Session instance representing the updated state.error: only populated when type is "error". Contains an object with a string message field which can be displayed to your customer.
Update the Customer's billing address
Checkout (React)
useCheckout hook
Update the customer's email address
Use this method to update the Customer's email address.
Method parameters
email required nullable string
The Customer's email address.
This method returns a Promise that resolves with an object containing the following fields:
type: one of either "success" or "error"session: only populated when type is "success". Contains a Session instance representing the updated state.error: only populated when type is "error". Contains an object with a string message field which can be displayed to your customer.
Update the Customer's email address
Checkout (React)
useCheckout hook
Update the customer's phone number
updatePhoneNumber(phoneNumber)
Use this method to update the Customer's phone number.
Method parameters
phoneNumber required nullable string
The Customer's phone number.
This method returns a Promise that resolves with an object containing the following fields:
type: one of either "success" or "error"session: only populated when type is "success". Contains a Session instance representing the updated state.error: only populated when type is "error". Contains an object with a string message field which can be displayed to your customer.
Update the Customer's phone number
Checkout (React)
useCheckout hook
Update the customer's business name and tax ID
updateTaxIdInfo(taxIdInfo?)
Use this method to update the Customer's business name and tax ID.
Method parameters
taxIdInfo optional
The Customer's tax ID information including the business name and tax ID.
Hide taxIdInfo properties
businessName required nullable string
The Customer's business name.
taxId required
Hide taxId properties
type required
value required nullable string
This method returns a Promise that resolves with an object containing the following fields:
type: one of either "success" or "error"session: only populated when type is "success". Contains a Session instance representing the updated state.error: only populated when type is "error". Contains an object with a string message field which can be displayed to your customer.
Update the Customer's business name and tax ID
Checkout (React)
useCheckout hook
Update line item quantities
updateLineItemQuantity(options)
Use this method to change the quantity of a line item.
Method parameters
options required object
Options for updateLineItemQuantity.
Hide options properties
lineItem required string
The ID of the line item to update.
quantity required integer
The new quantity of the line item.
This method returns a Promise that resolves with an object containing the following fields:
type: one of either "success" or "error"session: only populated when type is "success". Contains a Session instance representing the updated state.error: only populated when type is "error". Contains an object with a string message field which can be displayed to your customer.
Update line item quantities
Checkout (React)
useCheckout hook
Update shipping option
updateShippingOption(shippingOption?)
Use this method to update the selected shipping option. See shippingOptions for a list of the available shipping options.
Method parameters
shippingOption optional string
The ID of the shipping option to select.
This method returns a Promise that resolves with an object containing the following fields:
type: one of either "success" or "error"session: only populated when type is "success". Contains a Session instance representing the updated state.error: only populated when type is "error". Contains an object with a string message field which can be displayed to your customer.
Update the selected shipping option
Checkout (React)
useCheckout hook
Confirm the session
Use this method to confirm the Checkout Session.
You must either read total.total.amount or each of total.total.minorUnitsAmount and currency and minorUnitsAmountDivisor from the checkout object and display in your UI, otherwise an error will be thrown. This helps keep your checkout page in sync as the Checkout Session updates, including adding future Stripe features, with minimal UI code changes.
Method parameters
options optional object
Hide options properties
returnUrl string
The URL to redirect your customer to after they authenticate or cancel their payment on the payment method’s app or site. This parameter is only required if you didn't specify the return_url when creating the Checkout Session.
paymentMethod string
The ID of a previously collected PaymentMethod to use for confirmation.
When this option is provided, Custom Checkout will ignore the payment method collected by the PaymentElement and attempt confirmation using the provided PaymentMethod.
savePaymentMethod boolean
Whether your Customer has provided consent to save the payment method for future purchases.
Learn how to save payment methods.
redirect 'always' | 'if_required'
By default, confirm will always redirect to your returnUrl after a successful confirmation. If you set redirect: "if_required", then confirm will only redirect if your user chooses a redirect-based payment method.
email string
The Customer's email address.
If provided, this value overrides any values previously set using updateEmail.
phoneNumber string
The Customer's phone number.
If provided, this value overrides any values previously set using updatePhoneNumber.
billingAddress object
The Customer's billing address.
If provided, this value overrides any values previously set using updateBillingAddress.
Hide billingAddress properties
name optional string
address optional object
Hide address properties
country required string
line1 optional string
Address line 1 (e.g., street, PO Box, or company name).
line2 optional string
Address line 2 (e.g., apartment, suite, unit, or building).
city optional string
City, district, suburb, town, or village.
postal_code optional string
state optional string
State, county, province, or region.
shippingAddress object
The Customer's shipping address.
If provided, this value overrides any values previously set using updateShippingAddress.
Hide shippingAddress properties
name optional string
address optional object
Hide address properties
country required string
line1 required string
Address line 1 (e.g., street, PO Box, or company name).
line2 optional string
Address line 2 (e.g., apartment, suite, unit, or building).
city optional string
City, district, suburb, town, or village.
postal_code optional string
state optional string
State, county, province, or region.
This method returns a Promise that resolves with an object containing the following fields:
type: one of either "success" or "error"session: only populated when type is "success". Contains a Session instance representing the updated state.error: only populated when type is "error". Contains an object with a string message field which can be displayed to your customer.
Confirm the Checkout Session
Checkout (React)
useCheckout hook
Run a server update
runServerUpdate(userFunction)
Use this method to wrap an async function that makes a request to your server to update the Checkout Session.
Method parameters
userFunction required function
An async function to make a request to your server to update the Checkout Session.
This method returns a Promise that resolves with an object containing the following fields:
type: one of either "success" or "error"session: only populated when type is "success". Contains a Session instance representing the updated state.error: only populated when type is "error". Contains an object with a string message field which can be displayed to your customer.
Payment Intents
Introduction
Payment Intents
Accept global payments online with the Payment Intents APIs. For step-by-step instructions on using the Payment Intents APIs, see the accept a payment guide.
The following Stripe.js methods are available to use as part of your integration.
Payment Intents
Confirm a PaymentIntent
stripe.confirmPayment(options)
Use stripe.confirmPayment to confirm a PaymentIntent using data collected by the Payment Element, or with manually provided data via confirmParams. When called, stripe.confirmPayment will attempt to complete any required actions, such as authenticating your user by displaying a 3DS dialog or redirecting them to a bank authorization page. Your user will be redirected to the return_url you pass once the confirmation is complete.
Method parameters
options required object
Hide options properties
elements Conditionally required object
clientSecret Conditionally required string
confirmParams object
Parameters that will be passed on to the Stripe API. Refer to the Payment Intents API for a full list of parameters.
Hide confirmParams properties
return_url required string
The url your customer is redirected to after they complete the payment.
You can use the following query parameters, payment_intent (the PaymentIntent's ID) or payment_intent_client_secret (the PaymentIntent's client secret), to retrieve the PaymentIntent's status. You can also append your own query parameters to the return_url, which persist through the redirect process.
shipping recommended object
The shipping details for the payment, if collected.
Note: When the Address Element in shipping mode is being used, shipping address details are collected from the Address Element and passed to the PaymentIntents confirm endpoint as the shipping parameter. You can also include additional shipping fields, which will be merged with the data collected from the Element. Values passed here will override details collected by Elements.
confirmation_token string
If collected previously, the ID of the ConfirmationToken to use to confirm this PaymentIntent. This is mutually exclusive with the elements parameter.
payment_method string
If collected previously, the ID of the payment method to attach to this PaymentIntent. This is mutually exclusive with the elements parameter.
payment_method_data object
When you call stripe.confirmPayment, payment details are collected from the Element and passed to the PaymentIntents confirm endpoint as the payment_method_data parameter. You can also include additional payment_method_data fields, which will be merged with the data collected from the Element.
Hide payment_method_data properties
billing_details object
The customer's billing_details. Details collected by Elements will override values passed here. Billing fields that are omitted in the Payment Element via the fields option required.
Note: When the Address Element in billing mode is being used, billing address details are collected from the Address Element and passed to the PaymentIntents confirm endpoint as the billing_details parameter. The values collected from the Address Element will take precedence.
allow_redisplay 'unspecified' | 'always' | 'limited'
Indicates whether the payment method can be displayed to the customer in subsequent checkout flows. The value passed here will override the allow_redisplay determined by the provided elements parameter.
expand array
redirect 'always' | 'if_required'
By default, stripe.confirmPayment will always redirect to your return_url after a successful confirmation. If you set redirect: "if_required", then stripe.confirmPayment will only redirect if your user chooses a redirect-based payment method.
Note: Setting if_required requires that you handle successful confirmations for redirect-based and non-redirect based payment methods separately. When a non-redirect based payment method is successfully confirmed, stripe.confirmPayment will resolve with a {paymentIntent} object.
stripe.confirmPayment will return a Promise. After a successful confirmation, Stripe redirects your user to the return_url you provide before the Promise resolves. For payments that don't require a redirect, the Promise resolves to the updated Intent.
If the confirmation fails, the Promise will resolve with an {error} object that describes the failure. If the error type is either card_error or validation_error, directly display the error message in error.message to your user. If the error type is `invalid_request_error, you might have an invalid request or 3DS authentication failures.
For some payment methods, such as iDEAL or Afterpay/Clearpay, Stripe redirects your user to an intermediate page to authorize the payment. If iDEAL or Afterpay/Clearpay fail to authorize the payment, Stripe redirects the user to your return_url, and the PaymentIntent has a status of requires_payment_method. In this case, attempt to recollect payment from the user.
The stripe.confirmPayment might take several seconds to complete. During that time, disable your form from being resubmitted and show a waiting indicator, such as a spinner. If you receive an error result, show this error to the user, re-enable the form, and hide the waiting indicator.
Payment Intents
Confirm a PaymentIntent by payment method
Confirm a PaymentIntent by payment method
Below are a number of methods used to confirm a PaymentIntent for a specific payment method type.
Payment Intents
Confirm a PaymentIntent by payment method
Confirm a card payment
stripe.confirmCardPayment(clientSecret,data?,options?)
Use stripe.confirmCardPayment when the customer submits your payment form. When called, it will confirm the PaymentIntent with data you provide and carry out 3DS or other next actions if they are required.
If you are using Dynamic 3D Secure, stripe.confirmCardPayment will trigger your Radar rules to execute and may open a dialog for your customer to authenticate their payment.
When you confirm a PaymentIntent, it needs to have an attached PaymentMethod. In addition to confirming the PaymentIntent, this method can automatically create and attach a new PaymentMethod for you. It can also be called with an existing PaymentMethod, or if you have already attached a PaymentMethod you can call this method without needing to provide any additional data. These use cases are detailed in the sections that follow.
Method parameters
clientSecret required string
data optional object
Data to be sent with the request. Refer to the Payment Intents API for a full list of parameters.
Hide data properties
payment_method recommended string | object
Either the id of an existing PaymentMethod, or an object containing data to create a PaymentMethod with. See the use case sections below for details.
shipping recommended object
return_url string
If you are handling next actions yourself, pass in a return_url. If the subsequent action is redirect_to_url, this URL will be used on the return path for the redirect.
receipt_email string
Email address that the receipt for the resulting payment will be sent to.
setup_future_usage string
Indicates that you intend to make future payments with this PaymentIntent's payment method.
If present, the payment method used with this PaymentIntent can be attached to a Customer, even after the transaction completes.
Use on_session if you intend to only reuse the payment method when your customer is present in your checkout flow. Use off_session if your customer may or may not be in your checkout flow. See saving card details during payment to learn more.
Stripe uses setup_future_usage to dynamically optimize your payment flow and comply with regional legislation and network rules. For example, if your customer is impacted by SCA, using off_session will ensure that they are authenticated while processing this PaymentIntent. You will then be able to collect off-session payments for this customer.
payment_method_options object
An object containing payment-method-specific configuration to confirm the PaymentIntent with.
Hide payment_method_options properties
card object
Configuration for this card payment.
Hide card properties
cvc Element
Use the provided cardCvc Element when confirming the PaymentIntent with an existing PaymentMethod.
network string
Selected network to process this PaymentIntent on. Depends on the available networks of the card attached to the PaymentIntent. Can only be set at confirm-time.
options optional object
An options object to control the behavior of this method.
stripe.confirmCardPayment will return a Promise which resolves with a result object. This object has either:
result.paymentIntent: the successful PaymentIntent.result.error: an error. When the error type is card_error or validation_error, you can display the error message in error.message directly to your user. Refer to the API reference for other possible errors.
Note that stripe.confirmCardPayment may take several seconds to complete. During that time, you should disable your form from being resubmitted and show a waiting indicator like a spinner. If you receive an error result, you should be sure to show that error to the customer, re-enable the form, and hide the waiting indicator.
Additionally, stripe.confirmCardPayment may trigger a 3D Secure authentication challenge. This will be shown in a modal dialog and may be confusing for customers using assistive technologies like screen readers. You should make your form accessible by ensuring that success or error messages are clearly read out after this method completes.
Confirm a card payment
with payment data from an Element
Use stripe.confirmCardPayment with payment data from an Element by passing a card or cardNumber Element as payment_method[card] in the data argument.
The new PaymentMethod will be created with data collected by the Element and will be used to confirm the PaymentIntent.
Data argument properties
payment_method required object
Pass an object to confirm using data collected by a card or cardNumber Element.
Hide payment_method properties
card required Element
Uses the provided card or cardNumber Element for confirmation.
billing_details recommended object
Confirm a card payment
with an existing payment method
Use stripe.confirmCardPayment with an existing PaymentMethod by passing its id to payment_method. The PaymentMethod will be used to confirm the PaymentIntent.
Data argument properties
payment_method required string
Confirm with existing payment method
Confirm a card payment
with an existing token
For backwards compatibility, you can convert an existing Token into a PaymentMethod with stripe.confirmCardPayment by passing the Token to payment_method[card][token]. The newly created PaymentMethod will be used to confirm the PaymentIntent.
Data argument properties
payment_method required object
Pass an object to confirm using an existing token.
Hide payment_method properties
card required object
Hide card properties
token required string
Converts the provided token into a PaymentMethod to use for confirmation.
billing_details recommended object
Confirm with existing token
Confirm a card payment
with an attached PaymentMethod
If you have already attached a PaymentMethod to this PaymentIntent, then you can confirm the PaymentIntent using stripe.confirmCardPayment without passing in any additional data.
Confirm with an attached PaymentMethod
Payment Intents
Confirm a PaymentIntent by payment method
Confirm an ACH Direct Debit payment
stripe.confirmUsBankAccountPayment(clientSecret,data?)
Use stripe.confirmUsBankAccountPayment in the Accept a payment flow for the ACH Direct Debit payment method to record the customer’s authorization for payment.
When you confirm a PaymentIntent, it needs to have an attached PaymentMethod. We suggest using stripe.collectBankAccountForPayment, which automatically collects bank account details and attaches a PaymentMethod. You may also choose to reuse an existing PaymentMethod or manually collect bank account details using the data parameter. These use cases are detailed in the sections that follow.
Method parameters
clientSecret required string
data optional object
Data to be sent with the request. Refer to the Payment Intents API for a full list of parameters.
Hide data properties
payment_method object | string
The id of an existing PaymentMethod or an object of collected data. See use cases below for details.
stripe.confirmUsBankAccountPayment will return a Promise which resolves with a result object. This object has either:
Confirm an ACH Direct Debit payment
Confirm an ACH Direct Debit payment
with an existing PaymentMethod
If you have already created a PaymentMethod, you can pass its id to payment_method when calling stripe.confirmUsBankAccountPayment.
Data argument properties
payment_method required string
Confirm with an existing PaymentMethod
Confirm an ACH Direct Debit payment
with an attached PaymentMethod
If you have successfully called stripe.collectBankAccountForPayment or attached a PaymentMethod to this PaymentIntent already, then you can confirm the PaymentIntent without passing in any additional data.
Confirm with an attached PaymentMethod
Confirm an ACH Direct Debit payment
with self collected bank account information
If you already know the customer’s bank account information, or want to collect it yourself, you can pass them in directly to create a new PaymentMethod and confirm the PaymentIntent.
Data argument properties
payment_method required object
Pass an object to confirm using data collected.
Hide payment_method properties
billing_details required Object
Hide billing_details properties
name required string
The customer's name. The first and last name must be at minimum 2 characters each.
email string
us_bank_account required Object
Hide us_bank_account properties
account_number required string
The customer’s bank account number.
routing_number required string
The routing number of the customer’s bank.
account_holder_type required string
Account holder type: individual or company.
account_type string
Account type: checkings or savings. Defaults to checking if omitted.
Confirm with bank account information
Payment Intents
Confirm a PaymentIntent by payment method
Confirm an ACSS Debit payment
stripe.confirmAcssDebitPayment(clientSecret,data?,options?)
Use stripe.confirmAcssDebitPayment in the Accept a payment flow for the Canadian pre-authorized debit payment method when the customer submits your payment form. When called, it will automatically load an on-page modal UI to collect bank account details and verification, accept a hosted mandate agreement, and confirm the PaymentIntent when the user submits the form. Note that there are some additional requirements to this flow that are not covered in this reference. Refer to our integration guide for more details.
When you confirm a PaymentIntent, it needs to have an attached PaymentMethod. stripe.confirmAcssDebitPayment automatically creates a new PaymentMethod for you when your customer completes the modal UI. It can also be called with an existing PaymentMethod, which will load the modal UI to collect a new mandate agreement. These use cases are detailed in the sections that follow.
Method parameters
clientSecret required string
data optional object
Data to be sent with the request. Refer to the Payment Intents API for a full list of parameters.
Hide data properties
payment_method object | string
The id of an existing PaymentMethod or an object of collected data. See use cases below for details.
options optional object
An options object to control the behavior of this method.
Hide options properties
skipMandate boolean
Set this to true if you want to skip displaying the mandate confirmation.
stripe.confirmAcssDebitPayment will return a Promise which resolves with a result object. This object has either:
Note that stripe.confirmAcssDebitPayment may take several seconds to complete. During that time, disable your form from being resubmitted and show a waiting indicator like a spinner. If you receive an error result, show it to the customer, re-enable the form, and hide the waiting indicator.
Confirm Canadian pre-authorized debit payment
Confirm a Canadian pre-authorized debit payment
with a new PaymentMethod
You can pass in the customer’s billing details to create a new PaymentMethod and confirm the PaymentIntent. You are required to collect and include the customer’s name and email address. This method loads an on-page modal UI that handles bank account details collection and verification, presents a hosted mandate agreement and collects authorization for you.
Data argument properties
payment_method required object
Pass an object to confirm using data collected.
Hide payment_method properties
billing_details required Object
Hide billing_details properties
name required string
The customer's name. The first and last name must be at minimum 2 characters each.
email required string
Confirm with a new PaymentMethod
Confirm a Canadian pre-authorized debit payment
with an existing PaymentMethod
If you have already created a PaymentMethod, you can pass its id to payment_method when calling stripe.confirmAcssDebitPayment. This method loads an on-page modal UI that only presents a hosted mandate agreement and collects authorization for you.
Data argument properties
payment_method required string
Confirm with an existing PaymentMethod
Confirm a Canadian pre-authorized debit payment
with an attached PaymentMethod
If you have already attached a PaymentMethod to this PaymentIntent, then you can confirm the PaymentIntent without passing in any additional data. This method loads an on-page modal UI that only presents a hosted mandate agreement and collects authorization for you.
Confirm with an attached PaymentMethod
Confirm a Canadian pre-authorized debit payment
with self collected bank account information
If you already know the customer’s bank account information, or want to collect it yourself, you can pass them in directly to create a new PaymentMethod and confirm the PaymentIntent. In this case, this method does not load the on-page modal UI, so you will need to build your own mandate agreement page.
Data argument properties
payment_method required object
Pass an object to confirm using data collected.
Hide payment_method properties
billing_details required Object
Hide billing_details properties
name required string
The customer's name. The first and last name must be at minimum 2 characters each.
email required string
acss_debit required Object
Hide acss_debit properties
account_number required string
The customer’s bank account number.
institution_number required string
The institution number of the customer’s bank.
transit_number required string
The transit number of the customer’s bank.
Confirm with bank account information
Confirm a Canadian pre-authorized debit payment
with an existing PaymentMethod but skip mandate display
If you have already created a PaymentMethod and built your own mandate agreement page, you can reuse it by passing its id to payment_method when calling stripe.confirmAcssDebitPayment and skip the on-page modal UI at the same time.
Data and options argument paramters
data object
Data to be sent with the request.
Hide data properties
payment_method required string
options object
An options object to control the behavior of this method.
Hide options properties
skipMandate required boolean
Set to true to skip the on-page modal UI.
Confirm with an existing PaymentMethod but skip mandate display
Payment Intents
Confirm a PaymentIntent by payment method
Confirm an Affirm payment
stripe.confirmAffirmPayment(clientSecret,data?,options?)
Use stripe.confirmAffirmPayment in the Affirm payment method creation flow when the customer submits your payment form. When called, it will confirm the PaymentIntent with data you provide, and it will automatically redirect the customer to authorize the transaction. Once authorization is complete, the customer will be redirected back to your specified return_url. When you confirm a PaymentIntent, it needs to have an attached PaymentMethod. In addition to confirming the PaymentIntent, this method can automatically create and attach a new PaymentMethod for you. If you have already attached a PaymentMethod you can call this method without needing to provide any additional data. These use cases are detailed in the sections that follow.
Method parameters
clientSecret required string
data optional object
Data to be sent with the request. Refer to the Payment Intents API for a full list of parameters.
Hide data properties
payment_method recommended string | object
Either the id of an existing PaymentMethod, or an object containing data to create a PaymentMethod with. See the use case sections below for details.
shipping required object
Hide shipping properties
name required string
address required object
return_url required string
The url your customer will be directed to after they complete authentication.
options optional object
An options object to control the behavior of this method.
By default, stripe.confirmAffirmPayment will trigger a redirect when successful. If there is an error, or when handling next_actions manually by using the handleActions: false option, it will return a Promise which resolves with a result object. This object has either:
Note that stripe.confirmAffirmPayment may take several seconds to complete. During that time, you should disable your form from being resubmitted and show a waiting indicator like a spinner. If you receive an error result, you should be sure to show that error to the customer, re-enable the form, and hide the waiting indicator.
Confirm an Affirm payment
Confirm an Affirm payment
without an existing payment method
If you have not already created a PaymentMethod, you can pass payment method parameters, and the newly created PaymentMethod will be used to confirm the PaymentIntent.
Data argument properties
payment_method required object
Pass payment method billing details.
Hide payment_method properties
billing_details recommended object
Hide billing_details properties
email required string
name required string
address required object
shipping required object
Hide shipping properties
name required string
address required object
return_url required string
The url your customer will be directed to after they complete authentication.
Confirm without existing payment method
Confirm an Affirm payment
with an existing payment method
If you have already created a PaymentMethod, you can pass its id to payment_method and it will be used to confirm the PaymentIntent.
Data argument properties
payment_method required string
The id of an existing PaymentMethod.
shipping required object
Hide shipping properties
name required string
address required object
return_url required string
The url your customer will be directed to after they complete authentication.
Confirm with existing payment method
Confirm an Affirm payment
with an attached PaymentMethod
If you have already attached a return_url and a PaymentMethod to this PaymentIntent, then you can confirm without passing in any additional data.
Confirm with an attached PaymentMethod
Payment Intents
Confirm a PaymentIntent by payment method
Confirm an Afterpay Clearpay payment
stripe.confirmAfterpayClearpayPayment(clientSecret,data?,options?)
Use stripe.confirmAfterpayClearpayPayment in the Afterpay Clearpay payment method creation flow when the customer submits your payment form. When called, it will confirm the PaymentIntent with data you provide, and it will automatically redirect the customer to authorize the transaction. Once authorization is complete, the customer will be redirected back to your specified return_url. When you confirm a PaymentIntent, it needs to have an attached PaymentMethod. In addition to confirming the PaymentIntent, this method can automatically create and attach a new PaymentMethod for you. If you have already attached a PaymentMethod you can call this method without needing to provide any additional data. These use cases are detailed in the sections that follow.
Method parameters
clientSecret required string
data optional object
Data to be sent with the request. Refer to the Payment Intents API for a full list of parameters.
Hide data properties
payment_method recommended string | object
Either the id of an existing PaymentMethod, or an object containing data to create a PaymentMethod with. See the use case sections below for details.
return_url required string
The url your customer will be directed to after they complete authentication.
options optional object
An options object to control the behavior of this method.
By default, stripe.confirmAfterpayClearpayPayment will trigger a redirect when successful. If there is an error, or when handling next_actions manually by using the handleActions: false option, it will return a Promise which resolves with a result object. This object has either:
Note that stripe.confirmAfterpayClearpayPayment may take several seconds to complete. During that time, you should disable your form from being resubmitted and show a waiting indicator like a spinner. If you receive an error result, you should be sure to show that error to the customer, re-enable the form, and hide the waiting indicator.
Confirm an Afterpay Clearpay payment
Confirm an Afterpay Clearpay payment
without an existing payment method
If you have not already created a PaymentMethod, you can pass payment method parameters, and the newly created PaymentMethod will be used to confirm the PaymentIntent.
Data argument properties
payment_method required object
Pass payment method billing details.
Hide payment_method properties
billing_details required object
Hide billing_details properties
email required string
name required string
address required object
shipping recommended object
Hide shipping properties
name required string
address required object
return_url required string
The url your customer will be directed to after they complete authentication.
Confirm without existing payment method
Confirm an Afterpay Clearpay payment
with an existing payment method
If you have already created a PaymentMethod, you can pass its id to payment_method and it will be used to confirm the PaymentIntent.
Data argument properties
payment_method required string
The id of an existing PaymentMethod.
return_url required string
The url your customer will be directed to after they complete authentication.
Confirm with existing payment method
Confirm an Afterpay Clearpay payment
with an attached PaymentMethod
If you have already attached a return_url and a PaymentMethod to this PaymentIntent, then you can confirm without passing in any additional data.
Confirm with an attached PaymentMethod
Payment Intents
Confirm a PaymentIntent by payment method
Confirm an Alipay payment
stripe.confirmAlipayPayment(clientSecret,data?,options?)
Use stripe.confirmAlipayPayment in the Alipay payment method creation flow when the customer submits your payment form. When called, it will confirm the PaymentIntent with data you provide, and it will automatically redirect the customer to authorize the transaction. Once authorization is complete, the customer will be redirected back to your specified return_url. When you confirm a PaymentIntent, it needs to have an attached PaymentMethod. In addition to confirming the PaymentIntent, this method can automatically create and attach a new PaymentMethod for you. If you have already attached a PaymentMethod you can call this method without needing to provide any additional data. These use cases are detailed in the sections that follow.
Method parameters
clientSecret required string
data optional object
Data to be sent with the request. Refer to the Payment Intents API for a full list of parameters.
Hide data properties
payment_method recommended string | object
The id of an existing PaymentMethod. See the use case sections below for details.
return_url recommended string
The url your customer will be directed to after they complete authentication.
options optional object
An options object to control the behavior of this method.
By default, stripe.confirmAlipayPayment will trigger a redirect when successful. If there is an error, or when handling next_actions manually by using the handleActions: false option, it will return a Promise which resolves with a result object. This object has either:
Note that stripe.confirmAlipayPayment may take several seconds to complete. During that time, you should disable your form from being resubmitted and show a waiting indicator like a spinner. If you receive an error result, you should be sure to show that error to the customer, re-enable the form, and hide the waiting indicator.
Confirm an Alipay payment
Confirm an Alipay payment
Without an existing payment method
If you have not already created a PaymentMethod, the newly created PaymentMethod will be used to confirm the PaymentIntent.
Data argument properties
return_url recommended string
The url your customer will be directed to after they complete authentication.
Confirm without existing payment method
Confirm an Alipay payment
With an existing payment method
If you have already created a PaymentMethod, you can pass its id to payment_method and it will be used to confirm the PaymentIntent.
Data argument properties
payment_method required string
The id of an existing PaymentMethod.
return_url recommended string
The url your customer will be directed to after they complete authentication.
Confirm with existing payment method
Confirm an Alipay payment
With an attached PaymentMethod
If you have already attached a return_url and a PaymentMethod to this PaymentIntent, then you can confirm without passing in any additional data.
Confirm with an attached PaymentMethod
Payment Intents
Confirm a PaymentIntent by payment method
Confirm a BECS debit payment
stripe.confirmAuBecsDebitPayment(clientSecret,data?)
Use stripe.confirmAuBecsDebitPayment in the BECS Direct Debit Payments with Payment Methods flow when the customer submits your payment form. When called, it will confirm the PaymentIntent with data you provide. Note that there are some additional requirements to this flow that are not covered in this reference. Refer to our integration guide for more details.
When you confirm a PaymentIntent, it needs to have an attached PaymentMethod. In addition to confirming the PaymentIntent, this method can automatically create and attach a new PaymentMethod for you. If you have already attached a PaymentMethod you can call this method without needing to provide any additional data. These use cases are detailed in the sections that follow.
Method parameters
clientSecret required string
data optional object
Data to be sent with the request. Refer to the Payment Intents API for a full list of parameters.
Hide data properties
payment_method recommended object | string
The id of an existing PaymentMethod or an object of collected data. See use cases below for details.
setup_future_usage string
To set up the BECS Direct Debit account for reuse, set this parameter to off_session. BECS Direct Debit only accepts an off_session value for this parameter. If a customer is provided on this PaymentIntent, the PaymentMethod will be attached to the customer when the PaymentIntent transitions to processing.
stripe.confirmAuBecsDebitPayment will return a Promise which resolves with a result object. This object has either:
result.paymentIntent: the successful PaymentIntent.result.error: an error. Refer to the API reference for all possible errors.
Note that stripe.confirmAuBecsDebitPayment may take several seconds to complete. During that time, you should disable your form from being resubmitted and show a waiting indicator like a spinner. If you receive an error result, you should be sure to show that error to the customer, re-enable the form, and hide the waiting indicator.
Confirm a BECS Debit payment
Confirm a BECS Debit payment
with payment data from an Element
Create and attach a new PaymentMethod with stripe.confirmAuBecsDebitPayment by passing an auBankAccount Element to payment_method[au_becs_debit]. The new PaymentMethod will be created with the data collected by the Element and will be used to confirm the PaymentIntent. Additionally, to create a BECS Direct Debit PaymentMethod, you are required to collect and include the account holder's name and the customer's email address.
Data argument properties
payment_method required object
Pass an object to confirm the payment using data collected by an auBankAccount Element.
Hide payment_method properties
au_becs_debit required Element
An auBankAccount Element.
billing_details required Object
Hide billing_details properties
name required string
The account holder's name.
email required string
Confirm a BECS Debit payment
with self collected data
If you already know the customer’s BSB number and bank account number or want to collect it yourself, then you do not need to use the auBankAccount Element with stripe.confirmAuBecsDebitPayment. You can pass in the customer’s bank account information directly to create a new PaymentMethod and confirm the PaymentIntent. To create a BECS Direct Debit PaymentMethod, you are required to collect and include the account holder's name and the customer's email address.
Data argument properties
payment_method required object
Pass an object to confirm using data collected without an Element.
Hide payment_method properties
au_becs_debit required object
Hide au_becs_debit properties
bsb_number required string
A Bank State Branch (BSB) number.
account_number required string
billing_details required Object
Hide billing_details properties
name required string
The account holder's name.
email required string
Confirm with self collected data
Confirm a BECS Debit payment
with an existing payment method
If you have already created a PaymentMethod, you can pass its id to payment_method when calling stripe.confirmAuBecsDebitPayment. It will be used to confirm the PaymentIntent.
Data argument properties
payment_method required string
Confirm with existing payment method
Confirm a BECS Debit payment
with an attached PaymentMethod
If you have already attached a PaymentMethod to this PaymentIntent, then you can confirm the PaymentIntent using stripe.confirmAuBecsDebitPayment without passing in any additional data.
Confirm with an attached PaymentMethod
Payment Intents
Confirm a PaymentIntent by payment method
Confirm a BLIK payment
stripe.confirmBlikPayment(clientSecret,data,options?)
Use stripe.confirmBlikPayment in the BLIK Payments with Payment Methods flow when the customer submits your payment form. When called, it will confirm the PaymentIntent with data you provide, and it will automatically prompt the customer to authorize the transaction.
Method parameters
clientSecret required string
data required object
Data to be sent with the request. Refer to the Payment Intents API for a full list of parameters.
Hide data properties
payment_method_options required object
An object that contains transaction specific data.
Hide payment_method_options properties
code required string
Your customer's 6-digit BLIK code.
payment_method object
Use this parameter to supply additional data relevant to the transaction, such as billing details.
Hide payment_method properties
options optional object
An options object to control the behavior of this method.
Hide options properties
handleActions boolean
Set this to false if you want to manually determine if the confirmation has succeeded or failed.
By default, stripe.confirmBlikPayment will only return when the payment has succeeded or failed. If there is an error, or when handling next actions manually by using the handleActions: false option, it will return a Promise which resolves with a result object. This object has either:
Note that stripe.confirmBlikPayment may take several seconds to complete. During that time, you should disable your form from being resubmitted and show a waiting indicator like a spinner. If you receive an error result, you should be sure to show that error to the customer, re-enable the form, and hide the waiting indicator.
Payment Intents
Confirm a PaymentIntent by payment method
Confirm a Boleto payment
stripe.confirmBoletoPayment(clientSecret,data?,options?)
Use stripe.confirmBoletoPayment in the Boleto Payment with Payment Methods flow when the customer submits your payment form. When called, it will confirm the PaymentIntent with data you provide. Note that there are some additional requirements to this flow that are not covered in this reference. Refer to our integration guide for more details.
When you confirm a PaymentIntent, it needs to have an attached PaymentMethod. In addition to confirming the PaymentIntent, this method can automatically create and attach a new PaymentMethod for you. If you have already attached a PaymentMethod you can call this method without needing to provide any additional data. These use cases are detailed in the sections that follow.
Method parameters
clientSecret required string
data optional object
Data to be sent with the request. Refer to the Payment Intents API for a full list of parameters.
Hide data properties
payment_method object | string
The id of an existing PaymentMethod or an object of collected data. See use cases below for details.
options optional object
An options object to control the behavior of this method.
Hide options properties
handleActions required boolean
Set to false. The Boleto private beta does not handle the next actions for you automatically (e.g. display Boleto details). Please refer to our Stripe Boleto integration guide for more info.
stripe.confirmBoletoPayment will return a Promise which resolves with a result object. This object has either:
result.paymentIntent: the successful PaymentIntent.result.error: an error. Refer to the API reference for all possible errors.
Note that stripe.confirmBoletoPayment may take several seconds to complete. During that time, you should disable your form from being resubmitted and show a waiting indicator like a spinner. If you receive an error result, you should be sure to show that error to the customer, re-enable the form, and hide the waiting indicator.
Confirm a Boleto payment
with collected data
You can pass in the customer’s billing details to create a new PaymentMethod and confirm the PaymentIntent. To create a Boleto PaymentMethod, you are required to collect and include the customer’s name, email, Brazilian tax id (CPF/CNPJ) and address.
Data argument properties
payment_method required object
Pass an object to confirm using data collected.
Hide payment_method properties
boleto required Object
Hide boleto properties
tax_id required string
The customer's Brazilian tax id (CPF/CNPJ).
billing_details required Object
Hide billing_details properties
name required string
The customer's name. The first and last name must be at minimum 2 characters each.
email required string
address required string
The customer's address: street name, city, state and postal code
Hide address properties
line1 required string
The customer's address line 1 (e.g. street or company name).
line2 string
The customer's address line 2 (e.g. apartment, suite, unit, or building).
city required string
The customer's address city (e.g. Sao Paulo).
state required string
The customer's address state (e.g. SP).
postal_code required string
The customer's CEP (i.e. Brazilian postal code). Must be 8 digits long.
country required string
Confirm with collected data
Confirm a Boleto payment
with an existing payment method
If you have already created a PaymentMethod, you can pass its id to payment_method when calling stripe.confirmBoletoPayment. It will be used to confirm the PaymentIntent.
Data argument properties
payment_method required string
Confirm with existing payment method
Confirm a Boleto payment
with an attached PaymentMethod
If you have already attached a PaymentMethod to this PaymentIntent, then you can confirm the PaymentIntent using stripe.confirmBoletoPayment without passing in any additional data.
Confirm with an attached PaymentMethod
Payment Intents
Confirm a PaymentIntent by payment method
Confirm a Customer Balance payment
stripe.confirmCustomerBalancePayment(clientSecret,data?,options?)
Use stripe.confirmCustomerBalancePayment in the Customer Balance payment flow when the customer submits your payment form. When called, it will confirm the PaymentIntent with data you provide. Refer to our integration guide for more details.
Since the Customer Balance payment method draws from a balance, the attempt will succeed or fail depending on the current balance amount. To collect more funds from the customer when the cash balance is insufficient, use the customer balance with bank transfer funding parameters.
The confirmation attempt will finish in one of the following result states:
- If the customer balance is greater than or equal to the amount, the PaymentIntent response will have a
status of succeeded. The funding_type will be ignored. - If the customer balance is less than the amount, and you do not set the
funding_type, the PaymentIntent response will have a status of requires_payment_method. - If the customer balance is less than the amount, and you set the
funding_type, the PaymentIntent response will have a status of requires_action. The paymentIntent.next_action.display_bank_transfer_instructions hash will contain bank transfer details for funding the Customer Balance.
Method parameters
clientSecret required string
data optional object
Data to be sent with the request. Refer to the Payment Intents API for a full list of parameters.
Hide data properties
payment_method required object
An object specifying the customer_balance type.
Hide payment_method properties
customer_balance required object
payment_method_options object
options optional object
An options object to control the behavior of this method.
Hide options properties
handleActions required boolean
stripe.confirmCustomerBalancePayment will return a Promise which resolves with a result object. This object has either:
result.paymentIntent: when the Customer Balance is sufficient to pay the amount, a PaymentIntent with status of succeeded.result.paymentIntent: when the Customer Balance is insufficient to pay the amount, and funding_type data was provided, a PaymentIntent with status of requires_action.result.paymentIntent: when the Customer Balance is insufficient to pay the amount, and no funding_type data was provided, a PaymentIntent with status of requires_payment_method.result.error: an error. Refer to the API reference for all possible errors.
Note that stripe.confirmCustomerBalancePayment may take several seconds to complete. During that time, you should disable your form from being resubmitted and show a waiting indicator like a spinner. If you receive an error result, you should be sure to show that error to the customer, re-enable the form, and hide the waiting indicator.
Confirm a Customer Balance payment
Confirm a Customer Balance payment
with collected data
You can pass in the customer’s bank transfer funding details to create a new PaymentMethod and confirm the PaymentIntent.
If the Customer Balance was not enough to pay the amount, the status is requires_action. The paymentIntent.next_action.display_bank_transfer_instructions hash contains bank transfer details for funding the Customer Balance.
Data argument properties
payment_method required object
Pass an object to confirm using data collected.
Hide payment_method properties
customer_balance required object
payment_method_options object
Additional payment-specific configuration options.
Hide payment_method_options properties
funding_type string
The funding method type to be used when there are not enough funds in the Customer Balance. Permitted values include: bank_transfer.
bank_transfer object
The customer's chosen bank transfer method.
Hide bank_transfer properties
type required string
The list of bank transfer types allowed to use for funding. Permitted values include: us_bank_account, eu_bank_account, id_bank_account, gb_bank_account, jp_bank_account, or mx_bank_account.
eu_bank_account object
Details for the customer's EU bank account transfer. Required if the type is eu_bank_account.
Hide eu_bank_account properties
country required string
The desired country code of the bank account information. Permitted values include: DE, ES, FR, IE, NL.
id_bank_account object
Details for the customer's Indonesian bank account transfer. Required if the type is id_bank_account.
Hide id_bank_account properties
bank required string
Bank where the account is held. One of bca, bni.
requested_address_types array
List of address types that should be returned in the financial_addresses response. If not specified, all valid types will be returned. Permitted values include: aba, swift, sort_code, zengin, iban, spei, id_bban, or sepa.
Confirm with collected data
Payment Intents
Confirm a PaymentIntent by payment method
Confirm a Cash App Pay payment
stripe.confirmCashappPayment(clientSecret,data?,options?)
Use stripe.confirmCashappPayment in the Cash App Pay payment method creation flow when the customer submits your payment form. When called, it will confirm the PaymentIntent with data you provide and handle the NextAction for the customer to authorize the payment.
When you confirm a PaymentIntent, it needs to have an attached PaymentMethod.
In addition to confirming the PaymentIntent, this method can automatically create and attach a new PaymentMethod for you. If you have already attached a PaymentMethod you can call this method without needing to provide any additional data. These use cases are detailed in the sections that follow.
Method parameters
clientSecret required string
data optional object
Data to be sent with the request. Refer to the Payment Intents API for a full list of parameters.
Hide data properties
payment_method recommended string | object
Either the id of an existing PaymentMethod, or an object containing data to create a PaymentMethod with. See the use case sections below for details.
return_url required string
The url your customer will be directed to after they complete authentication.
options optional object
An options object to control the behavior of this method.
By default, stripe.confirmCashappPayment will display Cash App Pay QR code in desktop web app, or trigger a redirect in mobile web app. If there is an error, or when handling next actions manually by using the handleActions: false option, it will return a Promise which resolves with a result object. This object has either:
Note that stripe.confirmCashappPayment may take several seconds to complete. During that time, you should disable your form from being resubmitted and show a waiting indicator like a spinner. If you receive an error result, you should be sure to show that error to the customer, re-enable the form, and hide the waiting indicator.
Confirm a Cash App Pay payment
Confirm a Cash App Pay payment
Without an existing payment method
If you have not already created a PaymentMethod, you can pass payment method parameters, and the newly created PaymentMethod will be used to confirm the PaymentIntent.
Data argument properties
return_url required string
The url your customer will be directed to after they complete authentication.
Confirm without existing payment method
Confirm a Cash App Pay payment
With an existing payment method
If you have already created a PaymentMethod, you can pass its id to payment_method and it will be used to confirm the PaymentIntent.
Data argument properties
payment_method required string
The id of an existing PaymentMethod.
return_url required string
The url your customer will be directed to after they complete authentication.
Confirm with existing payment method
Confirm a Cash App Pay payment
With an attached PaymentMethod
If you have already attached a return_url and a PaymentMethod to this PaymentIntent, then you can confirm without passing in any additional data.
Confirm with an attached PaymentMethod
Payment Intents
Confirm a PaymentIntent by payment method
Confirm an EPS payment
stripe.confirmEpsPayment(clientSecret,data?,options?)
Use stripe.confirmEpsPayment in the EPS Payments with Payment Methods flow when the customer submits your payment form. When called, it will confirm the PaymentIntent with data you provide, and it will automatically redirect the customer to authorize the transaction. Once authorization is complete, the customer will be redirected back to your specified return_url. When you confirm a PaymentIntent, it needs to have an attached PaymentMethod. In addition to confirming the PaymentIntent, this method can automatically create and attach a new PaymentMethod for you. If you have already attached a PaymentMethod you can call this method without needing to provide any additional data. These use cases are detailed in the sections that follow.
Method parameters
clientSecret required string
data optional object
Data to be sent with the request. Refer to the Payment Intents API for a full list of parameters.
Hide data properties
payment_method recommended string | object
Either the id of an existing PaymentMethod, or an object containing data to create a PaymentMethod with. See the use case sections below for details.
return_url recommended string
The url your customer will be directed to after they complete authentication.
options optional object
An options object to control the behavior of this method.
stripe.confirmEpsPayment will trigger a redirect when successful. If there is an error, it will return a Promise which resolves with a result object. This object has either:
Note that stripe.confirmEpsPayment may take several seconds to complete. During that time, you should disable your form from being resubmitted and show a waiting indicator like a spinner. If you receive an error result, you should be sure to show that error to the customer, re-enable the form, and hide the waiting indicator.
Confirm an EPS payment
with an existing payment method
Use stripe.confirmEpsPayment with an existing PaymentMethod by passing its id to payment_method. The PaymentMethod will be used to confirm the PaymentIntent.
Data argument properties
payment_method required string
The id of an existing PaymentMethod.
return_url recommended string
The url your customer will be directed to after they complete authentication.
Confirm with existing payment method
Confirm an EPS payment
with collected data
Your customer's name is required for the EPS authorization to succeed. You can pass in the customer’s name directly to create a new PaymentMethod and confirm the PaymentIntent.
Data argument properties
payment_method required object
Pass an object to confirm with the customer's name.
Hide payment_method properties
billing_details required object
An object detailing billing information.
Hide billing_details properties
return_url recommended string
The url your customer will be directed to after they complete authentication.
Confirm with self collected data
Confirm an EPS payment
with an attached PaymentMethod
If you have already attached a PaymentMethod to this PaymentIntent, then you can confirm the PaymentIntent using stripe.confirmEpsPayment without passing in any additional data.
Confirm with an attached PaymentMethod
Payment Intents
Confirm a PaymentIntent by payment method
Confirm an FPX payment
stripe.confirmFpxPayment(clientSecret,data?,options?)
Use stripe.confirmFpxPayment in the FPX payment method creation flow when the customer submits your payment form. When called, it will confirm the PaymentIntent with data you provide, and it will automatically redirect the customer to authorize the transaction. Once authorization is complete, the customer will be redirected back to your specified return_url.
When you confirm a PaymentIntent, it needs to have an attached PaymentMethod. In addition to confirming the PaymentIntent, this method can automatically create and attach a new PaymentMethod for you. If you have already attached a PaymentMethod you can call this method without needing to provide any additional data. These use cases are detailed in the sections that follow.
Method parameters
clientSecret required string
data optional object
Data to be sent with the request. Refer to the Payment Intents API for a full list of parameters.
Hide data properties
payment_method recommended string | object
Either the id of an existing PaymentMethod, or an object containing data to create a PaymentMethod with. See the use case sections below for details.
return_url recommended string
The url your customer will be directed to after they complete authentication.
options optional object
An options object to control the behavior of this method.
By default, stripe.confirmFpxPayment will trigger a redirect when successful. If there is an error, or when handling next_actions manually by using the handleActions: false option, it will return a Promise which resolves with a result object. This object has either:
Note that stripe.confirmFpxPayment may take several seconds to complete. During that time, you should disable your form from being resubmitted and show a waiting indicator like a spinner. If you receive an error result, you should be sure to show that error to the customer, re-enable the form, and hide the waiting indicator.
Confirm an FPX payment
with payment data from an Element
Create and attach a new PaymentMethod by passing an fpxBank Element to payment_method[fpx]. The new PaymentMethod will be created with the bank code collected by the Element and will be used to confirm the PaymentIntent.
Data argument properties
payment_method required object
Pass an object to confirm using data collected by an fpxBank Element.
Hide payment_method properties
return_url recommended string
The url your customer will be directed to after they complete authentication.
Confirm an FPX payment
with an existing payment method
If you have already created a PaymentMethod, you can pass its id to payment_method and it will be used to confirm the PaymentIntent.
Data argument properties
payment_method required string
The id of an existing PaymentMethod.
return_url recommended string
The url your customer will be directed to after they complete authentication.
Confirm with existing payment method
Confirm an FPX payment
with self collected data
If you already know the customer’s bank or want to collect it yourself, then you do not need to use the fpxBank Element. You can pass in the customer’s bank code directly.
Data argument properties
payment_method required object
Pass an object to confirm using data collected by an fpxBank Element.
Hide payment_method properties
fpx required object
An object detailing the customer's FPX bank.
return_url recommended string
The url your customer will be directed to after they complete authentication.
Confirm with self collected data
Confirm an FPX payment
with an attached PaymentMethod
If you have already attached a return_url and a PaymentMethod to this PaymentIntent, then you can confirm the PaymentIntent using stripe.confirmFpxPayment without passing in any additional data.
Confirm with an attached PaymentMethod
Payment Intents
Confirm a PaymentIntent by payment method
Confirm a giropay payment
stripe.confirmGiropayPayment(clientSecret,data?,options?)
Use stripe.confirmGiropayPayment in the giropay Payments with Payment Methods flow when the customer submits your payment form. When called, it will confirm the PaymentIntent with data you provide, and it will automatically redirect the customer to authorize the transaction. Once authorization is complete, the customer will be redirected back to your specified return_url. When you confirm a PaymentIntent, it needs to have an attached PaymentMethod. In addition to confirming the PaymentIntent, this method can automatically create and attach a new PaymentMethod for you. If you have already attached a PaymentMethod you can call this method without needing to provide any additional data. These use cases are detailed in the sections that follow.
Method parameters
clientSecret required string
data optional object
Data to be sent with the request. Refer to the Payment Intents API for a full list of parameters.
Hide data properties
payment_method recommended string | object
Either the id of an existing PaymentMethod, or an object containing data to create a PaymentMethod with. See the use case sections below for details.
return_url recommended string
The url your customer will be directed to after they complete authentication.
options optional object
An options object to control the behavior of this method.
stripe.confirmGiropayPayment will trigger a redirect when successful. If there is an error, it will return a Promise which resolves with a result object. This object has either:
Note that stripe.confirmGiropayPayment may take several seconds to complete. During that time, you should disable your form from being resubmitted and show a waiting indicator like a spinner. If you receive an error result, you should be sure to show that error to the customer, re-enable the form, and hide the waiting indicator.
Confirm a giropay payment
Confirm a giropay payment
with an existing payment method
Use stripe.confirmGiropayPayment with an existing PaymentMethod by passing its id to payment_method. The PaymentMethod will be used to confirm the PaymentIntent.
Data argument properties
payment_method required string
The id of an existing PaymentMethod.
return_url recommended string
The url your customer will be directed to after they complete authentication.
Confirm with existing payment method
Confirm a giropay payment
with collected data
Your customer's name is required for the giropay authorization to succeed. You can pass in the customer’s name directly to create a new PaymentMethod and confirm the PaymentIntent.
Data argument properties
payment_method required object
Pass an object to confirm with the customer's name.
Hide payment_method properties
billing_details required object
An object detailing billing information.
Hide billing_details properties
return_url recommended string
The url your customer will be directed to after they complete authentication.
Confirm with self collected data
Confirm a giropay payment
with an attached PaymentMethod
If you have already attached a PaymentMethod to this PaymentIntent, then you can confirm the PaymentIntent using stripe.confirmGiropayPayment without passing in any additional data.
Confirm with an attached PaymentMethod
Payment Intents
Confirm a PaymentIntent by payment method
Confirm a GrabPay payment
stripe.confirmGrabPayPayment(clientSecret,data?,options?)
Use stripe.confirmGrabPayPayment in the GrabPay payments with Payment Methods flow when the customer submits your payment form. When called, it will confirm the PaymentIntent, and automatically redirect the customer to authorize the transaction. Once authorization is complete, the customer will be redirected back to your specified return_url.
Method parameters
clientSecret required string
data optional object
Data to be sent with the request. Refer to the Payment Intents API for a full list of parameters.
Hide data properties
payment_method string | object
Either the id of an existing PaymentMethod, or an object containing data to create a PaymentMethod with. See the use case sections below for details.
return_url required string
The URL your customer will be directed to after they complete authentication.
options optional object
An options object to control the behavior of this method.
By default, stripe.confirmGrabPayPayment will trigger a redirect when successful. If there is an error, or when handling next actions manually by using the handleActions: false option, it will return a Promise which resolves with a result object. This object has either:
Note that stripe.confirmGrabPayPayment may take several seconds to complete. During that time, you should disable your form from being resubmitted and show a waiting indicator like a spinner. If you receive an error result, you should be sure to show that error to the customer, re-enable the form, and hide the waiting indicator.
Confirm a GrabPay payment
Confirm a GrabPay payment
with a new PaymentMethod
You can confirm the PaymentIntent using stripe.confirmGrabPayPayment without passing in any additional data. This will automatically create and attach a new PaymentMethod.
Data argument properties
return_url required string
The URL your customer will be directed to after they complete authentication.
Confirm with a new PaymentMethod
Confirm a GrabPay payment
with an existing PaymentMethod
Use stripe.confirmGrabPayPayment with an existing PaymentMethod by passing its id to payment_method. The PaymentMethod will be used to confirm the PaymentIntent.
Data argument properties
payment_method required string
The id of an existing PaymentMethod.
return_url required string
The URL your customer will be directed to after they complete authentication.
Confirm with existing payment method
Confirm a GrabPay payment
with an attached PaymentMethod
If you have already attached a PaymentMethod to this PaymentIntent, you can then confirm the PaymentIntent using stripe.confirmGrabPayPayment without passing in any additional data.
Data argument properties
return_url required string
The URL your customer will be directed to after they complete authentication.
Confirm with an attached PaymentMethod
Payment Intents
Confirm a PaymentIntent by payment method
Confirm an iDEAL payment
stripe.confirmIdealPayment(clientSecret,data?,options?)
Use stripe.confirmIdealPayment in the iDEAL Payments with Payment Methods flow when the customer submits your payment form. When called, it will confirm the PaymentIntent with data you provide, and it will automatically redirect the customer to authorize the transaction. Once authorization is complete, the customer will be redirected back to your specified return_url.
When you confirm a PaymentIntent, it needs to have an attached PaymentMethod. In addition to confirming the PaymentIntent, this method can automatically create and attach a new PaymentMethod for you. If you have already attached a PaymentMethod you can call this method without needing to provide any additional data. These use cases are detailed in the sections that follow.
Method parameters
clientSecret required string
data optional object
Data to be sent with the request. Refer to the Payment Intents API for a full list of parameters.
Hide data properties
payment_method recommended string | object
Either the id of an existing PaymentMethod, or an object containing data to create a PaymentMethod with. See the use case sections below for details.
return_url recommended string
The url your customer will be directed to after they complete authentication.
setup_future_usage string
To set up a SEPA Direct Debit payment method using the bank details from this iDEAL payment, set this parameter to off_session. When using this parameter, a customer will need to be set on the PaymentIntent. The newly created SEPA Direct Debit PaymentMethod will be attached to this customer.
options optional object
An options object to control the behavior of this method.
By default, stripe.confirmIdealPayment will trigger a redirect when successful. If there is an error, or when handling next actions manually by using the handleActions: false option, it will return a Promise which resolves with a result object. This object has either:
Note that stripe.confirmIdealPayment may take several seconds to complete. During that time, you should disable your form from being resubmitted and show a waiting indicator like a spinner. If you receive an error result, you should be sure to show that error to the customer, re-enable the form, and hide the waiting indicator.
Confirm an iDEAL payment
with payment data from an Element
Create and attach a new PaymentMethod with stripe.confirmIdealPayment by passing an idealBank Element to payment_method[ideal]. The new PaymentMethod will be created with the bank code collected by the Element and will be used to confirm the PaymentIntent.
Data argument properties
payment_method required object
Pass an object to confirm using data collected by an idealBank Element.
Hide payment_method properties
ideal recommended Element
billing_details object
The customer's billing_details. Required when setup_future_usage is set to off_session.
Hide billing_details properties
return_url recommended string
The url your customer will be directed to after they complete authentication.
setup_future_usage string
To set up a SEPA Direct Debit payment method using the bank details from this iDEAL payment, set this parameter to off_session. When using this parameter, a customer will need to be set on the PaymentIntent. The newly created SEPA Direct Debit PaymentMethod will be attached to this customer.
Confirm an iDEAL payment
with an existing payment method
Use stripe.confirmIdealPayment with an existing PaymentMethod by passing its id to payment_method. The PaymentMethod will be used to confirm the PaymentIntent.
Data argument properties
payment_method required string
The id of an existing PaymentMethod.
return_url recommended string
The url your customer will be directed to after they complete authentication.
setup_future_usage string
To set up a SEPA Direct Debit payment method using the bank details from this iDEAL payment, set this parameter to off_session. When using this parameter, a customer will need to be set on the PaymentIntent. The newly created SEPA Direct Debit PaymentMethod will be attached to this customer.
Confirm with existing payment method
Confirm an iDEAL payment
with self collected data
If you already know the customer’s bank or want to collect it yourself, then you do not need to use the idealBank Element. You can pass in the customer’s bank code directly to create a new PaymentMethod and confirm the PaymentIntent.
Data argument properties
payment_method required object
Pass an object to confirm using data collected by an idealBank Element.
Hide payment_method properties
ideal required object
An object detailing the customer's iDEAL bank.
billing_details object
The customer's billing_details. Required when setup_future_usage is set to off_session.
Hide billing_details properties
return_url recommended string
The url your customer will be directed to after they complete authentication.
setup_future_usage string
To set up a SEPA Direct Debit payment method using the bank details from this iDEAL payment, set this parameter to off_session. When using this parameter, a customer will need to be set on the PaymentIntent. The newly created SEPA Direct Debit PaymentMethod will be attached to this customer.
Confirm with self collected data
Confirm an iDEAL payment
with an attached PaymentMethod
If you have already attached a PaymentMethod to this PaymentIntent, then you can confirm the PaymentIntent using stripe.confirmIdealPayment without passing in any additional data.
Confirm with an attached PaymentMethod
Payment Intents
Confirm a PaymentIntent by payment method
Confirm a Klarna payment
stripe.confirmKlarnaPayment(clientSecret,data?,options?)
Use stripe.confirmKlarnaPayment in the Klarna payment method creation flow when the customer submits your payment form. When called, it will confirm the PaymentIntent with data you provide, and it will automatically redirect the customer to authorize the transaction. Once authorization is complete, the customer will be redirected back to your specified return_url.
When you confirm a PaymentIntent, it needs to have an attached PaymentMethod. In addition to confirming the PaymentIntent, this method can automatically create and attach a new PaymentMethod for you. If you have already attached a PaymentMethod you can call this method without needing to provide any additional data. These use cases are detailed in the sections that follow.
Method parameters
clientSecret required string
data optional object
Data to be sent with the request. Refer to the Payment Intents API for a full list of parameters.
Hide data properties
payment_method recommended string | object
Either the id of an existing PaymentMethod, or an object containing data to create a PaymentMethod with. See the use case sections below for details.
return_url recommended string
The url your customer will be directed to after they complete authentication.
options optional object
An options object to control the behavior of this method.
By default, stripe.confirmKlarnaPayment will trigger a redirect when successful. If there is an error, or when handling next_actions manually by using the handleActions: false option, it will return a Promise which resolves with a result object. This object has either:
Note that stripe.confirmKlarnaPayment may take several seconds to complete. During that time, you should disable your form from being resubmitted and show a waiting indicator like a spinner. If you receive an error result, you should be sure to show that error to the customer, re-enable the form, and hide the waiting indicator.
Confirm a Klarna payment
Without an existing payment method
If you have not already created a PaymentMethod, the newly created PaymentMethod will be used to confirm the PaymentIntent.
Data argument properties
return_url recommended string
The url your customer will be directed to after they complete authentication.
Confirm without existing payment method
Confirm a Klarna payment
With an existing payment method
If you have already created a PaymentMethod, you can pass its id to payment_method and it will be used to confirm the PaymentIntent.
Data argument properties
payment_method required string
The id of an existing PaymentMethod.
return_url recommended string
The url your customer will be directed to after they complete authentication.
Confirm with existing payment method
Confirm a Klarna payment
With an attached PaymentMethod
If you have already attached a return_url and a PaymentMethod to this PaymentIntent, then you can confirm without passing in any additional data.
Confirm with an attached PaymentMethod
Payment Intents
Confirm a PaymentIntent by payment method
Confirm a Konbini payment
stripe.confirmKonbiniPayment(clientSecret,data?,options?)
Use stripe.confirmKonbiniPayment in the Konbini payment flow when the customer submits your payment form. When called, it will confirm the PaymentIntent with data you provide. Note that there are some additional requirements to this flow that are not covered in this reference. Refer to our integration guide for more details.
When you confirm a PaymentIntent, it needs to have an attached PaymentMethod. In addition to confirming the PaymentIntent, this method can automatically create and attach a new PaymentMethod for you. If you have already attached a PaymentMethod you can call this method without needing to provide any additional data. These use cases are detailed in the sections that follow.
Method parameters
clientSecret required string
data optional object
Data to be sent with the request. Refer to the Payment Intents API for a full list of parameters.
Hide data properties
payment_method object | string
Either the id of an existing PaymentMethod, or an object containing data to create a PaymentMethod with. See the use case sections below for details.
payment_method_options Object
An object containing payment-method-specific configuration to confirm the PaymentIntent with.
Hide payment_method_options properties
konbini object
Configuration for this Konbini payment.
Hide konbini properties
confirmation_number string
An optional 10 to 11 digit numeric-only string determining the confirmation code at applicable convenience stores. May not be all 0 and could be rejected in case of insufficient uniqueness. We recommend to use the customer’s phone number.
options optional object
An options object to control the behavior of this method.
Hide options properties
handleActions boolean
Set this to false if you want to handle next actions yourself. Please refer to our integration guide for more info. Default is true.
stripe.confirmKonbiniPayment will return a Promise which resolves with a result object. This object has either:
result.paymentIntent: the successful PaymentIntent.result.error: an error. Refer to the API reference for all possible errors.
Note that stripe.confirmKonbiniPayment may take several seconds to complete. During that time, you should disable your form from being resubmitted and show a waiting indicator like a spinner. If you receive an error result, you should be sure to show that error to the customer, re-enable the form, and hide the waiting indicator.
Confirm a Konbini payment
Confirm a Konbini payment
with collected data
You can pass in the customer’s billing details to create a new PaymentMethod and confirm the PaymentIntent. To create a Konbini PaymentMethod, you are required to collect and include the customer’s name and email.
Data argument properties
payment_method required object
Pass an object to confirm using data collected.
Hide payment_method properties
billing_details required Object
Hide billing_details properties
name required string
The customer's full name.
email required string
The customer's email address.
payment_method_options Object
An object containing payment-method-specific configuration to confirm the PaymentIntent with.
Hide payment_method_options properties
konbini object
Configuration for this Konbini payment.
Hide konbini properties
confirmation_number string
An optional 10 to 11 digit numeric-only string determining the confirmation code at applicable convenience stores. May not be all 0 and could be rejected in case of insufficient uniqueness. We recommend to use the customer’s phone number.
Confirm with collected data
Confirm a Konbini payment
with an existing payment method
If you have already created a PaymentMethod, you can pass its id to payment_method when calling stripe.confirmKonbiniPayment. It will be used to confirm the PaymentIntent.
Data argument properties
payment_method required string
payment_method_options Object
An object containing payment-method-specific configuration to confirm the PaymentIntent with.
Hide payment_method_options properties
konbini object
Configuration for this Konbini payment.
Hide konbini properties
confirmation_number string
An optional 10 to 11 digit numeric-only string determining the confirmation code at applicable convenience stores. May not be all 0 and could be rejected in case of insufficient uniqueness. We recommend to use the customer’s phone number.
Confirm with existing payment method
Confirm a Konbini payment
with an attached PaymentMethod
If you have already attached a PaymentMethod to this PaymentIntent, then you can confirm the PaymentIntent using stripe.confirmKonbiniPayment without passing in any additional data.
Data argument properties
payment_method_options Object
An object containing payment-method-specific configuration to confirm the PaymentIntent with.
Hide payment_method_options properties
konbini object
Configuration for this Konbini payment.
Hide konbini properties
confirmation_number string
An optional 10 to 11 digit numeric-only string determining the confirmation code at applicable convenience stores. May not be all 0 and could be rejected in case of insufficient uniqueness. We recommend to use the customer’s phone number.
Confirm with an attached PaymentMethod
Payment Intents
Confirm a PaymentIntent by payment method
Confirm a MB WAY payment
stripe.confirmMbWayPayment(clientSecret,data?,options?)
Use stripe.confirmMbWayPayment in the MB WAY payment method creation flow when the customer submits your payment form. When you call the method, it confirms the PaymentIntent with the data you provide, and sends a request to the customer to authorize the transaction.
When you confirm a PaymentIntent, it needs to have an attached PaymentMethod. In addition to confirming the PaymentIntent, this method can automatically create and attach a new PaymentMethod for you. If you've already attached a PaymentMethod, you can call this method without needing to provide any additional data. These use cases are detailed in the sections that follow.
Method parameters
clientSecret required string
data optional object
Data to be sent with the request. Refer to the Payment Intents API for a full list of parameters.
Hide data properties
payment_method recommended string | object
Either the id of an existing PaymentMethod, or an object containing data to create a PaymentMethod with. See the use case sections below for details.
options optional object
An options object to control the behavior of this method.
Hide options properties
handleActions boolean
Set this to false if you want to manually handle polling for PaymentIntent updates. Default is true.
By default, stripe.confirmMbWayPayment will poll for updates to the PaymentIntent. If there's an error, or when handling next_actions manually by using the handleActions: false option, it returns a Promise which resolves with a result object. This object has either:
Note that stripe.confirmMbWayPayment might take some time to complete while waiting for customers to authorize the payment. During that time, you should disable your form from being resubmitted and show a waiting indicator like a spinner. If you receive an error result, show that error to the customer, re-enable the form, and hide the waiting indicator.
Confirm a MB WAY payment
without an existing payment method
If you haven't already created a PaymentMethod, you can pass payment method parameters, and the newly created PaymentMethod is used to confirm the PaymentIntent.
Data argument properties
payment_method required object
Pass payment method billing details.
Hide payment_method properties
billing_details required object
The billing_details associated with the payment. A phone number is required for all MB WAY payments.
Hide billing_details properties
Confirm without existing payment method
Confirm a MB WAY payment
with an existing payment method
If you've already created a PaymentMethod, you can pass its id to payment_method, which is used to confirm the PaymentIntent.
Data argument properties
payment_method required string
The id of an existing PaymentMethod.
Confirm with existing payment method
Confirm a MB WAY payment
with an attached PaymentMethod
If you've already attached a PaymentMethod to this PaymentIntent, you can confirm it without passing in any additional data.
Confirm with an attached PaymentMethod
Payment Intents
Confirm a PaymentIntent by payment method
Confirm a MobilePay payment
stripe.confirmMobilepayPayment(clientSecret,data?,options?)
Use stripe.confirmMobilepayPayment in the MobilePay Payments with Payment Methods flow when the customer submits your payment form. When called, it will confirm the PaymentIntent with data you provide, and it will automatically redirect the customer to authorize the transaction. Once authorization is complete, the customer will be redirected back to your specified return_url.
When you confirm a PaymentIntent, it needs to have an attached PaymentMethod. In addition to confirming the PaymentIntent, this method can automatically create and attach a new PaymentMethod for you. If you have already attached a PaymentMethod you can call this method without needing to provide any additional data. These use cases are detailed in the sections that follow.
Method parameters
clientSecret required string
data optional object
Data to be sent with the request. Refer to the Payment Intents API for a full list of parameters.
Hide data properties
payment_method recommended string | object
Either the id of an existing PaymentMethod, or an object containing data to create a PaymentMethod with. See the use case sections below for details.
return_url recommended string
The url your customer will be directed to after they complete authentication.
options optional object
An options object to control the behavior of this method.
By default, stripe.confirmMobilepayPayment will trigger a redirect when successful. If there is an error, or when handling next actions manually by using the handleActions: false option, it will return a Promise which resolves with a result object. This object has either:
Note that stripe.confirmMobilepayPayment may take several seconds to complete. During that time, you should disable your form from being resubmitted and show a waiting indicator like a spinner. If you receive an error result, you should be sure to show that error to the customer, re-enable the form, and hide the waiting indicator.
Confirm a MobilePay payment
Confirm a MobilePay payment
with an existing payment method
Use stripe.confirmMobilepayPayment with an existing PaymentMethod by passing its id to payment_method. The PaymentMethod will be used to confirm the PaymentIntent.
Data argument properties
payment_method required string
The id of an existing PaymentMethod.
return_url recommended string
The url your customer will be directed to after they complete authentication.
Confirm with existing payment method
Confirm a MobilePay payment
with an attached PaymentMethod
If you have already attached a PaymentMethod to this PaymentIntent, then you can confirm the PaymentIntent using stripe.confirmMobilepayPayment without passing in any additional data.
Confirm with an attached PaymentMethod
Payment Intents
Confirm a PaymentIntent by payment method
Confirm a Multibanco payment
stripe.confirmMultibancoPayment(clientSecret,data?,options?)
Use stripe.confirmMultibancoPayment in the Multibanco Payment with Payment Methods flow when the customer submits your payment form. When called, it will confirm the PaymentIntent with data you provide. Note that there are some additional requirements to this flow that are not covered in this reference. Refer to our integration guide for more details.
When you confirm a PaymentIntent, it needs to have an attached PaymentMethod. In addition to confirming the PaymentIntent, this method can automatically create and attach a new PaymentMethod for you. If you have already attached a PaymentMethod you can call this method without needing to provide any additional data. These use cases are detailed in the sections that follow.
Method parameters
clientSecret required string
data optional object
Data to be sent with the request. Refer to the Payment Intents API for a full list of parameters.
Hide data properties
payment_method object | string
The id of an existing PaymentMethod or an object of collected data. See use cases below for details.
options optional object
An options object to control the behavior of this method.
stripe.confirmMultibancoPayment will return a Promise which resolves with a result object. This object has either:
result.paymentIntent: the successful PaymentIntent.result.error: an error. Refer to the API reference for all possible errors.
stripe.confirmMultibancoPayment might take several seconds to complete. During that time, disable your form from being resubmitted and show a waiting indicator, such as a spinner. If you receive an error, display it to the customer, re-enable the form, and hide the waiting indicator.
Additionally, stripe.confirmMultibancoPayment will pop up a modal with the voucher. This modal contains all the information required to pay the voucher through online banking or from an ATM, such as the Multibanco entity and reference numbers, and amount.
Confirm a Multibanco payment
Confirm a Multibanco payment
with collected data
You can pass in the customer’s billing details to create a new PaymentMethod and confirm the PaymentIntent. To create a Multibanco PaymentMethod, you are required to collect and include the customer’s email address.
Data argument properties
payment_method required object
Pass an object to confirm using data collected.
Hide payment_method properties
billing_details required Object
Hide billing_details properties
Confirm with collected data
Confirm a Multibanco payment
with an existing payment method
If you have already created a PaymentMethod, you can pass its id to payment_method when calling stripe.confirmMultibancoPayment. It will be used to confirm the PaymentIntent.
Data argument properties
payment_method required string
Confirm with existing payment method
Confirm a Multibanco payment
with an attached PaymentMethod
If you have already attached a PaymentMethod to this PaymentIntent, then you can confirm the PaymentIntent using stripe.confirmMultibancoPayment without passing in any additional data.
Confirm with an attached PaymentMethod
Payment Intents
Confirm a PaymentIntent by payment method
Confirm an OXXO payment
stripe.confirmOxxoPayment(clientSecret,data?,options?)
Use stripe.confirmOxxoPayment in the OXXO Payment with Payment Methods flow when the customer submits your payment form. When called, it will confirm the PaymentIntent with data you provide. Note that there are some additional requirements to this flow that are not covered in this reference. Refer to our integration guide for more details.
When you confirm a PaymentIntent, it needs to have an attached PaymentMethod. In addition to confirming the PaymentIntent, this method can automatically create and attach a new PaymentMethod for you. If you have already attached a PaymentMethod you can call this method without needing to provide any additional data. These use cases are detailed in the sections that follow.
Method parameters
clientSecret required string
data optional object
Data to be sent with the request. Refer to the Payment Intents API for a full list of parameters.
Hide data properties
payment_method object | string
The id of an existing PaymentMethod or an object of collected data. See use cases below for details.
options optional object
An options object to control the behavior of this method.
stripe.confirmOxxoPayment will return a Promise which resolves with a result object. This object has either:
result.paymentIntent: the successful PaymentIntent.result.error: an error. Refer to the API reference for all possible errors.
Note that stripe.confirmOxxoPayment may take several seconds to complete. During that time, you should disable your form from being resubmitted and show a waiting indicator like a spinner. If you receive an error result, you should be sure to show that error to the customer, re-enable the form, and hide the waiting indicator.
Additionally, stripe.confirmOxxoPayment will pop up a modal with the voucher. This modal contains all the information required to pay the voucher at OXXO stores, such as the amount, a reference number and corresponding barcode.
Confirm an Oxxo payment
with collected data
You can pass in the customer’s billing details to create a new PaymentMethod and confirm the PaymentIntent. To create a OXXO PaymentMethod, you are required to collect and include the customer’s name and email address.
Data argument properties
payment_method required object
Pass an object to confirm using data collected.
Hide payment_method properties
billing_details required Object
Hide billing_details properties
name required string
The customer's name. The first and last name must be at minimum 2 characters each.
email required string
Confirm with collected data
Confirm an Oxxo payment
with an existing payment method
If you have already created a PaymentMethod, you can pass its id to payment_method when calling stripe.confirmOxxoPayment. It will be used to confirm the PaymentIntent.
Data argument properties
payment_method required string
Confirm with existing payment method
Confirm an Oxxo payment
with an attached PaymentMethod
If you have already attached a PaymentMethod to this PaymentIntent, then you can confirm the PaymentIntent using stripe.confirmOxxoPayment without passing in any additional data.
Confirm with an attached PaymentMethod
Payment Intents
Confirm a PaymentIntent by payment method
Confirm a Przelewy24 payment
stripe.confirmP24Payment(clientSecret,data?,options?)
Use stripe.confirmP24Payment in the Przelewy24 Payments with Payment Methods flow when the customer submits your payment form. When called, it will confirm the PaymentIntent with data you provide, and it will automatically redirect the customer to authorize the transaction. Once authorization is complete, the customer will be redirected back to your specified return_url.
When you confirm a PaymentIntent, it needs to have an attached PaymentMethod. In addition to confirming the PaymentIntent, this method can automatically create and attach a new PaymentMethod for you. If you have already attached a PaymentMethod you can call this method without needing to provide any additional data. These use cases are detailed in the sections that follow.
Method parameters
clientSecret required string
data optional object
Data to be sent with the request. Refer to the Payment Intents API for a full list of parameters.
Hide data properties
payment_method recommended string | object
Either the id of an existing PaymentMethod, or an object containing data to create a PaymentMethod with. See the use case sections below for details.
return_url recommended string
The url your customer will be directed to after they complete authentication.
options optional object
An options object to control the behavior of this method.
stripe.confirmP24Payment will trigger a redirect when successful. If there is an error, it will return a Promise which resolves with a result object. This object has either:
Note that stripe.confirmP24Payment may take several seconds to complete. During that time, you should disable your form from being resubmitted and show a waiting indicator like a spinner. If you receive an error result, you should be sure to show that error to the customer, re-enable the form, and hide the waiting indicator.
Confirm a Przelewy24 payment
with an existing payment method
Use stripe.confirmP24Payment with an existing PaymentMethod by passing its id to payment_method. The PaymentMethod will be used to confirm the PaymentIntent.
Data argument properties
payment_method required string
The id of an existing PaymentMethod.
return_url recommended string
The url your customer will be directed to after they complete authentication.
Confirm with existing payment method
Confirm a Przelewy24 payment
with collected data
Your customer's email address is required for the Przelewy24 authorization to succeed. You can pass in the customer’s email address directly to create a new PaymentMethod and confirm the PaymentIntent.
Data argument properties
payment_method required object
Pass an object to confirm with the customer's email address.
Hide payment_method properties
billing_details required object
An object detailing billing information.
Hide billing_details properties
email required string
The customer's email address.
return_url recommended string
The url your customer will be directed to after they complete authentication.
Confirm with self collected data
Confirm a Przelewy24 payment
with an attached PaymentMethod
If you have already attached a PaymentMethod to this PaymentIntent, then you can confirm the PaymentIntent using stripe.confirmP24Payment without passing in any additional data.
Confirm with an attached PaymentMethod
Payment Intents
Confirm a PaymentIntent by payment method
Confirm a PayNow payment
stripe.confirmPayNowPayment(clientSecret,data?,options?)
Use stripe.confirmPayNowPayment in the PayNow payment method creation flow when the customer submits your payment form. When called, it will confirm the PaymentIntent with data you provide and handle the NextAction for the customer to authorize the payment. When you confirm a PaymentIntent, it needs to have an attached PaymentMethod. In addition to confirming the PaymentIntent, this method can automatically create and attach a new PaymentMethod for you. If you have already attached a PaymentMethod you can call this method without needing to provide any additional data. These use cases are detailed in the sections that follow.
Method parameters
clientSecret required string
data optional object
Data to be sent with the request. Refer to the Payment Intents API for a full list of parameters.
Hide data properties
payment_method recommended string | object
Either the id of an existing PaymentMethod, or an object containing data to create a PaymentMethod with. See the use case sections below for details.
options optional object
An options object to control the behavior of this method.
By default, stripe.confirmPayNowPayment will display the PayNow QR code overlay. If there is an error, or when handling next actions manually by using the handleActions: false option, it will return a Promise which resolves with a result object. This object has either:
Note that stripe.confirmPayNowPayment may take several seconds to complete and display the QR code. During that time, you should disable your form from being resubmitted and show a waiting indicator like a spinner. If you receive an error result, you should be sure to show that error to the customer, re-enable the form, and hide the waiting indicator.
Confirm a PayNow payment
Without an existing payment method
If you have not already created a PaymentMethod, you can pass payment method parameters, and the newly created PaymentMethod will be used to confirm the PaymentIntent.
Data argument properties
payment_method required object
Pass payment method billing details.
Hide payment_method properties
billing_details recommended object
Confirm without existing payment method
Confirm a PayNow payment
With an existing payment method
If you have already created a PaymentMethod, you can pass its id to payment_method and it will be used to confirm the PaymentIntent.
Data argument properties
payment_method required string
The id of an existing PaymentMethod.
Confirm with existing payment method
Confirm a PayNow payment
With an attached PaymentMethod
If you have already attached a PaymentMethod to this PaymentIntent, then you can confirm without passing in any additional data.
Confirm with an attached PaymentMethod
Payment Intents
Confirm a PaymentIntent by payment method
Confirm a PayPal payment
stripe.confirmPayPalPayment(clientSecret,data?)
Use stripe.confirmPayPalPayment in the PayPal Payments with Payment Methods flow when the customer submits your payment form. When called, it will confirm the PaymentIntent, and it will automatically redirect the customer to authorize the transaction. Once authorization is complete, the customer will be redirected back to your specified return_url.
Method parameters
clientSecret required string
data optional object
Data to be sent with the request. Refer to the Payment Intents API for a full list of parameters.
Hide data properties
payment_method string | object
The id of an existing PaymentMethod. See the use case sections below for details.
return_url string
The url your customer will be directed to after they complete authentication. Required for new PayPal payment methods, but not required when using a previously set up PayPal payment method (via SetupIntent or a PaymentIntent with setup_future_usage).
stripe.confirmPayPalPayment will trigger a redirect when successful. If there is an error, it will return a Promise which resolves with a result object. This object has either:
Note that stripe.confirmPayPalPayment may take several seconds to complete. During that time, you should disable your form from being resubmitted and show a waiting indicator like a spinner. If you receive an error result, you should be sure to show that error to the customer, re-enable the form, and hide the waiting indicator.
Confirm a PayPal payment
with a new PaymentMethod
You can confirm the PaymentIntent using stripe.confirmPayPalPayment without passing in any additional data. This will automatically create and attach a new PaymentMethod.
Data argument properties
return_url string
The url your customer will be directed to after they complete authentication. Required for new PayPal payment methods, but not required when using a previously set up PayPal payment method (via SetupIntent or a PaymentIntent with setup_future_usage).
Confirm with a new PaymentMethod
Confirm a PayPal payment
with an existing payment method
Use stripe.confirmPayPalPayment with an existing PaymentMethod by passing its id to payment_method. The PaymentMethod will be used to confirm the PaymentIntent.
Data argument properties
payment_method required string
The id of an existing PaymentMethod.
return_url string
The url your customer will be directed to after they complete authentication. Required for new PayPal payment methods, but not required when using a previously set up PayPal payment method (via SetupIntent or a PaymentIntent with setup_future_usage).
Confirm with existing payment method
Confirm a PayPal payment
with an attached PaymentMethod
If you have already attached a PaymentMethod to this PaymentIntent, then you can confirm the PaymentIntent using stripe.confirmPayPalPayment without passing in any additional data.
Confirm with an attached PaymentMethod
Payment Intents
Confirm a PaymentIntent by payment method
Confirm a PayTo payment
stripe.confirmPayToPayment(clientSecret,data?,options?)
Use stripe.confirmPayToPayment in the PayTo payment method creation flow when the customer submits your payment form. When you call the method, it confirms the PaymentIntent with the data you provide, and sends a request to the customer to authorize the transaction.
When you confirm a PaymentIntent, it needs to have an attached PaymentMethod. In addition to confirming the PaymentIntent, this method can automatically create and attach a new PaymentMethod for you. If you've already attached a PaymentMethod, you can call this method without needing to provide any additional data. These use cases are detailed in the sections that follow.
Method parameters
clientSecret required string
data optional object
Data to be sent with the request. Refer to the Payment Intents API for a full list of parameters.
Hide data properties
payment_method recommended string | object
Either the id of an existing PaymentMethod, or an object containing data to create a PaymentMethod with. See the use case sections below for details.
options optional object
An options object to control the behavior of this method.
Hide options properties
handleActions boolean
Set this to false if you want to manually handle polling for PaymentIntent updates. Default is true.
By default, stripe.confirmPayToPayment will poll for updates to the PaymentIntent. If there's an error, or when handling next_actions manually by using the handleActions: false option, it returns a Promise which resolves with a result object. This object has either:
Note that stripe.confirmPayToPayment might take some time to complete while waiting for customers to authorize the PayTo agreement, and while waiting for funds to transfer. During that time, you should disable your form from being resubmitted and show a waiting indicator like a spinner. If you receive an error result, show that error to the customer, re-enable the form, and hide the waiting indicator.
Confirm a PayTo payment
without an existing payment method
If you haven't already created a PaymentMethod, you can pass payment method parameters, and the newly created PaymentMethod is used to confirm the PaymentIntent.
Data argument properties
payment_method required object
Pass payment method billing details.
Hide payment_method properties
billing_details required object
The billing_details associated with the payment. The email is required if the customer is paying with PayID.
Hide billing_details properties
email string
name required string
payto required object
The PayTo payment method details associated with the customer's bank account. Either pay_id or account_number and bsb_number must be provided.
Hide payto properties
pay_id string
account_number string
bsb_number string
Confirm without existing payment method
Confirm a PayTo payment
with an existing payment method
If you've already created a PaymentMethod, you can pass its id to payment_method, which is used to confirm the PaymentIntent.
Data argument properties
payment_method required string
The id of an existing PaymentMethod.
Confirm with existing payment method
Confirm a PayTo payment
with an attached PaymentMethod
If you've already attached a PaymentMethod to this PaymentIntent, you can confirm it without passing in any additional data.
Confirm with an attached PaymentMethod
Payment Intents
Confirm a PaymentIntent by payment method
Confirm a Pix payment
stripe.confirmPixPayment(clientSecret,data?,options?)
Use stripe.confirmPixPayment in the Pix Payment with Payment Methods flow when the customer submits your payment form. When called, it will confirm the PaymentIntent with data you provide. Note that there are some additional requirements to this flow that are not covered in this reference. Refer to our integration guide for more details.
When you confirm a PaymentIntent, it needs to have an attached PaymentMethod. In addition to confirming the PaymentIntent, this method can automatically create and attach a new PaymentMethod for you. If you have already attached a PaymentMethod you can call this method without needing to provide any additional data. These use cases are detailed in the sections that follow.
Method parameters
clientSecret required string
data optional object
Data to be sent with the request. Refer to the Payment Intents API for a full list of parameters.
Hide data properties
payment_method string | object
Either the id of an existing PaymentMethod, or an object containing data to create a PaymentMethod with. See the use case sections below for details.
options optional object
An options object to control the behavior of this method.
By default, stripe.confirmPixPayment will display the Pix QR code overlay. If there is an error, or when handling next actions manually by using the handleActions: false option, it will return a Promise which resolves with a result object. This object has either:
Note that stripe.confirmPixPayment may take several seconds to complete and display the QR code. During that time, you should disable your form from being resubmitted and show a waiting indicator like a spinner. If you receive an error result, you should be sure to show that error to the customer, re-enable the form, and hide the waiting indicator.
Confirm a Pix payment
without an existing payment method
If you have not already created a PaymentMethod, you can pass payment method parameters, and the newly created PaymentMethod will be used to confirm the PaymentIntent.
Data argument properties
payment_method required object
Pass payment method paramters or and empty payment method object.
Confirm without existing payment method
Confirm a Pix payment
with an existing payment method
If you have already created a PaymentMethod, you can pass its id to payment_method and it will be used to confirm the PaymentIntent.
Data argument properties
payment_method required string
Confirm with existing payment method
Confirm a Pix payment
with an attached PaymentMethod
If you have already attached a PaymentMethod to this PaymentIntent, then you can confirm without passing in any additional data.
Confirm with an attached PaymentMethod
Payment Intents
Confirm a PaymentIntent by payment method
Confirm a PromptPay payment
stripe.confirmPromptPayPayment(clientSecret,data?,options?)
Use stripe.confirmPromptPayPayment in the PromptPay payment method creation flow when the customer submits your payment form. When called, it will confirm the PaymentIntent with data you provide and handle the NextAction for the customer to authorize the payment. When you confirm a PaymentIntent, it needs to have an attached PaymentMethod. In addition to confirming the PaymentIntent, this method can automatically create and attach a new PaymentMethod for you. If you have already attached a PaymentMethod you can call this method without needing to provide any additional data. These use cases are detailed in the sections that follow.
Method parameters
clientSecret required string
data optional object
Data to be sent with the request. Refer to the Payment Intents API for a full list of parameters.
Hide data properties
payment_method recommended string | object
Either the id of an existing PaymentMethod, or an object containing data to create a PaymentMethod with. See the use case sections below for details.
options optional object
An options object to control the behavior of this method.
By default, stripe.confirmPromptPayPayment will display the PromptPay QR code overlay. If there is an error, or when handling next actions manually by using the handleActions: false option, it will return a Promise which resolves with a result object. This object has either:
Note that stripe.confirmPromptPayPayment may take several seconds to complete and display the QR code. During that time, you should disable your form from being resubmitted and show a waiting indicator like a spinner. If you receive an error result, you should be sure to show that error to the customer, re-enable the form, and hide the waiting indicator.
Confirm a PromptPay payment
Confirm a PromptPay payment
Without an existing payment method
If you have not already created a PaymentMethod, you can pass payment method parameters, and the newly created PaymentMethod will be used to confirm the PaymentIntent.
Data argument properties
payment_method required object
Pass payment method billing details.
Hide payment_method properties
billing_details recommended object
Confirm without existing payment method
Confirm a PromptPay payment
With an existing payment method
If you have already created a PaymentMethod, you can pass its id to payment_method and it will be used to confirm the PaymentIntent.
Data argument properties
payment_method required string
The id of an existing PaymentMethod.
Confirm with existing payment method
Confirm a PromptPay payment
With an attached PaymentMethod
If you have already attached a PaymentMethod to this PaymentIntent, then you can confirm without passing in any additional data.
Confirm with an attached PaymentMethod
Payment Intents
Confirm a PaymentIntent by payment method
Confirm a SEPA debit payment
stripe.confirmSepaDebitPayment(clientSecret,data?)
Use stripe.confirmSepaDebitPayment in the SEPA Direct Debit Payments with Payment Methods flow when the customer submits your payment form. When called, it will confirm the PaymentIntent with data you provide. Note that there are some additional requirements to this flow that are not covered in this reference. Refer to our integration guide for more details.
When you confirm a PaymentIntent, it needs to have an attached PaymentMethod. In addition to confirming the PaymentIntent, this method can automatically create and attach a new PaymentMethod for you. If you have already attached a PaymentMethod you can call this method without needing to provide any additional data. These use cases are detailed in the sections that follow.
Method parameters
clientSecret required string
data optional object
Data to be sent with the request. Refer to the Payment Intents API for a full list of parameters.
Hide data properties
payment_method recommended object | string
The id of an existing PaymentMethod or an object of collected data. See use cases below for details.
setup_future_usage string
To set up the SEPA Direct Debit account for reuse, set this parameter to off_session. SEPA Direct Debit only accepts an off_session value for this parameter. If a customer is provided on this PaymentIntent, the PaymentMethod will be attached to the customer when the PaymentIntent transitions to processing.
stripe.confirmSepaDebitPayment will return a Promise which resolves with a result object. This object has either:
result.paymentIntent: the successful PaymentIntent.result.error: an error. Refer to the API reference for all possible errors.
Note that stripe.confirmSepaDebitPayment may take several seconds to complete. During that time, you should disable your form from being resubmitted and show a waiting indicator like a spinner. If you receive an error result, you should be sure to show that error to the customer, re-enable the form, and hide the waiting indicator.
Confirm a SEPA Debit payment
Confirm a SEPA Debit payment
with payment data from an Element
Create and attach a new PaymentMethod with stripe.confirmSepaDebitPayment by passing an iban Element to payment_method[sepa_debit]. The new PaymentMethod will be created with the data collected by the Element and will be used to confirm the PaymentIntent. Additionally, to create a SEPA Direct Debit PaymentMethod, you are required to collect and include the customer’s name and email address.
Data argument properties
payment_method required object
Pass an object to confirm the payment using data collected by an iban Element.
Hide payment_method properties
sepa_debit required Element
billing_details required Object
Hide billing_details properties
name required string
email required string
Confirm a SEPA Debit payment
with self collected data
If you already know the customer’s IBAN account number or want to collect it yourself, then you do not need to use the iban Element with stripe.confirmSepaDebitPayment. You can pass in the customer’s account number directly to create a new PaymentMethod and confirm the PaymentIntent. To create a SEPA Direct Debit PaymentMethod, you are required to collect and include the customer’s name and email address.
Data argument properties
payment_method required object
Pass an object to confirm using data collected without an Element.
Hide payment_method properties
sepa_debit required object
Hide sepa_debit properties
billing_details required Object
Hide billing_details properties
name required string
email required string
Confirm with self collected data
Confirm a SEPA Debit payment
with an existing payment method
If you have already created a PaymentMethod, you can pass its id to payment_method when calling stripe.confirmSepaDebitPayment. It will be used to confirm the PaymentIntent.
Data argument properties
payment_method required string
Confirm with existing payment method
Confirm a SEPA Debit payment
with an attached PaymentMethod
If you have already attached a PaymentMethod to this PaymentIntent, then you can confirm the PaymentIntent using stripe.confirmSepaDebitPayment without passing in any additional data.
Confirm with an attached PaymentMethod
Payment Intents
Confirm a PaymentIntent by payment method
Confirm a Sofort payment
stripe.confirmSofortPayment(clientSecret,data?,options?)
Use stripe.confirmSofortPayment in the Sofort Payments with Payment Methods flow when the customer submits your payment form. When called, it will confirm the PaymentIntent with data you provide. It will then automatically redirect the customer to authorize the transaction. Once authorization is complete, the customer will be redirected back to your specified return_url.
When you confirm a PaymentIntent, it needs to have an attached PaymentMethod. In addition to confirming the PaymentIntent, this method can automatically create and attach a new PaymentMethod for you. If you have already attached a PaymentMethod you can call this method without needing to provide any additional data. These use cases are detailed in the sections that follow.
Method parameters
clientSecret required string
data optional object
Data to be sent with the request. Refer to the Payment Intents API for a full list of parameters.
Hide data properties
payment_method recommended string | object
Either the id of an existing PaymentMethod, or an object containing data to create a PaymentMethod with. See the use case sections below for details.
return_url recommended string
The url your customer will be directed to after they complete authentication.
setup_future_usage string
To set up a SEPA Direct Debit payment method using the bank details from this SOFORT payment, set this parameter to off_session. When using this parameter, a customer will need to be set on the PaymentIntent. The newly created SEPA Direct Debit PaymentMethod will be attached to this customer.
options optional object
An options object to control the behavior of this method.
stripe.confirmSofortPayment will trigger a redirect when successful. If there is an error, it will return a Promise which resolves with a result object. This object has either:
Note that stripe.confirmSofortPayment may take several seconds to complete. During that time, you should disable your form from being resubmitted and show a waiting indicator like a spinner. If you receive an error result, you should be sure to show that error to the customer, re-enable the form, and hide the waiting indicator.
Confirm a Sofort payment
with an existing payment method
Use stripe.confirmSofortPayment with an existing PaymentMethod by passing its id to payment_method. The PaymentMethod will be used to confirm the PaymentIntent.
Data argument properties
payment_method required string
The id of an existing PaymentMethod.
return_url recommended string
The url your customer will be directed to after they complete authentication.
setup_future_usage string
To set up a SEPA Direct Debit payment method using the bank details from this SOFORT payment, set this parameter to off_session. When using this parameter, a customer will need to be set on the PaymentIntent. The newly created SEPA Direct Debit PaymentMethod will be attached to this customer.
Confirm with existing payment method
Confirm a Sofort payment
with collected data
The country of your customer's bank is required for the Sofort authorization to succeed. You can pass in the country of your customer's bank directly to create a new PaymentMethod and confirm the PaymentIntent.
Data argument properties
payment_method required object
Pass an object to confirm with the customer's name.
Hide payment_method properties
sofort required object
An object detailing SOFORT specific parameters.
Hide sofort properties
country required string
The country code where customer's bank is located.
billing_details object
The customer's billing_details. Required when setup_future_usage is set to off_session.
Hide billing_details properties
return_url recommended string
The url your customer will be directed to after they complete authentication.
setup_future_usage string
To set up a SEPA Direct Debit payment method using the bank details from this SOFORT payment, set this parameter to off_session. When using this parameter, a customer will need to be set on the PaymentIntent. The newly created SEPA Direct Debit PaymentMethod will be attached to this customer.
Confirm with self collected data
Confirm a Sofort payment
with an attached PaymentMethod
If you have already attached a PaymentMethod to this PaymentIntent, then you can confirm the PaymentIntent using stripe.confirmSofortPayment without passing in any additional data.
Confirm with an attached PaymentMethod
Payment Intents
Confirm a PaymentIntent by payment method
Confirm a TWINT payment
stripe.confirmTwintPayment(clientSecret,data?,options?)
Use stripe.confirmTwintPayment in the TWINT payment method creation flow when the customer submits your payment form. When you call the method, it confirms the PaymentIntent with the data you provide, and automatically redirects the customer to authorize the transaction. Once authorization is complete, the customer is redirected back to your specified return_url.
When you confirm a PaymentIntent, it needs to have an attached PaymentMethod. In addition to confirming the PaymentIntent, this method can automatically create and attach a new PaymentMethod for you. If you've already attached a return_url and a PaymentMethod, you can call this method without needing to provide any additional data. These use cases are detailed in the sections that follow.
Method parameters
clientSecret required string
data optional object
Data to be sent with the request. Refer to the Payment Intents API for a full list of parameters.
Hide data properties
payment_method recommended string | object
Either the id of an existing PaymentMethod, or an object containing data to create a PaymentMethod with. See the use case sections below for details.
return_url required string
The url your customer will be directed to after they complete authentication.
options optional object
An options object to control the behavior of this method.
By default, stripe.confirmTwintPayment triggers a redirect when successful. If there's an error, or when handling next_actions manually by using the handleActions: false option, it returns a Promise which resolves with a result object. This object has either:
Note that stripe.confirmTwintPayment might take several seconds to complete. During that time, you should disable your form from being resubmitted and show a waiting indicator like a spinner. If you receive an error result, show that error to the customer, re-enable the form, and hide the waiting indicator.
Confirm a TWINT payment
without an existing payment method
If you haven't already created a PaymentMethod, you can pass payment method parameters, and the newly created PaymentMethod is used to confirm the PaymentIntent.
Data argument properties
payment_method required object
Pass payment method billing details.
Hide payment_method properties
billing_details required object
Hide billing_details properties
email required string
name required string
address required object
shipping recommended object
Hide shipping properties
name required string
address required object
return_url required string
The url your customer will be directed to after they complete authentication.
Confirm without existing payment method
Confirm a TWINT payment
with an existing payment method
If you've already created a PaymentMethod, you can pass its id to payment_method, which is used to confirm the PaymentIntent.
Data argument properties
payment_method required string
The id of an existing PaymentMethod.
return_url required string
The url your customer will be directed to after they complete authentication.
Confirm with existing payment method
Confirm a TWINT payment
with an attached PaymentMethod
If you've already attached a return_url and a PaymentMethod to this PaymentIntent, you can confirm it without passing in any additional data.
Confirm with an attached PaymentMethod
Payment Intents
Confirm a PaymentIntent by payment method
Confirm a WeChat Pay payment
stripe.confirmWechatPayPayment(clientSecret,data?,options?)
Use stripe.confirmWechatPayPayment in the WeChat Pay payment method creation flow when the customer submits your payment form. When called, it will confirm the PaymentIntent with data you provide and handle the NextAction for the customer to authorize the payment. When you confirm a PaymentIntent, it needs to have an attached PaymentMethod. In addition to confirming the PaymentIntent, this method can automatically create and attach a new PaymentMethod for you. If you have already attached a PaymentMethod you can call this method without needing to provide any additional data. These use cases are detailed in the sections that follow.
Method parameters
clientSecret required string
data optional object
Data to be sent with the request. Refer to the Payment Intents API for a full list of parameters.
Hide data properties
payment_method recommended string | object
Either the id of an existing PaymentMethod, or an object containing data to create a PaymentMethod with. See the use case sections below for details.
options optional object
An options object to control the behavior of this method.
By default, stripe.confirmWechatPayPayment will display WeChat Pay QR code. If there is an error, or when handling next actions manually by using the handleActions: false option, it will return a Promise which resolves with a result object. This object has either:
Note that stripe.confirmWechatPayPayment may take several seconds to complete and display the QR code. During that time, you should disable your form from being resubmitted and show a waiting indicator like a spinner. If you receive an error result, you should be sure to show that error to the customer, re-enable the form, and hide the waiting indicator.
Confirm a WeChat Pay payment
Confirm a WeChat Pay payment
Without an existing payment method
If you have not already created a PaymentMethod, you can pass payment method parameters, and the newly created PaymentMethod will be used to confirm the PaymentIntent.
Data argument properties
payment_method required object
Pass payment method billing details.
Hide payment_method properties
billing_details recommended object
Confirm without existing payment method
Confirm a WeChat Pay payment
With an existing payment method
If you have already created a PaymentMethod, you can pass its id to payment_method and it will be used to confirm the PaymentIntent.
Data argument properties
payment_method required string
The id of an existing PaymentMethod.
Confirm with existing payment method
Confirm a WeChat Pay payment
With an attached PaymentMethod
If you have already attached a PaymentMethod to this PaymentIntent, then you can confirm without passing in any additional data.
Confirm with an attached PaymentMethod
Payment Intents
Confirm a PaymentIntent by payment method
Confirm a Zip payment
stripe.confirmZipPayment(clientSecret,data?,options?)
Use stripe.confirmZipPayment in the Zip payment method creation flow when the customer submits your payment form. When called, it will confirm the PaymentIntent with data you provide, and it will automatically redirect the customer to authorize the transaction. Once authorization is complete, the customer will be redirected back to your specified return_url. When you confirm a PaymentIntent, it needs to have an attached PaymentMethod. In addition to confirming the PaymentIntent, this method can automatically create and attach a new PaymentMethod for you. If you have already attached a return_url and a PaymentMethod you can call this method without needing to provide any additional data. These use cases are detailed in the sections that follow.
Method parameters
clientSecret required string
data optional object
Data to be sent with the request. Refer to the Payment Intents API for a full list of parameters.
Hide data properties
payment_method recommended string | object
Either the id of an existing PaymentMethod, or an object containing data to create a PaymentMethod with. See the use case sections below for details.
return_url required string
The url your customer will be directed to after they complete authentication.
options optional object
An options object to control the behavior of this method.
By default, stripe.confirmZipPayment will trigger a redirect when successful. If there is an error, or when handling next_actions manually by using the handleActions: false option, it will return a Promise which resolves with a result object. This object has either:
Note that stripe.confirmZipPayment may take several seconds to complete. During that time, you should disable your form from being resubmitted and show a waiting indicator like a spinner. If you receive an error result, you should be sure to show that error to the customer, re-enable the form, and hide the waiting indicator.
Confirm an Zip payment
without an existing payment method
If you have not already created a PaymentMethod, you can pass payment method parameters, and the newly created PaymentMethod will be used to confirm the PaymentIntent.
Data argument properties
payment_method required object
Pass payment method billing details.
Hide payment_method properties
billing_details required object
Hide billing_details properties
email required string
name required string
address required object
shipping recommended object
Hide shipping properties
name required string
address required object
return_url required string
The url your customer will be directed to after they complete authentication.
Confirm without existing payment method
Confirm an Zip payment
with an existing payment method
If you have already created a PaymentMethod, you can pass its id to payment_method and it will be used to confirm the PaymentIntent.
Data argument properties
payment_method required string
The id of an existing PaymentMethod.
return_url required string
The url your customer will be directed to after they complete authentication.
Confirm with existing payment method
Confirm an Zip payment
with an attached PaymentMethod
If you have already attached a return_url and a PaymentMethod to this PaymentIntent, then you can confirm without passing in any additional data.
Confirm with an attached PaymentMethod
Payment Intents
Retrieve a PaymentIntent
stripe.retrievePaymentIntent(clientSecret)
Method parameters
clientSecret required string
This method returns a Promise which resolves with a result object. This object has either:
result.paymentIntent: a PaymentIntent was retrieved successfully.result.error: an error. Refer to the API reference for all possible errors.
Payment Intents
Verify with micro-deposits for payment
stripe.verifyMicrodepositsForPayment(clientSecret,data?)
Method parameters
clientSecret required string
data optional object
Data to be sent with the request.
Hide data properties
amounts array
An array of two positive integers, in cents, equal to the values of the micro-deposits sent to the bank account.
descriptor_code string
A six-character code starting with SM present in the microdeposit sent to the bank account.
stripe.verifyMicrodepositsForPayment will return a Promise which resolves with a result object. This object has either:
Verification can fail for several reasons. The failure may happen synchronously as a direct error response, or asynchronously through a payment_intent.payment_failed webhook event. Refer to our integration guide for more details.
Verify with micro-deposits for payment
Payment Intents
Create a Radar Session
stripe.createRadarSession()
Use stripe.createRadarSession() to associate client browser information with a Radar Session ID. This ID can then be passed to Stripe when creating charges and payment methods to associate client browser information with those charges and improve Radar's ability to identify fraud.
This method returns a Promise which resolves with a result object. This object has either:
result.radarSession: a Radar Session was created successfully.result.error: an error. Refer to the API reference for all possible errors and the FPX guide for FPX specific errors.
After you receive a Radar Session ID, pass it to your server and subsequently include it in your API requests to create charges, payment methods, or to create or confirm a PaymentIntent.
Note that stripe.createRadarSession should be non-blocking. If you receive an error from this function, continue on with completing charges without passing through a Radar Session ID.
Payment Intents
Handle a next action
stripe.handleNextAction(options)
Use stripe.handleNextAction in the finalizing payments on the server flow to finish confirmation of a PaymentIntent with the requires_action status. It will throw an error if the PaymentIntent has a different status.
Depending on the payment method and required action, the customer may be temporarily redirected from your site and brought back to the return_url parameter provided when the PaymentIntent is confirmed.
This method returns a Promise which resolves with a result object. This object has either:
result.paymentIntent: a PaymentIntent with the processing or succeeded status.result.error: an error. Refer to the API reference for all possible errors.
Note that stripe.handleNextAction may take several seconds to complete. During that time, you should disable your form from being resubmitted and show a waiting indicator like a spinner. If you receive an error result, you should be sure to show that error to the customer, re-enable the form, and hide the waiting indicator.
Additionally, stripe.handleNextAction may trigger a 3D Secure authentication challenge. The authentication challenge requires a context switch that can be hard to follow on a screen-reader. Ensure that your form is accessible by ensuring that success or error messages are clearly read out.
Payment Intents
Handle a card action
stripe.handleCardAction(clientSecret)
Use stripe.handleCardAction in the Payment Intents API manual confirmation flow to handle a PaymentIntent with the requires_action status. It will throw an error if the PaymentIntent has a different status.
Method parameters
clientSecret required string
This method returns a Promise which resolves with a result object. This object has either:
result.paymentIntent: a PaymentIntent with the requires_confirmation status to confirm server-side.result.error: an error. Refer to the API reference for all possible errors.
Note that stripe.handleCardAction may take several seconds to complete. During that time, you should disable your form from being resubmitted and show a waiting indicator like a spinner. If you receive an error result, you should be sure to show that error to the customer, re-enable the form, and hide the waiting indicator.
Additionally, stripe.handleCardAction may trigger a 3D Secure authentication challenge. The authentication challenge requires a context switch that can be hard to follow on a screen-reader. Ensure that your form is accessible by ensuring that success or error messages are clearly read out.
Payment Intents
Collect bank account details for payment
stripe.collectBankAccountForPayment(options)
Use stripe.collectBankAccountForPayment in the Accept a payment flow for the ACH Direct Debit payment method to collect the customer’s bank account in your payment form. When called, it will automatically load an on-page modal UI to collect bank account details and verification, and attach the PaymentMethod to the PaymentIntent.
Method parameters
options required object
Data to be sent with the request.
Hide options properties
clientSecret required string
params required object
Hide params properties
payment_method_type required string
The payment method type for the bank account details (e.g. us_bank_account)
payment_method_data required object
Payment method specific data to be sent with the request
Hide payment_method_data properties
billing_details required Object
Hide billing_details properties
name required string
The customer's name. The first and last name must be at minimum 2 characters each.
email string
When the stripe.collectBankAccountForPayment completes successfully, it returns a PaymentIntent. If the customer provided their account, the PaymentIntent is in the requires_confirmation state. If the customer closed the dialog without providing their account, the PaymentIntent is in the requires_payment_method state. Use stripe.confirmUsBankAccountPayment to complete the process.
Collect bank account details for payment
Setup Intents
Introduction
Setup Intents
Confirm a SetupIntent
stripe.confirmSetup(options)
Use stripe.confirmSetup to confirm a SetupIntent using data collected by the Payment Element, or with manually provided data via confirmParams. When called, stripe.confirmSetup will attempt to complete any required actions, such as authenticating your user by displaying a 3DS dialog or redirecting them to a bank authorization page. Your user will be redirected to the return_url you pass once the authorization is complete.
Method parameters
options required object
Hide options properties
elements Conditionally required object
clientSecret Conditionally required string
confirmParams object
Parameters that will be passed on to the Stripe API. Refer to the Setup Intents API for a full list of parameters.
Hide confirmParams properties
return_url required string
The url your customer will be directed to after they complete authentication.
confirmation_token string
If collected previously, the ID of the ConfirmationToken to use to confirm this SetupIntent. This is mutually exclusive with the elements parameter.
payment_method_data object
When you call stripe.confirmSetup, payment details are collected from the Element and passed to the SetupIntents confirm endpoint as the payment_method_data parameter. You can also include additional payment_method_data fields, which will be merged with the data collected from the Element.
Hide payment_method_data properties
billing_details object
The customer's billing_details. Details collected by Elements will override values passed here. Billing fields that are omitted in the Payment Element via the fields option required.
allow_redisplay 'unspecified' | 'always' | 'limited'
Indicates whether the payment method can be displayed to the customer in subsequent checkout flows. The value passed here will override the allow_redisplay determined by the provided elements parameter.
expand array
redirect 'always' | 'if_required'
By default, stripe.confirmSetup will always redirect to your return_url after a successful confirmation. If you set redirect: "if_required", then stripe.confirmSetup will only redirect if your user chooses a redirect-based payment method.
Note: Setting if_required requires that you handle successful confirmations for redirect-based and non-redirect based payment methods separately. When a non-redirect based payment method is successfully confirmed, stripe.confirmSetup will resolve with a {setupIntent} object.
stripe.confirmSetup will return a Promise. For payments that don't require a redirect, the Promise resolves to the updated Intent. After a successful authorization, Stripe redirects your user to the return_url you provided before the Promise resolves. For payments that don't require a redirect, the Promise resolves to the updated Intent.
If the authorization fails, the Promise resolves with an {error} object that describes the failure. If the error type is either card_error or validation_error, directly display the error message in error.message to your user. If the error type is `invalid_request_error, you might have an invalid request or 3DS authentication failures.
For some payment methods, such as iDEAL or Afterpay/Clearpay, Stripe first redirects your user to an intermediate page to authorize the payment. If iDEAL or Afterpay/Clearpay fail to authorize the payment, Stripe redirects the user to your return_url, and the SetupIntent has a status of requires_payment_method. In this case, attempt to recollect payment from the user.
The stripe.confirmSetup might take several seconds to complete. During that time, disable your form from being resubmitted and show a waiting indicator, such as a spinner. If you receive an error result, show this error to the user, re-enable the form, and hide the waiting indicator.
Setup Intents
Confirm a SetupIntent by payment method
Confirm a SetupIntent by payment method
Below are a number of methods used to confirm a SetupIntent for a specific payment method type.
Setup Intents
Confirm a SetupIntent by payment method
Confirm card setup
stripe.confirmCardSetup(clientSecret,data?,options?)
Use stripe.confirmCardSetup in the Setup Intents API flow when the customer submits your payment form. When called, it will confirm the SetupIntent with data you provide and carry out 3DS or other next actions if they are required.
When you confirm a SetupIntent, it needs to have an attached PaymentMethod. In addition to confirming the SetupIntent, this method can automatically create and attach a new PaymentMethod for you. It can also be called with an existing PaymentMethod, or if you have already attached a PaymentMethod you can call this method without needing to provide any additional data. These use cases are detailed in the sections that follow.
Method parameters
clientSecret required string
data optional object
Data to be sent with the request. Refer to the Setup Intents API for a full list of parameters.
Hide data properties
payment_method recommended string | object
Either the id of an existing PaymentMethod, or an object containing data to create a PaymentMethod with. See the use case sections below for details.
return_url string
If you are handling next actions yourself, pass in a return_url. If the subsequent action is redirect_to_url, this URL will be used on the return path for the redirect.
options optional object
An options object to control the behavior of this method.
stripe.confirmCardSetup will return a Promise which resolves with a result object. This object has either:
result.setupIntent: the successful SetupIntent.result.error: an error. Refer to the API reference for all possible errors.
Note that stripe.confirmCardSetup may take several seconds to complete. During that time, you should disable your form from being resubmitted and show a waiting indicator like a spinner. If you receive an error result, you should be sure to show that error to the customer, re-enable the form, and hide the waiting indicator.
Additionally, stripe.confirmCardSetup may trigger a 3D Secure authentication challenge. This will be shown in a modal dialog and may be confusing for customers using assistive technologies like screen readers. You should make your form accessible by ensuring that success or error messages are clearly read out after this method completes.
Confirm card setup
with payment data from an Element
Use stripe.confirmCardSetup with payment data from an Element by passing a card or cardNumber Element to payment_method[card]. The new PaymentMethod will be created with data collected by the Element and will be used to confirm the SetupIntent.
Data argument properties
payment_method required object
Pass an object to confirm using data collected by a card or cardNumber Element.
Hide payment_method properties
card required Element
Uses the provided card or cardNumber Element for confirmation.
billing_details recommended object
Confirm card setup
with an existing payment method
Use stripe.confirmCardSetup with an existing PaymentMethod by passing its id to payment_method. The PaymentMethod will be used to confirm the SetupIntent.
Data argument properties
payment_method required string
Confirm with existing payment method
Confirm card setup
with an existing token
For backwards compatibility, you can convert an existing Token into a PaymentMethod with stripe.confirmCardSetup by passing the Token to payment_method[card][token]. The newly created PaymentMethod will be used to confirm the PaymentMethod.
Data argument properties
payment_method required object
Pass an object to confirm using an existing token.
Hide payment_method properties
card required object
Hide card properties
token required string
Converts the provided token into a PaymentMethod to use for confirmation.
billing_details recommended object
Confirm with existing token
Confirm card setup
with an attached PaymentMethod
If you have already attached a PaymentMethod to this SetupIntent, then you can confirm the SetupIntent using stripe.confirmCardSetup without passing in any additional data.
Confirm with an attached PaymentMethod
Setup Intents
Confirm a SetupIntent by payment method
Confirm an ACH Direct Debit setup
stripe.confirmUsBankAccountSetup(clientSecret,data?)
Use stripe.confirmUsBankAccountSetup in the Save bank details flow for the ACH Direct Debit payment method to record the customer’s authorization for future payments.
When you confirm a SetupIntent, it needs to have an attached PaymentMethod. We suggest using stripe.collectBankAccountForSetup, which automatically collects bank account details and attaches a PaymentMethod. You may also choose to reuse an existing PaymentMethod or manually collect bank account details using the data parameter. These use cases are detailed in the sections that follow.
Method parameters
clientSecret required string
data optional object
Data to be sent with the request. Refer to the Setup Intents API for a full list of parameters.
Hide data properties
payment_method object | string
The id of an existing PaymentMethod or an object of collected data. See use cases below for details.
stripe.confirmUsBankAccountSetup will return a Promise which resolves with a result object. This object has either:
Confirm an ACH Direct Debit setup
Confirm an ACH Direct Debit setup
with an existing PaymentMethod
If you have already created a PaymentMethod, you can pass its id to payment_method when calling stripe.confirmUsBankAccountSetup.
Data argument properties
payment_method required string
Confirm with an existing PaymentMethod
Confirm an ACH Direct Debit setup
with an attached PaymentMethod
If you have successfully called stripe.collectBankAccountForSetup or attached a PaymentMethod to this SetupIntent already, then you can confirm the SetupIntent without passing in any additional data.
Confirm with an attached PaymentMethod
Confirm an ACH Direct Debit setup
with self collected bank account information
If you already know the customer’s bank account information, or want to collect it yourself, you can pass them in directly to create a new PaymentMethod and confirm the SetupIntent.
Data argument properties
payment_method required object
Pass an object to confirm using data collected.
Hide payment_method properties
billing_details required Object
Hide billing_details properties
name required string
The customer's name. The first and last name must be at minimum 2 characters each.
email string
us_bank_account required Object
Hide us_bank_account properties
account_number required string
The customer’s bank account number.
routing_number required string
The routing number of the customer’s bank.
account_holder_type required string
Account holder type: individual or company.
account_type string
Account type: checkings or savings. Defaults to checking if omitted.
Confirm with bank account information
Setup Intents
Confirm a SetupIntent by payment method
Confirm an ACSS Debit setup
stripe.confirmAcssDebitSetup(clientSecret,data?,options?)
Use stripe.confirmAcssDebitSetup in the Save bank details flow to set up a Canadian pre-authorized debit payment method for future payments. When called, it will automatically pop up a modal to collect bank account details and verification, accept the mandate, and confirm the SetupIntent when the user submits the form. Note that there are some additional requirements to this flow that are not covered in this reference. Refer to our integration guide for more details.
When you confirm a SetupIntent, it needs to have an attached PaymentMethod. stripe.confirmAcssDebitSetup automatically creates a new PaymentMethod for you when your customer completes the modal UI. It can also be called with an existing PaymentMethod, which will load the modal UI to collect a new mandate agreement. These use cases are detailed in the sections that follow.
Method parameters
clientSecret required string
data optional object
Data to be sent with the request. Refer to the Setup Intents API for a full list of parameters.
Hide data properties
payment_method object | string
The id of an existing PaymentMethod or an object of collected data. See use cases below for details.
options optional object
An options object to control the behavior of this method.
Hide options properties
skipMandate boolean
Set this to true if you want to skip displaying the mandate confirmation.
stripe.confirmAcssDebitSetup will return a Promise which resolves with a result object. This object has either:
Note that stripe.confirmAcssDebitSetup may take several seconds to complete. During that time, disable your form from being resubmitted and show a waiting indicator like a spinner. If you receive an error result, show it to the customer, re-enable the form, and hide the waiting indicator.
Confirm Canadian pre-authorized debit setup
Confirm a Canadian pre-authorized debit setup
with a new PaymentMethod
You can pass in the customer’s billing details to create a new PaymentMethod and confirm the SetupIntent. You are required to collect and include the customer’s name and email address. This method loads an on-page modal UI that handles bank account details collection and verification, presents a hosted mandate agreement and collects authorization for you.
Data argument properties
payment_method required object
Pass an object to confirm using data collected.
Hide payment_method properties
billing_details required Object
Hide billing_details properties
name required string
The customer's name. The first and last name must be at minimum 2 characters each.
email required string
Confirm with a new PaymentMethod
Confirm a Canadian pre-authorized debit setup
with an existing PaymentMethod
If you have already created a PaymentMethod, you can pass its id to payment_method when calling stripe.confirmAcssDebitSetup. This method loads an on-page modal UI that only presents a hosted mandate agreement and collects authorization for you.
Data argument properties
payment_method required string
Confirm with an existing PaymentMethod
Confirm a Canadian pre-authorized debit setup
with an attached PaymentMethod
If you have already attached a PaymentMethod to this SetupIntent, then you can confirm the SetupIntent without passing in any additional data. This method loads an on-page modal UI that only presents a hosted mandate agreement and collects authorization for you.
Confirm with an attached PaymentMethod
Confirm a Canadian pre-authorized debit setup
with self collected bank account information
If you already know the customer’s bank account information, or want to collect it yourself, you can pass them in directly to create a new PaymentMethod and confirm the SetupIntent. In this case, this method does not load the on-page modal UI, so you will need to build your own mandate agreement page.
Data argument properties
payment_method required object
Pass an object to confirm using data collected.
Hide payment_method properties
billing_details required Object
Hide billing_details properties
name required string
The customer's name. The first and last name must be at minimum 2 characters each.
email required string
acss_debit required Object
Hide acss_debit properties
account_number required string
The customer’s bank account number.
institution_number required string
The institution number of the customer’s bank.
transit_number required string
The transit number of the customer’s bank.
Confirm with bank account information
Confirm a Canadian pre-authorized debit setup
with an existing PaymentMethod but skip mandate display
If you have already created a PaymentMethod and built your own mandate agreement page, you can reuse it by passing its id to payment_method when calling stripe.confirmAcssDebitSetup and skip the on-page modal UI at the same time.
Data and options argument paramters
data object
Data to be sent with the request.
Hide data properties
payment_method required string
options object
An options object to control the behavior of this method.
Hide options properties
skipMandate required boolean
Set to true to skip the on-page modal UI.
Confirm with an existing PaymentMethod but skip mandate display
Setup Intents
Confirm a SetupIntent by payment method
Confirm BECS Debit setup
stripe.confirmAuBecsDebitSetup(clientSecret,data?)
Use stripe.confirmAuBecsDebitSetup in the BECS Direct Debit Payments flow when the customer submits your payment form. When called, it will confirm the SetupIntent with data you provide. Note that there are some additional requirements to this flow that are not covered in this reference. Refer to our integration guide for more details.
When you confirm a SetupIntent, it needs to have an attached PaymentMethod. In addition to confirming the SetupIntent, this method can automatically create and attach a new PaymentMethod for you. It can also be called with an existing PaymentMethod, or if you have already attached a PaymentMethod you can call this method without needing to provide any additional data. These use cases are detailed in the sections that follow.
Method parameters
clientSecret required string
data optional object
Data to be sent with the request. Refer to the Setup Intents API for a full list of parameters.
Hide data properties
payment_method recommended object | string
The id of an existing PaymentMethod or an object of collected data. See use cases below for details.
stripe.confirmAuBecsDebitSetup will return a Promise which resolves with a result object. This object has either:
result.setupIntent: the successful SetupIntent.result.error: an error. Refer to the API reference for all possible errors.
Note that stripe.confirmAuBecsDebitSetup may take several seconds to complete. During that time, you should disable your form from being resubmitted and show a waiting indicator like a spinner. If you receive an error result, you should be sure to show that error to the customer, re-enable the form, and hide the waiting indicator.
Confirm BECS Debit setup
with payment data from an Element
Create and attach a new PaymentMethod with stripe.confirmAuBecsDebitSetup by passing an auBankAccount Element to payment_method[au_becs_debit]. The new PaymentMethod will be created with the data collected by the Element and will be used to confirm the SetupIntent. Additionally, to create a BECS Direct Debit PaymentMethod, you are required to collect and include the account holder's name and the customer’s email address.
Data argument properties
payment_method required object
Pass an object to confirm using data collected by an auBankAccount Element.
Hide payment_method properties
au_becs_debit required Element
billing_details required Object
Hide billing_details properties
name required string
email required string
Confirm BECS Debit setup
with an existing payment method
If you have already created a PaymentMethod, you can pass its id to payment_method when calling stripe.confirmAuBecsDebitSetup and it will be used to confirm the SetupIntent.
Data argument properties
payment_method required string
The id of an existing PaymentMethod.
Confirm with existing payment method
Confirm BECS Debit setup
with self collected data
If you already know the customer’s BSB number and bank account number or want to collect it yourself, then you do not need to use the auBankAccount Element. You can pass in the customer’s bank account information directly to create a new PaymentMethod and confirm the SetupIntent. Additionally, to create a BECS Direct Debit PaymentMethod, you are required to collect and include the account holder's name and the customer's email address.
Data argument properties
payment_method required object
Pass an object to confirm using data collected without an Element.
Hide payment_method properties
au_becs_debit required object
An object of self-collected bank account data.
Hide au_becs_debit properties
bsb_number required string
A Bank State Branch (BSB) number.
account_number required string
billing_details required object
Hide billing_details properties
name required string
The account holder's name.
email required string
Confirm with self collected data
Setup Intents
Confirm a SetupIntent by payment method
Confirm Bacs Debit setup
stripe.confirmBacsDebitSetup(clientSecret,data?)
Use stripe.confirmBacsDebitSetup in the Bacs Direct Debit Payments flow when the customer submits your payment form. When called, it will confirm the SetupIntent with data you provide. Note that there are some additional requirements to this flow that are not covered in this reference. Refer to our integration guide for more details.
When you confirm a SetupIntent, it needs to have an attached PaymentMethod. In addition to confirming the SetupIntent, this method can automatically create and attach a new PaymentMethod for you. It can also be called with an existing PaymentMethod, or if you have already attached a PaymentMethod you can call this method without needing to provide any additional data. These use cases are detailed in the sections that follow.
Method parameters
clientSecret required string
data optional object
Data to be sent with the request. Refer to the Setup Intents API for a full list of parameters.
Hide data properties
payment_method recommended object | string
The id of an existing PaymentMethod or an object of collected data. See use cases below for details.
stripe.confirmBacsDebitSetup will return a Promise which resolves with a result object. This object has either:
result.setupIntent: the successful SetupIntent.result.error: an error. Refer to the API reference for all possible errors.
Note that stripe.confirmBacsDebitSetup may take several seconds to complete. During that time, you should disable your form from being resubmitted and show a waiting indicator like a spinner. If you receive an error result, you should be sure to show that error to the customer, re-enable the form, and hide the waiting indicator.
Confirm Bacs Debit setup
with self collected data
You can also pass in the customer’s bank account information directly to create a new PaymentMethod and confirm the SetupIntent. Additionally, to create a Bacs Direct Debit PaymentMethod, you are required to collect and include the account holder's name and the customer's email address.
Data argument properties
payment_method required object
Pass an object to confirm using payment method data.
Hide payment_method properties
bacs_debit required object
An object of self-collected bank account data.
Hide bacs_debit properties
account_number required string
sort_code required string
billing_details required object
Hide billing_details properties
address required string
The account holder's address.
Hide address properties
line1 required string
Line 1 of the account holder's address.
city required string
The account holder's city.
country required string
The account holder's country.
postal_code required string
The account holder's postal code.
name required string
The account holder's name.
email required string
Confirm with self collected data
Confirm Bacs Debit setup
with an existing payment method
If you have already created a PaymentMethod, you can pass its id to payment_method when calling stripe.confirmBacsDebitSetup and it will be used to confirm the SetupIntent.
Data argument properties
payment_method required string
The id of an existing PaymentMethod.
Confirm with existing payment method
Setup Intents
Confirm a SetupIntent by payment method
Confirm Cash App Pay setup
stripe.confirmCashappSetup(clientSecret,data?,options?)
Use stripe.confirmCashappSetup in the Save payment details flow for the Cash App Pay payment method to record the customer’s authorization for future payments.
When you confirm a SetupIntent, it needs to have an attached PaymentMethod.
In addition to confirming the SetupIntent, this method can automatically create and attach a new PaymentMethod for you. If you have already attached a PaymentMethod you can call this method without needing to provide any additional data. These use cases are detailed in the sections that follow.
Method parameters
clientSecret required string
data optional object
Data to be sent with the request. Refer to the Setup Intents API for a full list of parameters.
Hide data properties
payment_method object | string
The id of an existing PaymentMethod or an object of collected data. See use cases below for details.
return_url required string
The url your customer will be directed to after they complete authentication.
options optional object
An options object to control the behavior of this method.
By default, stripe.confirmCashappSetup will display Cash App Pay QR code in desktop web app, or trigger a redirect in mobile web app. If there is an error, or when handling next actions manually by using the handleActions: false option, it will return a Promise which resolves with a result This object has either:
Note that stripe.confirmCashappSetup may take several seconds to complete. During that time, you should disable your form from being resubmitted and show a waiting indicator like a spinner. If you receive an error result, you should be sure to show that error to the customer, re-enable the form, and hide the waiting indicator.
Confirm a Cash App Pay setup
Confirm an Cash App Pay setup
Without an existing payment method
If you have not already created a PaymentMethod, you can pass payment method parameters, and the newly created PaymentMethod will be used to confirm the SetupIntent.
Data argument properties
return_url required string
The url your customer will be directed to after they complete authentication.
Confirm with bank account information
Confirm an Cash App Pay setup
with an existing PaymentMethod
If you have already created a PaymentMethod, you can pass its id to payment_method when calling stripe.confirmCashappSetup.
Data argument properties
payment_method required string
return_url required string
The url your customer will be directed to after they complete authentication.
Confirm with an existing PaymentMethod
Confirm an Cash App Pay setup
with an attached PaymentMethod
If you have already attached a return_url and a PaymentMethod to this SetupIntent, then you can confirm without passing in any additional data.
Confirm with an attached PaymentMethod
Setup Intents
Confirm a SetupIntent by payment method
Confirm iDEAL setup
stripe.confirmIdealSetup(clientSecret,data?,options?)
Use stripe.confirmIdealSetup in the Set up future payments flow to use iDEAL bank details to set up a SEPA Direct Debit payment method for future payments. When called, it will confirm a SetupIntent with data you provide, and it will automatically redirect the customer to authorize the transaction. Once authorization is complete, the customer will be redirected back to your specified return_url. Note that there are some additional requirements to this flow that are not covered in this reference. Refer to our integration guide for more details.
When you confirm a SetupIntent, it needs to have an attached PaymentMethod. In addition to confirming the SetupIntent, this method can automatically create and attach a new PaymentMethod for you. It can also be called with an existing PaymentMethod, or if you have already attached a PaymentMethod you can call this method without needing to provide any additional data. These use cases are detailed in the sections that follow.
Method parameters
clientSecret required string
data optional object
Data to be sent with the request. Refer to the Setup Intents API for a full list of parameters.
Hide data properties
payment_method recommended object | string
The id of an existing PaymentMethod or an object of collected data. See use cases below for details.
return_url recommended string
The url your customer will be directed to after they complete authentication.
options optional object
An options object to control the behavior of this method.
stripe.confirmIdealSetup will return a Promise which resolves with a result object. This object has either:
result.setupIntent: the successful SetupIntent.result.error: an error. Refer to the API reference for all possible errors.
Note that stripe.confirmIdealSetup may take several seconds to complete. During that time, you should disable your form from being resubmitted and show a waiting indicator like a spinner. If you receive an error result, you should be sure to show that error to the customer, re-enable the form, and hide the waiting indicator.
Confirm iDEAL setup
with payment data from an Element
Create and attach a new SEPA Direct Debit PaymentMethod with stripe.confirmIdealSetup by passing an idealBank Element to payment_method[ideal]. The new PaymentMethod will be created with the data collected by the Element and will be used to confirm the SetupIntent. Additionally, to create a SEPA Direct Debit PaymentMethod, you are required to collect and include the customer’s name and email address.
Data argument properties
payment_method required object
Pass an object to confirm using data collected by an idealBank Element.
Hide payment_method properties
ideal required Element
billing_details required object
Hide billing_details properties
name required string
email required string
return_url recommended string
The url your customer will be directed to after they complete authentication.
Confirm iDEAL setup
with an existing payment method
If you have already created a PaymentMethod, you can pass its id to payment_method when calling stripe.confirmIdealSetup and it will be used to confirm the SetupIntent.
Data argument properties
payment_method required string
The id of an existing PaymentMethod.
return_url recommended string
The url your customer will be directed to after they complete authentication.
Confirm with existing payment method
Confirm iDEAL setup
with self collected data
If you already know the customer’s bank or want to collect it yourself, then you do not need to use the idealBank Element. You can pass in the customer’s bank code directly to create a new PaymentMethod and confirm the SetupIntent.
Data argument properties
payment_method required object
Pass an object to confirm using data collected by an idealBank Element.
Hide payment_method properties
ideal required object
An object detailing the customer's iDEAL bank.
billing_details required object
Hide billing_details properties
name required string
email required string
return_url recommended string
The url your customer will be directed to after they complete authentication.
Confirm with self collected data
Setup Intents
Confirm a SetupIntent by payment method
Confirm PayPal setup
stripe.confirmPayPalSetup(clientSecret,data?)
Use stripe.confirmPayPalSetup in the PayPal Payments with Setup Intents flow when the customer submits your setup form. When called, it will confirm the SetupIntent, and it will automatically redirect the customer to authorize the setup. Once authorization is complete, the customer will be redirected back to your specified return_url.
Method parameters
clientSecret required string
data optional object
Data to be sent with the request. Refer to the Setup Intents API for a full list of parameters.
Hide data properties
payment_method string | object
The id of an existing PaymentMethod. See the use case sections below for details.
return_url required string
The url your customer will be directed to after they complete authentication.
stripe.confirmPayPalSetup will trigger a redirect when successful. If there is an error, it will return a Promise which resolves with a result object. This object has either:
result.setupIntent: the successful SetupIntent.result.error: an error. Refer to the API reference for all possible errors.
Note that stripe.confirmPayPalSetup may take several seconds to complete. During that time, you should disable your form from being resubmitted and show a waiting indicator like a spinner. If you receive an error result, you should be sure to show that error to the customer, re-enable the form, and hide the waiting indicator.
Confirm a PayPal setup
with a new PaymentMethod
You can confirm the SetupIntent using stripe.confirmPayPalSetup without passing in any additional data. This will automatically create and attach a new PaymentMethod.
Data argument properties
return_url required string
The url your customer will be directed to after they complete authentication.
Confirm with a new PaymentMethod
Confirm a PayPal setup
with an existing payment method
Use stripe.confirmPayPalSetup with an existing PaymentMethod by passing its id to payment_method. The PaymentMethod will be used to confirm the SetupIntent.
Data argument properties
payment_method required string
The id of an existing PaymentMethod.
return_url required string
The url your customer will be directed to after they complete authentication.
Confirm with existing payment method
Confirm a PayPal setup
with an attached PaymentMethod
If you have already attached a PaymentMethod to this SetupIntent, then you can confirm the SetupIntent using stripe.confirmPayPalSetup without passing in any additional data.
Confirm with an attached PaymentMethod
Setup Intents
Confirm a SetupIntent by payment method
Confirm PayTo setup
stripe.confirmPayToSetup(clientSecret,data?,options?)
Use stripe.confirmPayToSetup in the PayTo Payments with Setup Intents flow when the customer submits your setup form. When called, it will confirm the SetupIntent, and send a request for authorization to the customer.
When you confirm a SetupIntent, it needs to have an attached PaymentMethod. In addition to confirming the SetupIntent, this method can automatically create and attach a new PaymentMethod for you. If you've already attached a PaymentMethod, you can call this method without needing to provide any additional data. These use cases are detailed in the sections that follow.
Method parameters
clientSecret required string
data optional object
Data to be sent with the request. Refer to the Setup Intents API for a full list of parameters.
Hide data properties
payment_method string | object
Either the id of an existing PaymentMethod, or an object containing data to create a PaymentMethod with. See the use case sections below for details.
options optional object
An options object to control the behavior of this method.
Hide options properties
handleActions boolean
Set this to false if you want to manually handle polling for SetupIntent updates. Default is true.
By default, stripe.confirmPayToSetup will poll for updates to the SetupIntent. If there's an error, or when handling next_actions manually by using the handleActions: false option, it returns a Promise which resolves with a result object. This object has either:
result.setupIntent: the successful SetupIntent.result.error: an error. Refer to the API reference for all possible errors.
Note that stripe.confirmPayToSetup might take some time to complete while waiting for customers to authorize the PayTo agreement. During that time, you should disable your form from being resubmitted and show a waiting indicator like a spinner. If you receive an error result, you should be sure to show that error to the customer, re-enable the form, and hide the waiting indicator.
Confirm a PayTo setup
with a new PaymentMethod
You can confirm the SetupIntent using stripe.confirmPayToSetup without passing in any additional data. This will automatically create and attach a new PaymentMethod.
Data argument properties
payment_method required object
Pass payment method billing details.
Hide payment_method properties
billing_details required object
The billing_details associated with the payment. The email is required if the customer is paying with PayID.
Hide billing_details properties
email string
name required string
payto required object
The PayTo payment method details associated with the customer's bank account. Either pay_id or account_number and bsb_number must be provided.
Hide payto properties
pay_id string
account_number string
bsb_number string
Confirm with a new PaymentMethod
Confirm a PayTo setup
with an existing payment method
Use stripe.confirmPayToSetup with an existing PaymentMethod by passing its id to payment_method. The PaymentMethod will be used to confirm the SetupIntent.
Data argument properties
payment_method required string
The id of an existing PaymentMethod.
Confirm with existing payment method
Confirm a PayTo setup
with an attached PaymentMethod
If you have already attached a PaymentMethod to this SetupIntent, then you can confirm the SetupIntent using stripe.confirmPayToSetup without passing in any additional data.
Confirm with an attached PaymentMethod
Setup Intents
Confirm a SetupIntent by payment method
Confirm SEPA Debit setup
stripe.confirmSepaDebitSetup(clientSecret,data?)
Use stripe.confirmSepaDebitSetup in the SEPA Direct Debit with Setup Intents flow when the customer submits your payment form. When called, it will confirm the SetupIntent with data you provide. Note that there are some additional requirements to this flow that are not covered in this reference. Refer to our integration guide for more details.
When you confirm a SetupIntent, it needs to have an attached PaymentMethod. In addition to confirming the SetupIntent, this method can automatically create and attach a new PaymentMethod for you. It can also be called with an existing PaymentMethod, or if you have already attached a PaymentMethod you can call this method without needing to provide any additional data. These use cases are detailed in the sections that follow.
Method parameters
clientSecret required string
data optional object
Data to be sent with the request. Refer to the Setup Intents API for a full list of parameters.
Hide data properties
payment_method recommended object | string
The id of an existing PaymentMethod or an object of collected data. See use cases below for details.
stripe.confirmSepaDebitSetup will return a Promise which resolves with a result object. This object has either:
result.setupIntent: the successful SetupIntent.result.error: an error. Refer to the API reference for all possible errors.
Note that stripe.confirmSepaDebitSetup may take several seconds to complete. During that time, you should disable your form from being resubmitted and show a waiting indicator like a spinner. If you receive an error result, you should be sure to show that error to the customer, re-enable the form, and hide the waiting indicator.
Confirm SEPA Debit setup
with payment data from an Element
Create and attach a new PaymentMethod with stripe.confirmSepaDebitSetup by passing an iban Element to payment_method[sepa_debit]. The new PaymentMethod will be created with the data collected by the Element and will be used to confirm the SetupIntent. Additionally, to create a SEPA Direct Debit PaymentMethod, you are required to collect and include the customer’s name and email address.
Data argument properties
payment_method required object
Pass an object to confirm using data collected by an iban Element.
Hide payment_method properties
sepa_debit required Element
billing_details required Object
Hide billing_details properties
name required string
email required string
Confirm SEPA Debit setup
with an existing payment method
If you have already created a PaymentMethod, you can pass its id to payment_method when calling stripe.confirmSepaDebitSetup and it will be used to confirm the SetupIntent.
Data argument properties
payment_method required string
The id of an existing PaymentMethod.
Confirm with existing payment method
Confirm SEPA Debit setup
with self collected data
If you already know the customer’s IBAN account number or want to collect it yourself, then you do not need to use the iban Element. You can pass in the customer’s account number directly to create a new PaymentMethod and confirm the SetupIntent. Additionally, to create a SEPA Direct Debit PaymentMethod, you are required to collect and include the customer’s name and email address.
Data argument properties
payment_method required object
Pass an object to confirm using data collected by an iban Element.
Hide payment_method properties
sepa_debit required object
An object of self-collected IBAN data.
Hide sepa_debit properties
billing_details required object
Hide billing_details properties
name required string
email required string
Confirm with self collected data
Setup Intents
Confirm a SetupIntent by payment method
Confirm Sofort setup
stripe.confirmSofortSetup(clientSecret,data?,options?)
Use stripe.confirmSofortSetup in the Set up future payments flow to use SOFORT bank details to set up a SEPA Direct Debit payment method for future payments. When called, it will confirm a SetupIntent with data you provide, and it will automatically redirect the customer to authorize the transaction. Once authorization is complete, the customer will be redirected back to your specified return_url. Note that there are some additional requirements to this flow that are not covered in this reference. Refer to our integration guide for more details.
When you confirm a SetupIntent, it needs to have an attached PaymentMethod. In addition to confirming the SetupIntent, this method can automatically create and attach a new PaymentMethod for you. It can also be called with an existing PaymentMethod, or if you have already attached a PaymentMethod you can call this method without needing to provide any additional data. These use cases are detailed in the sections that follow.
Method parameters
clientSecret required string
data optional object
Data to be sent with the request. Refer to the Setup Intents API for a full list of parameters.
Hide data properties
payment_method recommended object | string
The id of an existing PaymentMethod or an object of collected data. See use cases below for details.
return_url recommended string
The url your customer will be directed to after they complete authentication.
options optional object
An options object to control the behavior of this method.
stripe.confirmSofortSetup will return a Promise which resolves with a result object. This object has either:
result.setupIntent: the successful SetupIntent.result.error: an error. Refer to the API reference for all possible errors.
Note that stripe.confirmSofortSetup may take several seconds to complete. During that time, you should disable your form from being resubmitted and show a waiting indicator like a spinner. If you receive an error result, you should be sure to show that error to the customer, re-enable the form, and hide the waiting indicator.
Confirm Sofort setup
with an existing payment method
If you have already created a PaymentMethod, you can pass its id to payment_method when calling stripe.confirmSofortSetup and it will be used to confirm the SetupIntent.
Data argument properties
payment_method required string
The id of an existing PaymentMethod.
return_url recommended string
The url your customer will be directed to after they complete authentication.
Confirm with existing payment method
Confirm Sofort setup
with self collected data
Your customer's name, email and the country of their bank are required for the SOFORT authorization to succeed. You can pass in these properties directly to create a new PaymentMethod and confirm the SetupIntent.
Data argument properties
payment_method required object
Pass an object to confirm with the customer's name and email.
Hide payment_method properties
country required string
The country code where customer's bank is located.
billing_details required object
Hide billing_details properties
name required string
email required string
return_url recommended string
The url your customer will be directed to after they complete authentication.
Confirm with self collected data
Setup Intents
Retrieve a SetupIntent
stripe.retrieveSetupIntent(clientSecret)
Method parameters
clientSecret required string
This method returns a Promise which resolves with a result object. This object has either:
result.setupIntent: a SetupIntent was retrieved successfully.result.error: an error. Refer to the API reference for all possible errors.
Setup Intents
Verify with micro-deposits for setup
stripe.verifyMicrodepositsForSetup(clientSecret,data?)
Method parameters
clientSecret required string
data optional object
Data to be sent with the request.
Hide data properties
amounts array
An array of two positive integers, in cents, equal to the values of the micro-deposits sent to the bank account.
descriptor_code string
A six-character code starting with SM present in the microdeposit sent to the bank account.
stripe.verifyMicrodepositsForSetup will return a Promise which resolves with a result object. This object has either:
Verification can fail for several reasons. The failure may happen synchronously as a direct error response, or asynchronously through a payment_intent.payment_failed webhook event. Refer to our integration guide for more details.
Verify with micro-deposits for setup
Setup Intents
Handle a next action
stripe.handleNextAction(options)
Use stripe.handleNextAction in the finalizing payments on the server flow to finish confirmation of a SetupIntent with the requires_action status. It will throw an error if the SetupIntent has a different status.
Depending on the payment method and required action, the customer may be temporarily redirected from your site and brought back to the return_url parameter provided when the SetupIntent is confirmed.
This method returns a Promise which resolves with a result object. This object has either:
result.setupIntent: a SetupIntent with the processing or succeeded status.result.error: an error. Refer to the API reference for all possible errors.
Note that stripe.handleNextAction may take several seconds to complete. During that time, you should disable your form from being resubmitted and show a waiting indicator like a spinner. If you receive an error result, you should be sure to show that error to the customer, re-enable the form, and hide the waiting indicator.
Additionally, stripe.handleNextAction may trigger a 3D Secure authentication challenge. The authentication challenge requires a context switch that can be hard to follow on a screen-reader. Ensure that your form is accessible by ensuring that success or error messages are clearly read out.
Setup Intents
Collect bank account details for setup
stripe.collectBankAccountForSetup(options)
Use stripe.collectBankAccountForSetup in the Save bank details flow for the ACH Direct Debit payment method to collect the customer’s bank account in your payment form. When called, it will automatically load an on-page modal UI to collect bank account details and verification, and attach the PaymentMethod to the SetupIntent.
Method parameters
options required object
Data to be sent with the request.
Hide options properties
clientSecret required string
params required object
Hide params properties
payment_method_type required string
The payment method type for the bank account details (e.g. us_bank_account)
payment_method_data required object
Payment method specific data to be sent with the request
Hide payment_method_data properties
billing_details required Object
Hide billing_details properties
name required string
The customer's name. The first and last name must be at minimum 2 characters each.
email string
When the stripe.collectBankAccountForSetup completes successfully, it returns a SetupIntent. If the customer provided their account, the SetupIntent is in the requires_confirmation state. If the customer closed the dialog without providing their account, the SetupIntent is in the requires_payment_method state. Use stripe.confirmUsBankAccountSetup to complete the process.
Collect bank account details for setup
The Payment Request object
Introduction
The Payment Request object
A PaymentRequest object is used to collect payment information through an interface controlled and styled by the browser itself (i.e., not by you or your page).
See the Payment Request Button Element quickstart for a high-level overview of when you’d want to do this.
The Payment Request object
Create a PaymentRequest object
stripe.paymentRequest(options)
Use stripe.paymentRequest to create a PaymentRequest object. Creating a PaymentRequest requires that you configure it with an options object.
In Safari, stripe.paymentRequest uses Apple Pay, and in other browsers it uses the Payment Request API standard.
Method parameters
options required object
A set of options to create this PaymentRequest instance with. These options can be updated using paymentRequest.update.
Hide options properties
country required string
The two-letter country code of your Stripe account (e.g., US).
currency required string
Three character currency code (e.g., usd).
total required PaymentItem
A PaymentItem object. This PaymentItem is shown to the customer in the browser’s payment interface.
displayItems array
An array of PaymentItem objects. These objects are shown as line items in the browser’s payment interface. Note that the sum of the line item amounts does not need to add up to the total amount above.
requestPayerName recommended boolean
By default, the browser‘s payment interface only asks the customer for actual payment information. A customer name can be collected by setting this option to true. This collected name will appears in the PaymentResponse object.
We highly recommend you collect name as this also results in collection of billing address for Apple Pay. The billing address can be used to perform address verification and block fraudulent payments. For all other payment methods, the billing address is automatically collected when available.
requestPayerEmail boolean
requestPayerPhone boolean
requestShipping boolean
Collect shipping address by setting this option to true. The address appears in the PaymentResponse.
You must also supply a valid [ShippingOptions] to the shippingOptions property. This can be up front at the time stripe.paymentRequest is called, or in response to a shippingaddresschange event using the updateWith callback.
shippingOptions array
An array of ShippingOption objects. The first shipping option listed appears in the browser payment interface as the default option.
disableWallets array
An array of wallet strings. Can be one or more of applePay, googlePay, link, and browserCard. Use this option to disable Apple Pay, Google Pay, Link, and/or browser-saved cards.
applePay object
Specify Apple Pay specific options. These are passed through to the Apple Pay API.
Hide applePay properties
recurringPaymentRequest object
Hide recurringPaymentRequest properties
paymentDescription required string
managementURL required string
regularBilling required object
Hide regularBilling properties
amount required number
label required string
recurringPaymentStartDate Date
recurringPaymentEndDate Date
recurringPaymentIntervalUnit 'year' | 'month' | 'day' | 'hour' | 'minute'
recurringPaymentIntervalCount number
trialBilling object
Hide trialBilling properties
amount required number
label required string
recurringPaymentStartDate Date
recurringPaymentEndDate Date
recurringPaymentIntervalUnit 'year' | 'month' | 'day' | 'hour' | 'minute'
recurringPaymentIntervalCount number
billingAgreement string
deferredPaymentRequest object
Hide deferredPaymentRequest properties
paymentDescription required string
managementURL required string
deferredBilling required object
Hide deferredBilling properties
amount required number
label required string
deferredPaymentDate required Date
billingAgreement string
freeCancellationDate Date
If set, you must also supply a freeCancellationDateTimeZone.
freeCancellationDateTimeZone string
If set, you must also supply a freeCancellationDate.
These are tz timezones such as America/Los_Angeles, Europe/Dublin, and Asia/Singapore.
automaticReloadPaymentRequest object
Hide automaticReloadPaymentRequest properties
paymentDescription required string
managementURL required string
automaticReloadBilling required object
Hide automaticReloadBilling properties
amount required number
label required string
automaticReloadPaymentThresholdAmount required number
billingAgreement string
cardFunding 'supportsDebit' | 'supportsCredit'
By default, Apple Pay allows both credit and debit cards.
You can specify if you only want to support one type of card with either 'supportsDebit' or 'supportsCredit'.
onBehalfOf Connect only string
The Stripe account ID which is the business of record. See use cases to determine if this option is relevant for your integration. This should match the on_behalf_of provided on the Intent used when confirming payment.
stripe.paymentRequest abstracts over a number of implementation details to work uniformly across Apple Pay and the Payment Request browser standard. In particular, under the hood we set supportedNetworks to its most permissive setting, dynamically accounting for country and platform. It is currently not possible to override this and make supportedNetworks be more restrictive.
Create a PaymentRequestObject
The Payment Request object
Check if a payment can be made
paymentRequest.canMakePayment()
Returns a Promise that resolves with an object detailing if an enabled wallet is ready to pay. If no wallet is available, it resolves with null. The resolution object has the properties in the table below.
NOTE: The paymentRequestButton element automatically shows the correct wallet branding. You shouldn't need to inspect the return object's properties unless you are building your own custom button.
Return object properties
applePay optional boolean
true if Apple Pay wallet is ready to pay. In this case:
paymentRequestButton Element will show as a branded Apple Pay button automatically.- When using a custom button, you‘ll want to show a button that conforms to the Apple Pay Human Interface Guidelines.
googlePay optional boolean
true if Google Pay wallet is ready to pay. In this case:
paymentRequestButton Element will show as a branded Google Pay button automatically.- When using a custom button, you'll want to show a button that conforms to the Google Pay Brand Guidelines.
link optional boolean
true if Link wallet is ready to pay. In this case:
paymentRequestButton Element will show as a branded Link button automatically.- Link is not supported in custom button configurations.
canMakePayment resolves to null outside the following supported cases:
- Safari 10.1+ (desktop and mobile)
- with a saved Apple Pay card
- or when in a Private Browsing window
- or when the “Allow websites to check if Apple Pay is set up” preference is disabled
- Chrome 61+ (desktop and mobile)
- with a saved Google Pay card
- or when the browser has a saved card (i.e. autofill)
For more information, see Testing your integration.
paymentRequest.canMakePayment
The Payment Request object
Show the payment request interface
Shows the browser’s payment interface. When using the paymentRequestButton Element, this is called for you automatically. This method must be called as the result of a user interaction (for example, in a click handler).
Show the payment request interface
The Payment Request object
Update a PaymentRequest object
paymentRequest.update(options)
PaymentRequest instances can be updated with an options object. Available options are documented below.
paymentRequest.update can only be called when the browser payment interface is not showing. Listen to the click and cancel events to detect if the payment interface has been initiated. To update the PaymentRequest right before the payment interface is initiated, call paymentRequest.update in your click event handler.
Method parameters
options required object
A set of options to update this PaymentRequest instance with.
Hide options properties
currency string
Three character currency code (e.g., usd).
total object
A PaymentItem object. This PaymentItem is shown to the customer in the browser’s payment interface.
displayItems array
An array of PaymentItem objects. These payment items are shown as line items in the browser’s payment interface. Note that the sum of the line item amounts does not need to add up to the total amount above.
shippingOptions array
An array of ShippingOption objects. The first shipping option listed appears in the browser payment interface as the default option.
applePay object
Specify Apple Pay specific options. These are passed through to the Apple Pay API.
Hide applePay properties
recurringPaymentRequest object
Hide recurringPaymentRequest properties
paymentDescription required string
managementURL required string
regularBilling required object
Hide regularBilling properties
amount required number
label required string
recurringPaymentStartDate Date
recurringPaymentEndDate Date
recurringPaymentIntervalUnit 'year' | 'month' | 'day' | 'hour' | 'minute'
recurringPaymentIntervalCount number
trialBilling object
Hide trialBilling properties
amount required number
label required string
recurringPaymentStartDate Date
recurringPaymentEndDate Date
recurringPaymentIntervalUnit 'year' | 'month' | 'day' | 'hour' | 'minute'
recurringPaymentIntervalCount number
billingAgreement string
deferredPaymentRequest object
Hide deferredPaymentRequest properties
paymentDescription required string
managementURL required string
deferredBilling required object
Hide deferredBilling properties
amount required number
label required string
deferredPaymentDate required Date
billingAgreement string
freeCancellationDate Date
If set, you must also supply a freeCancellationDateTimeZone.
freeCancellationDateTimeZone string
If set, you must also supply a freeCancellationDate.
These are tz timezones such as America/Los_Angeles, Europe/Dublin, and Asia/Singapore.
automaticReloadPaymentRequest object
Hide automaticReloadPaymentRequest properties
paymentDescription required string
managementURL required string
automaticReloadBilling required object
Hide automaticReloadBilling properties
amount required number
label required string
automaticReloadPaymentThresholdAmount required number
billingAgreement string
cardFunding 'supportsDebit' | 'supportsCredit'
By default, Apple Pay allows both credit and debit cards.
You can specify if you only want to support one type of card with either 'supportsDebit' or 'supportsCredit'.
The Payment Request object
Listen to PaymentRequest events
PaymentRequest events
PaymentRequest instances emit several different types of events.
The Payment Request object
Listen to PaymentRequest events
Token event
paymentRequest.on('token',handler)
Stripe.js automatically creates a Token after the customer is done interacting with the browser’s payment interface. To access the created Token, listen for this event.
Method parameters
event required string
The name of the event. In this case, token.
handler required function
A callback function that will be called with a PaymentResponse object when the event is fired. The PaymentResponse object will contain a token field.
The Payment Request object
Listen to PaymentRequest events
PaymentMethod event
paymentRequest.on('paymentmethod',handler)
Stripe.js automatically creates a PaymentMethod after the customer is done interacting with the browser’s payment interface. To access the created PaymentMethod, listen for this event.
Method parameters
event required string
The name of the event. In this case, paymentmethod.
handler required function
A callback function that will be called with a PaymentResponse object when the event is fired. The PaymentResponse object will contain a paymentMethod field.
Handle 'paymentmethod' event
The Payment Request object
Listen to PaymentRequest events
Source event
paymentRequest.on('source',handler)
Stripe.js automatically creates a Source after the customer is done interacting with the browser’s payment interface. To access the created source, listen for this event.
Method parameters
event required string
The name of the event. In this case, source.
handler required function
A callback function that will be called with a PaymentResponse object when the event is fired. The PaymentResponse object will contain a source field.
The Payment Request object
Listen to PaymentRequest events
Cancel event
paymentRequest.on('cancel',handler)
The cancel event is emitted from a PaymentRequest when the browser‘s payment interface is dismissed.
Note that in some browsers, the payment interface may be dismissed by the customer even after they authorize the payment. This means that you may receive a cancel event on your PaymentRequest object after receiving a token, paymentmethod, or source event. If you’re using the cancel event as a hook for canceling the customer’s order, make sure you also refund the payment that you just created.
Method parameters
event required string
The name of the event. In this case, cancel.
handler required function
A callback function that you will provide that will be called when the event is fired.
The Payment Request object
Listen to PaymentRequest events
Shipping address change event
paymentRequest.on('shippingaddresschange',handler)
The shippingaddresschange event is emitted from a PaymentRequest whenever the customer selects a new address in the browser's payment interface.
Method parameters
event required string
The name of the event. In this case, shippingaddresschange.
handler required function
handler(event) => void is a callback function that you provide that will be called when the event is fired.
When called it will be passed an event object with the following properties:
Hide handler event object properties
updateWith function
updateWith(updateDetails) => void is a Stripe.js provided function that is called with an UpdateDetails object to merge your updates into the current PaymentRequest object. Note that if you subscribe to shippingaddresschange events, then you must call updateWith within 30 seconds.
shippingAddress ShippingAddress
The customer's selected ShippingAddress.
To maintain privacy, browsers may anonymize the shipping address by removing sensitive information that is not necessary to calculate shipping costs. Depending on the country, some fields can be missing or partially redacted. For example, the shipping address in the U.S. may only contain a city, state, and ZIP code. The full shipping address appears in the PaymentResponse object after the purchase is confirmed in the browser’s payment interface
Handle 'shippingaddresschange' event
The Payment Request object
Listen to PaymentRequest events
Shipping option change event
paymentRequest.on('shippingoptionchange',handler)
The shippingoptionchange event is emitted from a PaymentRequest whenever the customer selects a new shipping option in the browser's payment interface.
Method parameters
event required string
The name of the event. In this case, shippingoptionchange.
handler required function
handler(event) => void is a callback function that you provide that will be called when the event is fired.
When called it will be passed an event object with the following properties:
Hide handler event object properties
updateWith function
updateWith(updateDetails) => void is a Stripe.js provided function that is called with an UpdateDetails object to merge your updates into the current PaymentRequest object. Note that if you subscribe to shippingoptionchange events, then you must call updateWith within 30 seconds.
shippingOption ShippingOption
Handle 'shippingoptionchange' event
Confirmation Tokens
Introduction
Confirmation Tokens
ConfirmationTokens transport client-side data collected by Stripe.js to your server. You can use them to confirm a PaymentIntent or SetupIntent on your server.
Confirmation Tokens
Create a ConfirmationToken
stripe.createConfirmationToken(options)
Method parameters
options required object
Hide options properties
elements required object
The Elements instance that was used to create the Express Checkout Element or Payment Element. Calling stripe.createConfirmationToken pulls payment method, billing address, and shipping address data from the Elements instance.
params object
Parameters that will be passed on to the Stripe API.
Hide params properties
payment_method_data object
When you call stripe.createConfirmationToken, payment details are collected from Elements. You can include additional payment_method_data fields, which will be merged with the data collected from Elements. Refer to the PaymentMethod API for a full list of parameters.
Hide payment_method_data properties
billing_details object
Billing information associated with the PaymentMethod that may be used or required by particular types of payment methods.
allow_redisplay 'unspecified' | 'always' | 'limited'
Indicates whether the payment method can be displayed to the customer in subsequent checkout flows. The value passed here will override the allow_redisplay determined by the provided elements parameter.
shipping object
The shipping details for the payment, if collected. You can't specify shipping if mode: 'setup' is specified on the elements object.
Note: When the Address Element in shipping mode is being used, shipping address details are collected from the Address Element. You can also include additional shipping fields, which will be merged with the data collected from the Element, overriding any fields that were also collected by the Address Element.
return_url string
The URL to redirect your customer back to after they authenticate or cancel their payment on the payment method's app or site. If you'd prefer to redirect to a mobile application, you can alternatively supply an application URI scheme. This parameter is only used for cards and other redirect-based payment methods.
stripe.createConfirmationToken(options) returns a Promise which resolves with a result object. This object has either:
result.confirmationToken: a ConfirmationToken was created successfully.result.error: there was an error. This includes client-side validation errors. Refer to the API reference for all possible errors.
Create a ConfirmationToken
Payment Methods
Introduction
Payment Methods
PaymentMethod objects represent your customer's payment instruments. They can be used with PaymentIntents to collect payments or saved to Customer objects to store instrument details for future payments.
Related guides: Payment Methods and More Payment Scenarios.
Payment Methods
Create a PaymentMethod
stripe.createPaymentMethod(paymentMethodData)
Use stripe.createPaymentMethod to convert payment information collected by elements into a PaymentMethod object that you safely pass to your server to use in an API call.
NOTE: In most integrations, you will not need to use this method. Instead, use methods like stripe.confirmCardPayment, which will automatically create a PaymentMethod when you confirm a PaymentIntent.
Method parameters
paymentMethodData required object
Hide paymentMethodData properties
type required string
card Element
A card or cardNumber Element.
au_becs_debit Element
An auBankAccount Element.
fpx Element
fpx[bank] string
netbanking[bank] string
ideal Element
ideal[bank] string
sepa_debit Element
sepa_debit[iban] string
upi[vpa] string
billing_details object
Billing information associated with the PaymentMethod that may be used or required by particular types of payment methods.
stripe.createPaymentMethod(paymentMethodData) returns a Promise which resolves with a result object. This object has either:
result.paymentMethod: a PaymentMethod was created successfully.result.error: there was an error. This includes client-side validation errors. Refer to the API reference for all possible errors.
Payment Methods
Create a PaymentMethod with Elements
stripe.createPaymentMethod(options)
Use stripe.createPaymentMethod to convert payment information collected by elements into a PaymentMethod object that you safely pass to your server to use in an API call.
NOTE: In most integrations, you will not need to use this method. Instead, use methods like stripe.confirmPayment, which will automatically create a PaymentMethod when you confirm a PaymentIntent.
Method parameters
options required object
Hide options properties
elements required object
The Elements instance that was used to create the Payment Element. It will be used to pull payment method and billing address data from.
params object
Parameters that will be passed on to the Stripe API. Refer to the PaymentMethod API for a full list of parameters.
Hide params properties
billing_details object
Billing information associated with the PaymentMethod that may be used or required by particular types of payment methods.
stripe.createPaymentMethod(options) returns a Promise which resolves with a result object. This object has either:
result.paymentMethod: a PaymentMethod was created successfully.result.error: there was an error. This includes client-side validation errors. Refer to the API reference for all possible errors.
Tokens
Introduction
Tokens
Stripe uses tokens to collect sensitive client information without exposing it. When you use the Payment Intents API, the client handles tokenization and you don't have to create tokens yourself.
Stripe.js provides the following method to create Tokens.
Tokens
Create a Token
stripe.createToken(,data?)
Use stripe.createToken to convert information collected by card elements into a single-use Token that you safely pass to your server to use in an API call.
Method parameters
cardElement required Element
The card Element you wish to tokenize data from. If applicable, the Element tokenizes by pulling data from other elements you’ve created on the same instance of Elements—you only need to supply one Element as the parameter.
data optional object
An object containing additional payment information you might have collected.
Although these fields are optional, we highly recommend collecting name and address. This information can be used to perform a number of verifications, such as CVC, ZIP, and address verification. Radar includes built-in rules that can block payments where the ZIP or CVC verifications with the cardholder’s bank failed.
Hide data properties
name recommended string
address_line1 string
address_line2 string
address_city string
address_state string
address_zip string
address_country recommended string
A two character country code (for example, US).
currency string
stripe.createToken returns a Promise which resolves with a result object. This object has either:
result.token: a Token was created successfully.result.error: there was an error. This includes client-side validation errors. Refer to the API reference for all possible errors.
Identity
Show verification modal
stripe.verifyIdentity(clientSecret)
Use stripe.verifyIdentity to display an Identity modal that securely collects verification information.
Method parameters
clientSecret required string
This method returns a Promise which resolves with a result object. If this method fails, the result object will contain a localized error message in the error.message field.
Issuing
Create an ephemeral key nonce
stripe.createEphemeralKeyNonce(options)
Method parameters
options required object
Data to be sent with the request.
Hide options properties
issuingCard required string
The id of an existing Issuing card. The nonce returned by this method can only be used to retrieve this Issuing card.
stripe.createEphemeralKeyNonce will return a Promise which resolves with a result object. This object has either:
result.nonce: the successful ephemeral key nonce.result.error: an error. Refer to the API reference for all possible errors.
Create ephemeral key nonce
Issuing
Retrieve an Issuing card
stripe.retrieveIssuingCard(issuingCard,options)
Deprecated
Use stripe.retrieveIssuingCard in the Issuing Elements flow to retrieve an Issuing card. Note that once you retrieve the card, you still need to display the card details in Elements. You need to pass in the issuing_elements_2 beta to the Stripe instance to access this method. Refer to our integration guide for more details.
Method parameters
issuingCard required string
options required object
An options object to configure the Issuing card retrieved from this method.
Hide options properties
ephemeralKeySecret required string
The ephemeral key secret retrieved from the API. The card id used to retrieve the ephemeral key must match the card id passed into this method. See the integration guide for more details.
nonce required string
The ephemeral key nonce returned by stripe.createEphemeralKeyNonce. The card id used to create the nonce must match the card id passed into this method.
expand array
An array of Card fields to expand in the response from the Stripe API. Can be one or more of number, cvc, and pin.number. Expand fields as required to display Issuing Elements for those fields.
stripe.retrieveIssuingCard will return a Promise which resolves with a result object. This object has either:
Financial Connections
Introduction
Financial Connections
Stripe Financial Connections enables your users to securely share their financial data by linking their external financial accounts to your business.
Financial Connections
Collect Financial Connections Accounts
stripe.collectFinancialConnectionsAccounts(options)
Method parameters
options required object
Hide options properties
clientSecret required string
stripe.collectFinancialConnectionsAccounts returns a Promise which resolves with a result object. The object has either:
result.financialConnectionsSession: the updated Financial Connections Session object. The accounts property will contain the list of accounts collected during this session. If the user chooses to link no accounts, or exits the Authentication Flow early, the accounts array will be empty.result.error: there was an error launching the Authentication Flow. For example, the Financial Connections Session has expired, or the Financial Connections Session has already been used.
Collect Financial Connections Accounts
Financial Connections
Use Financial Connections to collect a bank account Token for payouts
stripe.collectBankAccountToken(options)
Method parameters
options required object
Hide options properties
clientSecret required string
stripe.collectBankAccountToken returns a Promise which resolves with a result object.
If an external financial account was successfully collected, the result object will contain:
result.token: a bank account Token.result.financialConnectionsSession: the updated Financial Connections Session object. The accounts array will contain a single Financial Connections Account (representing the same external financial account used for result.token).
If there was an error launching the Authentication Flow, the result object will contain:
result.error: there was an error launching the Authentication Flow. For example, the Financial Connections Session has expired, or the Financial Connections Session has already been used.
If the user chooses to link no accounts, or exits the Authentication Flow early, the result object will contain:
Use Financial Connections to collect a bank account Token for payouts
Retrieve card networks
Introduction
Retrieve card networks
Retrieve card networks
stripe.retrieveCardNetworks(rawCardNumber)
Method parameters
rawCardNumber required string
The card number entered in your card collection form. When passed 8 or more digits of the card number, the method starts returning available networks for the card.
In order to pass these card details to Stripe, you must have access to raw card data APIs.
This method returns a Promise which resolves with a result object. This object has a single property, result.networks, which will either be null or an array of network types
Appendix
CssFontSource object
The CssFontSource object
This object is used to pass custom fonts via a stylesheet URL when creating an Elements object.
Example CssFontSource object
Appendix
CustomFontSource object
The CustomFontSource object
This object is used to pass custom fonts when creating an Elements object.
Object Properties
family required string
The name to give the font.
src required string
A valid src value pointing to your custom font file. This is usually (though not always) a link to a file with a .woff , .otf, or .svg suffix. The file must be hosted on https.
display string
style string
One of normal, italic, oblique. Defaults to normal.
unicodeRange string
weight string
A valid font-weight. Note that this is a string, not a number.
Example CustomFontSource object
Appendix
PaymentItem object
The PaymentItem object
Object Properties
amount required number
The amount in the currency's subunit (e.g. cents, yen, etc.)
label required string
A name that the browser shows the customer in the payment interface.
pending boolean
If you might change this amount later (for example, after you have calcluated shipping costs), set this to true. Note that browsers treat this as a hint for how to display things, and not necessarily as something that will prevent submission.
Example PaymentItem object
Appendix
PaymentResponse object
The PaymentResponse object
Object Properties
token object
A Token object. Present if this was the result of a token event listener.
paymentMethod object
A PaymentMethod object. Present if this was the result of a paymentmethod event listener.
source object
A Source object. Present if this was the result of a source event listener.
complete function
complete(status) => void is a Stripe.js provided function. Call this when you have processed the token data provided by the API. Note that you must must call complete within 30 seconds.
Accepts one of the following values:
Hide allowed status values
'success' value
Report to the browser that the payment was successful, and that it can close any active payment interface.
'fail' value
Report to the browser that you were unable to process the customer‘s payment. Browsers may re-show the payment interface, or simply show a message and close.
'invalid_payer_name' value
Equivalent to fail, except that the browser can choose to show a more-specific error message.
'invalid_payer_phone' value
Equivalent to fail, except that the browser can choose to show a more-specific error message.
'invalid_payer_email' value
Equivalent to fail, except that the browser can choose to show a more-specific error message.
'invalid_shipping_address' value
Equivalent to fail, except that the browser can choose to show a more-specific error message.
payerName string
payerEmail string
payerPhone string
shippingAddress ShippingAddress
shippingOption ShippingOption
walletName string
The unique name of the wallet the customer chose to authorize payment. For example, browserCard.
Example PaymentResponse object
Appendix
ShippingOption object
The ShippingOption object
The ShippingOption object describes a shipping method used with a PaymentRequest.
Object Properties
id string
A unique ID you create to keep track of this shipping option. You’ll be told the ID of the selected option on changes and on completion.
label string
A short label for this shipping option.
detail string
A longer description of this shipping option.
amount number
The amount to show for this shipping option. If the cost of this shipping option depends on the shipping address the customer enters, listen for the shippingaddresschange event.
Example ShippingOption object
Appendix
ShippingAddress object
The ShippingAddress object
The ShippingAddress object describes a shipping address collected with a PaymentRequest.
Object Properties
country string
Two-letter country code, capitalized. Valid two-letter country codes are specified by ISO3166 alpha-2.
addressLine array
An array of address line items. For example, 185 Berry St., Suite 500, P.O. Box 12345, etc.
region string
The most coarse subdivision of a country. Depending on the country, this might correspond to a state, a province, an oblast, a prefecture, or something else along these lines.
city string
The name of a city, town, village, etc.
postalCode string
The postal code or ZIP code, also known as PIN code in India.
recipient string
The name of the recipient. This might be a person, a business name, or contain “care of” (c/o) instructions.
phone string
The phone number of the recipient. Note that this might be different from any phone number you collect with requestPayerPhone.
sortingCode string
The sorting code as used in, for example, France. Not present on Apple platforms.
dependentLocality string
A logical subdivision of a city. Can be used for things like neighborhoods, boroughs, districts, or UK dependent localities. Not present on Apple platforms.
Example ShippingAddress object
Appendix
Style object
The Style object
Elements are styled using a Style object, which consists of CSS properties nested under objects for any of the following variants:
base, base variant—all other variants inherit from these stylescomplete, applied when the Element has valid inputempty, applied when the Element has no customer inputinvalid, applied when the Element has invalid input
The following pseudo-classes and pseudo-elements can also be styled using a nested object inside of a variant:
:hover:focus::placeholder::selection:-webkit-autofill:disabled, available for all Elements except the paymentRequestButton Element.::-ms-clear, available for the cardNumber, cardExpiry, and cardCvc Elements. Inside the ::-ms-clear selector, the display property can be customized.
The following CSS properties are supported:
Supported CSS properties
backgroundColor string
The background-color CSS property.
This property works best with the ::selection pseudo-class. In other cases, consider setting the background color on the Element's container instead.
color string
fontFamily string
fontSize string
fontSmoothing string
fontStyle string
fontVariant string
fontWeight string
iconColor string
A custom property, used to set the color of the icons that are rendered in an Element.
lineHeight string
The line-height CSS property.
To avoid cursors being rendered inconsistently across browsers, consider using a padding on the Element's container instead.
letterSpacing string
textAlign string
The text-align CSS property.
Available for the cardNumber, cardExpiry, cardCvc and iban Elements.
padding string
The padding CSS property.
Available for the idealBank Element. Accepts integer length with px unit as values.
textDecoration string
textShadow string
textTransform string
Creating a styled element
Appendix
UpdateDetails object
The UpdateDetails object
This object is passed to the updateWith callback on a PaymentRequest's shippingaddresschange and shippingoptionchange events.
Object Properties
status string
The browser uses this value to show an error message to the customer if they‘ve taken an action that invalidates the payment request. The value must be one of the following:
Hide allowed values
'success' value
Let the customer proceed.
'fail' value
Prevent the customer from making the change they just made.
'invalid_shipping_address' value
Equivalent to fail, except we show a more specific error message. Can only be used in a shippingaddresschange handler.
total PaymentItem
The new total amount, if applicable, as a PaymentItem object.
displayItems array
An array of PaymentItem objects. These PaymentItems are shown as line items in the browser‘s payment interface. Note that the sum of the line item amounts does not need to add up to the total amount above.
shippingOptions array
An array of ShippingOption objects. The first shipping option listed appears in the browser payment interface as the default option.
applePay object
Specify Apple Pay specific options. These are passed through to the Apple Pay API.
Hide applePay properties
recurringPaymentRequest object
Hide recurringPaymentRequest properties
paymentDescription required string
managementURL required string
regularBilling required object
Hide regularBilling properties
amount required number
label required string
recurringPaymentStartDate Date
recurringPaymentEndDate Date
recurringPaymentIntervalUnit 'year' | 'month' | 'day' | 'hour' | 'minute'
recurringPaymentIntervalCount number
trialBilling object
Hide trialBilling properties
amount required number
label required string
recurringPaymentStartDate Date
recurringPaymentEndDate Date
recurringPaymentIntervalUnit 'year' | 'month' | 'day' | 'hour' | 'minute'
recurringPaymentIntervalCount number
automaticReloadPaymentRequest object
Hide automaticReloadPaymentRequest properties
paymentDescription required string
managementURL required string
automaticReloadBilling required object
Hide automaticReloadBilling properties
amount required number
label required string
automaticReloadPaymentThresholdAmount required number
Example UpdateDetails object
Appendix
Supported browsers
Supported browsers
Stripe.js strives to support all recent versions of major browsers. For the sake of security and providing the best experience to the majority of customers, we do not support browsers that are no longer receiving security updates and represent a small minority of traffic. We support some older versions of evergreen browsers but recommend merchants keep their systems up to date for the best support. We support the following desktop browser versions:
- Chrome 38+
- Safari 10.1+
- Firefox 29+
- Edge 15+
- Opera 25+
We support the following mobile browsers:
- iOS Safari 9+ and other browsers and web views which use the system-provided WebKit engine
- Android Chrome 38+
- Samsung Browser 7.1+
For browsers not explicitly supported, we limit support as follows:
- We require TLS 1.2 to be supported by the browser.
- We require browsers that are sufficiently modern enough that they support Promises in the JavaScript programming language.
- We respond to bug reports but do not proactively test other browsers.
If you have an issue with Stripe.js on a specific browser, please contact us so we can improve its support.
Appendix
Cross-origin isolation
Cross-Origin Isolation
Currently, Stripe.js doesn't support Cross-origin isolated sites
Cross-origin isolation requires support by all dependencies, and several key dependencies that enable our payment offerings don't yet provide support for this feature.
Appendix
Supported locales
Supported locales
The following subset of IETF language tags can be used to configure localization in Stripe.js.
Note that Checkout supports a slightly different set of locales than Stripe.js. If you are using Checkout with stripe.redirectToCheckout, make sure to use a locale that Checkout supports.
| Value | Locale | Elements | Checkout |
auto | Stripe detects the locale of the browser | ✔ | ✔ |
ar | Arabic | ✔ | |
bg | Bulgarian (Bulgaria) | ✔ | ✔ |
cs | Czech (Czech Republic) | ✔ | ✔ |
da | Danish (Denmark) | ✔ | ✔ |
de | German (Germany) | ✔ | ✔ |
el | Greek (Greece) | ✔ | ✔ |
en | English | ✔ | ✔ |
en-GB | English (United Kingdom) | ✔ | ✔ |
es | Spanish (Spain) | ✔ | ✔ |
es-419 | Spanish (Latin America) | ✔ | ✔ |
et | Estonian (Estonia) | ✔ | ✔ |
fi | Finnish (Finland) | ✔ | ✔ |
fil | Filipino (Philipines) | ✔ | ✔ |
fr | French (France) | ✔ | ✔ |
fr-CA | French (Canada) | ✔ | ✔ |
he | Hebrew (Israel) | ✔ | |
hr | Croatian (Croatia) | ✔ | ✔ |
hu | Hungarian (Hungary) | ✔ | ✔ |
id | Indonesian (Indonesia) | ✔ | ✔ |
it | Italian (Italy) | ✔ | ✔ |
ja | Japanese (Japan) | ✔ | ✔ |
ko | Korean (Korea) | ✔ | ✔ |
lt | Lithuanian (Lithuania) | ✔ | ✔ |
lv | Latvian (Latvia) | ✔ | ✔ |
ms | Malay (Malaysia) | ✔ | ✔ |
mt | Maltese (Malta) | ✔ | ✔ |
nb | Norwegian Bokmål | ✔ | ✔ |
nl | Dutch (Netherlands) | ✔ | ✔ |
pl | Polish (Poland) | ✔ | ✔ |
pt-BR | Portuguese (Brazil) | ✔ | ✔ |
pt | Portuguese (Brazil) | ✔ | ✔ |
ro | Romanian (Romania) | ✔ | ✔ |
ru | Russian (Russia) | ✔ | ✔ |
sk | Slovak (Slovakia) | ✔ | ✔ |
sl | Slovenian (Slovenia) | ✔ | ✔ |
sv | Swedish (Sweden) | ✔ | ✔ |
th | Thai (Thailand) | ✔ | ✔ |
tr | Turkish (Turkey) | ✔ | ✔ |
vi | Vietnamese (Vietnam) | ✔ | ✔ |
zh | Chinese Simplified (China) | ✔ | ✔ |
zh-HK | Chinese Traditional (Hong Kong) | ✔ | ✔ |
zh-TW | Chinese Traditional (Taiwan) | ✔ | ✔ |
Create a Stripe instance with a locale
Appendix
Cookies
Cookies
There are some cookies that are essential for Stripe to function properly. These Necessary Cookies provide secure access to the site and enable page navigation. Stripe.js only uses essential cookies to ensure the site works properly, detect and prevent fraud, and understand how people interact with Stripe.
You can find more information in the Stripe Cookies Policy.
Deprecated
Redirect to Checkout
stripe.redirectToCheckout(options?)
Deprecated
Use stripe.redirectToCheckout to redirect your customers to Checkout, a Stripe-hosted page to securely collect payment information. When the customer completes their purchase, they are redirected back to your website.
Method parameters
options optional object
Hide options properties
sessionId string
lineItems array
An array of objects representing the items that your customer would like to purchase. These items are shown as line items in the Checkout interface and make up the total amount to be collected by Checkout. Used with the client-only integration.
Hide lineItems properties
price required string
The ID of the price that the customer would like to purchase or subscribe to. May also be a SKU or plan.
quantity required integer
The quantity of units for the item.
mode string
The mode of the Checkout Session, one of payment or subscription. Required if using lineItems with the client-only integration.
successUrl string
The URL to which Stripe should send customers when payment is complete. If you’d like access to the Checkout Session for the successful payment, read more about it in the guide on fulfilling orders. Required if using the client-only integration.
cancelUrl string
The URL to which Stripe should send customers when payment is canceled. Required if using the client-only integration.
clientReferenceId string
A unique string to reference the Checkout session. This can be a customer ID, a cart ID, or similar. It is included in the checkout.session.completed webhook and can be used to fulfill the purchase.
customerEmail string
The email address used to create the customer object. If you already know your customer's email address, use this attribute to prefill it on Checkout.
billingAddressCollection string
Specify whether Checkout should collect the customer’s billing address. If set to required, Checkout will attempt to collect the customer’s billing address. If not set or set to auto Checkout will only attempt to collect the billing address when necessary.
shippingAddressCollection object
When set, provides configuration for Checkout to collect a shipping address from a customer.
Hide shippingAddressCollection properties
allowedCountries required array
An array of two-letter ISO country codes representing which countries Checkout should provide as options for shipping locations. Unsupported country codes: AS, CX, CC, CU, HM, IR, KP, MH, FM, NF, MP, PW, SD, SY, UM, VI.
locale string
A locale that will be used to localize the display of Checkout. Default is auto (Stripe detects the locale of the browser).
submitType string
Describes the type of transaction being performed by Checkout in order to customize relevant text on the page, such as the Submit button. submitType can only be specified when using using line items or SKUs, and not subscriptions. The default is auto. Supported values are: auto, book, donate, pay.
items array
An array of objects representing the items that your customer would like to purchase. These items are shown as line items in the Checkout interface and make up the total amount to be collected by Checkout. Using lineItems is preferred.
Hide items properties
sku, plan string
The ID of the SKU that the customer would like to purchase, or the ID of the plan or recurring price that the customer would like to subscribe to.
quantity integer
The quantity of units for the item.
This method returns a Promise which resolves with a result object. If this method fails, the result object will contain a localized error message in the error.message field.
If you are currently on a beta of the new version of Checkout, read the Beta Migration Guide to upgrade to the latest version.
Deprecated
Handle a card payment with an Element
stripe.handleCardPayment(clientSecret,element,data?)
Deprecated
handleCardPayment has been renamed to confirmCardPayment. In addition to the rename, we have slightly modified the arguments. These changes do not affect the behavior of the method. While we have no plans to ever remove support for handleCardPayment, we think the new name and arguments are easier to understand and better convey what the method is doing.
Use stripe.handleCardPayment(clientSecret, element, data?) when the customer submits your payment form. It will gather payment information from the element, which can be a card or cardNumber element, along with any other data you provide. It will then confirm the PaymentIntent and carry out 3DS or other next_actions if they are required.
If you are using Dynamic 3D Secure, handleCardPayment will trigger your Radar rules to execute and may open a dialog for your customer to authenticate their payment.
Method parameters
clientSecret required string
element required Element
A card or cardNumber Element that will be used to create a payment method.
data optional object
Data to be sent with the request.
Hide data properties
payment_method_data object
Use this parameter to supply additional data relevant to the payment method, such as billing details.
Hide payment_method_data properties
billing_details recommended object
shipping recommended object
receipt_email string
Email address that the receipt for the resulting payment will be sent to.
setup_future_usage string
Indicates that you intend to make future payments with this PaymentIntent's payment method.
If present, the PaymentMethod used with this PaymentIntent can be attached to a Customer, even after the transaction completes.
Use on_session if you intend to only reuse the PaymentMethod when your customer is present in your checkout flow. Use off_session if your customer may or may not be in your checkout flow. See saving card details during payment to learn more.
Stripe uses setup_future_usage to dynamically optimize your payment flow and comply with regional legislation and network rules. For example, if your customer is impacted by SCA, using off_session will ensure that they are authenticated while processing this PaymentIntent. You will then be able to collect off-session payments for this customer.
A Promise which resolves with a result object.
The object will have either:
Note that stripe.handleCardPayment may take several seconds to complete. During that time, you should disable your form from being resubmitted and show a waiting indicator like a spinner. If you receive an error result, you should be sure to show that error to the customer, re-enable the form, and hide the waiting indicator.
Additionally, stripe.handleCardPayment may trigger a 3D Secure authentication challenge. This will be shown in a modal dialog and may be confusing for customers using assistive technologies like screen readers. You should make your form accessible by ensuring that success or error messages are clearly read out after this method completes.
Deprecated
Handle a card payment
stripe.handleCardPayment(clientSecret,data?)
Deprecated
handleCardPayment has been renamed to confirmCardPayment. In addition to the rename, we have slightly modified the arguments. These changes do not affect the behavior of the method. While we have no plans to ever remove support for handleCardPayment, we think the new name and arguments are easier to understand and better convey what the method is doing.
Use stripe.handleCardPayment(clientSecret, data?) to advance the PaymentIntent towards completion when you are not gathering payment method information from an Element.
Call this variation when you have already attached a card to this PaymentIntent or if you want to attach an existing card to it.
Method parameters
clientSecret required string
data optional object
Data to be sent with the request.
Hide data properties
payment_method string
Use payment_method to specify an existing PaymentMethod to use for this payment.
Only one of payment_method_data and payment_method is required.
payment_method_data object
Use this parameter to supply additional data relevant to the payment method, such as billing details.
Hide payment_method_data properties
billing_details recommended object
card[token] string
Converts the provided token into a PaymentMethod to use for the payment.
shipping recommended object
receipt_email string
Email address that the receipt for the resulting payment will be sent to.
setup_future_usage string
Indicates that you intend to make future payments with this PaymentIntent's payment method.
If present, the PaymentMethod used with this PaymentIntent can be attached to a Customer, even after the transaction completes.
Use on_session if you intend to only reuse the PaymentMethod when your customer is present in your checkout flow. Use off_session if your customer may or may not be in your checkout flow. See saving card details after a payment to learn more.
Stripe uses setup_future_usage to dynamically optimize your payment flow and comply with regional legislation and network rules. For example, if your customer is impacted by SCA, using off_session will ensure that they are authenticated while processing this PaymentIntent. You will then be able to collect off-session payments for this customer.
A Promise which resolves with a result object.
The object will have either:
Note that stripe.handleCardPayment may take several seconds to complete. During that time, you should disable your form from being resubmitted and show a waiting indicator like a spinner. If you receive an error result, you should be sure to show that error to the customer, re-enable the form, and hide the waiting indicator.
Additionally, stripe.handleCardPayment may trigger a 3D Secure authentication challenge. This will be shown in a modal dialog and may be confusing for customers using assistive technologies like screen readers. You should make your form accessible by ensuring that success or error messages are clearly read out after this method completes.
Deprecated
Confirm a PaymentIntent with an Element
stripe.confirmPaymentIntent(clientSecret,element,data?)
Deprecated
confirmPaymentIntent has been deprecated. Going forward, if you wish to confirm on the client without handling next actions, simply pass {handleActions: false} as a third argument to confirmCardPayment. While we have no plans to ever remove support for confirmPaymentIntent, we think that explicitly opting out of next action handling is easier to understand and will better convey what the method is doing.
Use stripe.confirmPaymentIntent(clientSecret, element, data) when the customer submits your payment form. It will gather payment information from element, along with any other data you provide, and confirm the PaymentIntent.
Only use this method if you want to handle next actions yourself. Otherwise, use stripe.handleCardPayment.
Method parameters
clientSecret required string
element required Element
An Element that will be used to create a payment method.
data optional object
Data to be sent with the request. It can contain the following parameters
Hide data properties
return_url string
If you are handling next actions yourself, pass in a return_url. If the subsequent action is redirect_to_url, this URL will be used on the return path for the redirect.
payment_method_data object
Use this parameter to supply additional data relevant to the payment method, such as billing details.
Hide payment_method_data properties
billing_details recommended object
shipping recommended object
receipt_email string
Email address that the receipt for the resulting payment will be sent to.
setup_future_usage string
Indicates that you intend to make future payments with this PaymentIntent's payment method.
If present, the PaymentMethod used with this PaymentIntent can be attached to a Customer, even after the transaction completes.
Use on_session if you intend to only reuse the PaymentMethod when your customer is present in your checkout flow. Use off_session if your customer may or may not be in your checkout flow. See saving card details after a payment to learn more.
Stripe uses setup_future_usage to dynamically optimize your payment flow and comply with regional legislation and network rules. For example, if your customer is impacted by SCA, using off_session will ensure that they are authenticated while processing this PaymentIntent. You will then be able to collect off-session payments for this customer.
A Promise which resolves with a result object.
The object will have either:
Note that stripe.confirmPaymentIntent may take several seconds to complete. During that time, you should disable your form from being resubmitted and show a waiting indicator like a spinner. If you receive an error result, you should be sure to show that error to the customer, re-enable the form, and hide the waiting indicator.
Deprecated
Confirm a PaymentIntent
stripe.confirmPaymentIntent(clientSecret,data?)
Deprecated
confirmPaymentIntent has been deprecated. Going forward, if you wish to confirm on the client without handling next actions, simply pass {handleActions: false} as a third argument to confirmCardPayment. While we have no plans to ever remove support for confirmPaymentIntent, we think that explicitly opting out of next action handling is easier to understand and will better convey what the method is doing.
Use stripe.confirmPaymentIntent(clientSecret, data) to confirm the PaymentIntent when you are not gathering payment information from an Element. Call this variation when you have already attached a payment method to this PaymentIntent, or if you want to attach an existing card, token, or PaymentMethod to it.
Only use this method if you want to handle next actions yourself. Otherwise, use stripe.handleCardPayment.
Method parameters
clientSecret required string
data optional object
Data to be sent with the request. It can contain the following parameters
Hide data properties
return_url string
If you are handling next actions yourself, pass in a return_url. If the subsequent action is redirect_to_url, this URL will be used on the return path for the redirect.
payment_method string
Use payment_method to specify an existing PaymentMethod to use for this payment.
Only one of payment_method_data and payment_method is required.
payment_method_data object
Use this parameter to supply additional data relevant to the payment method, such as billing details.
Hide payment_method_data properties
billing_details recommended object
card[token] string
Converts the provided token into a PaymentMethod to use for the payment.
shipping recommended object
receipt_email string
Email address that the receipt for the resulting payment will be sent to.
setup_future_usage string
Indicates that you intend to make future payments with this PaymentIntent's payment method.
If present, the PaymentMethod used with this PaymentIntent can be attached to a Customer, even after the transaction completes.
Use on_session if you intend to only reuse the PaymentMethod when your customer is present in your checkout flow. Use off_session if your customer may or may not be in your checkout flow. See saving card details after a payment to learn more.
Stripe uses setup_future_usage to dynamically optimize your payment flow and comply with regional legislation and network rules. For example, if your customer is impacted by SCA, using off_session will ensure that they are authenticated while processing this PaymentIntent. You will then be able to collect off-session payments for this customer.
A Promise which resolves with a result object.
The object will have either:
Note that stripe.confirmPaymentIntent may take several seconds to complete. During that time, you should disable your form from being resubmitted and show a waiting indicator like a spinner. If you receive an error result, you should be sure to show that error to the customer, re-enable the form, and hide the waiting indicator.
Deprecated
Handle card setup with an Element
stripe.handleCardSetup(clientSecret,element,data?)
Deprecated
handleCardSetup has been renamed to confirmCardSetup. In addition to the rename, we have slightly modified the arguments. These changes do not affect the behavior of the method. While we have no plans to ever remove support for handleCardSetup, we think the new name and arguments are easier to understand and better convey what the method is doing.
Use stripe.handleCardSetup(clientSecret, element, data?) in the Setup Intents API flow when the customer submits your payment form. It will gather payment information from the element, which can be a card or cardNumber element, along with any other data you provide. It will then confirm the SetupIntent and carry out 3DS or other next_actions if they are required.
Method parameters
clientSecret required string
element required Element
A card or cardNumber Element that will be used to create a payment method.
data optional object
Data to be sent with the request.
Hide data properties
payment_method_data object
Use this parameter to supply additional data relevant to the payment method, such as billing details.
Hide payment_method_data properties
billing_details recommended object
A Promise which resolves with a result object.
The object will have either:
result.setupIntent: the successful SetupIntent.result.error: An error. Refer to the API reference for all possible errors.
Note that stripe.handleCardSetup may take several seconds to complete. During that time, you should disable your form from being resubmitted and show a waiting indicator like a spinner. If you receive an error result, you should be sure to show that error to the customer, re-enable the form, and hide the waiting indicator.
Additionally, stripe.handleCardSetup may trigger a 3D Secure authentication challenge. This will be shown in a modal dialog and may be confusing for customers using assistive technologies like screen readers. You should make your form accessible by ensuring that success or error messages are clearly read out after this method completes.
Deprecated
Handle card setup
stripe.handleCardSetup(clientSecret,data?)
Deprecated
handleCardSetup has been renamed to confirmCardSetup. In addition to the rename, we have slightly modified the arguments. These changes do not affect the behavior of the method. While we have no plans to ever remove support for handleCardSetup, we think the new name and arguments are easier to understand and better convey what the method is doing.
Use stripe.handleCardSetup(clientSecret, data) to advance the SetupIntent towards completion when you are not gathering payment method information from an Element.
Call this variation when you have already attached a card to this SetupIntent or if you want to attach an existing card to it.
Method parameters
clientSecret required string
data optional object
Data to be sent with the request.
Hide data properties
payment_method string
Use payment_method to specify an existing PaymentMethod to use for this payment.
Only one of payment_method_data and payment_method is required.
payment_method_data object
Use this parameter to supply additional data relevant to the payment method, such as billing details.
Hide payment_method_data properties
billing_details recommended object
card[token] string
Converts the provided token into a PaymentMethod to use for the payment.
A Promise which resolves with a result object.
The object will have either:
result.setupIntent: the successful SetupIntent.result.error: An error. Refer to the API reference for all possible errors.
Note that stripe.handleCardSetup may take several seconds to complete. During that time, you should disable your form from being resubmitted and show a waiting indicator like a spinner. If you receive an error result, you should be sure to show that error to the customer, re-enable the form, and hide the waiting indicator.
Additionally, stripe.handleCardSetup may trigger a 3D Secure authentication challenge. This will be shown in a modal dialog and may be confusing for customers using assistive technologies like screen readers. You should make your form accessible by ensuring that success or error messages are clearly read out after this method completes.
Deprecated
Confirm a SetupIntent with an Element
stripe.confirmSetupIntent(clientSecret,element,data?)
Deprecated
confirmSetupIntent has been deprecated. Going forward, if you wish to confirm on the client without handling next actions, simply pass {handleActions: false} as a third argument to confirmCardSetup. While we have no plans to ever remove support for confirmSetupIntent, we think that explicitly opting out of next action handling is easier to understand and will better convey what the method is doing.
Use stripe.confirmSetupIntent(clientSecret, element, data) when the customer submits your save payment method form. It will gather payment information from element, along with any other data you provide, and confirm the SetupIntent.
Only use this method if you want to handle next actions yourself. Otherwise, use stripe.handleCardSetup.
Method parameters
clientSecret required string
element required Element
An Element that will be used to create a payment method.
data optional object
Data to be sent with the request. It can contain the following parameters
Hide data properties
payment_method_data object
Use this parameter to supply additional data relevant to the payment method, such as billing details.
Hide payment_method_data properties
billing_details recommended object
A Promise which resolves with a result object.
The object will have either:
result.setupIntent: the successful SetupIntent.result.error: An error. Refer to the API reference for all possible errors.
Note that stripe.confirmSetupIntent may take several seconds to complete. During that time, you should disable your form from being resubmitted and show a waiting indicator like a spinner. If you receive an error result, you should be sure to show that error to the customer, re-enable the form, and hide the waiting indicator.
Deprecated
Confirm a SetupIntent
stripe.confirmSetupIntent(clientSecret,data?)
Deprecated
confirmSetupIntent has been deprecated. Going forward, if you wish to confirm on the client without handling next actions, simply pass {handleActions: false} as a third argument to confirmCardSetup. While we have no plans to ever remove support for confirmSetupIntent, we think that explicitly opting out of next action handling is easier to understand and will better convey what the method is doing.
Use stripe.confirmSetupIntent(clientSecret, data) to confirm the SetupIntent when you are not gathering payment information from an Element. Call this variation when you have already attached a payment method to this SetupIntent, or if you want to attach an existing card, token, or PaymentMethod to it.
Only use this method if you want to handle next actions yourself. Otherwise, use stripe.handleCardSetup.
Method parameters
clientSecret required string
data optional object
Data to be sent with the request. It can contain the following parameters
Hide data properties
return_url string
If you are handling next actions yourself, pass in a return_url. If the subsequent action is redirect_to_url, this URL will be used on the return path for the redirect.
payment_method string
Use payment_method to specify an existing PaymentMethod to use for this payment.
Only one of payment_method_data and payment_method is required.
payment_method_data object
Use this parameter to supply additional data relevant to the payment method, such as billing details.
Hide payment_method_data properties
billing_details recommended object
card[token] string
Converts the provided token into a PaymentMethod to use for the payment.
A Promise which resolves with a result object.
The object will have either:
result.setupIntent: the successful SetupIntent.result.error: An error. Refer to the API reference for all possible errors.
Note that stripe.confirmSetupIntent may take several seconds to complete. During that time, you should disable your form from being resubmitted and show a waiting indicator like a spinner. If you receive an error result, you should be sure to show that error to the customer, re-enable the form, and hide the waiting indicator.
Deprecated
Handle an FPX payment
stripe.handleFpxPayment(clientSecret,element,data?)
Deprecated
handleFpxPayment has been renamed to confirmFpxPayment. In addition to the rename, we have slightly modified the arguments. These changes do not affect the behavior of the method. While we will continue to support handleFpxPayment for the duration of the beta, we think the new name and arguments are easier to understand and better convey what the method is doing.
Use stripe.handleFpxPayment in the FPX payment method creation flow when the customer selects a bank from the dropdown. It will gather the bank code from the element, along with any other PaymentIntent data you provide. It will then create an FPX payment method and confirm the PaymentIntent.
Method parameters
clientSecret required string
element required Element
An fpxBank Element that will be used to create a payment method.
data optional object
A data object to be sent with the request.
This method returns a Promise which resolves with a result object. This object has either:
result.paymentIntent: a PaymentIntent with the requires_confirmation status to confirm server-side.result.error: an error. Refer to the API reference for all possible errors and the FPX guide for FPX specific errors.
Note that stripe.handleFpxPayment may take several seconds to complete. During that time, you should disable your form from being resubmitted and show a waiting indicator like a spinner. If you receive an error result, you should be sure to show that error to the customer, re-enable the form, and hide the waiting indicator.
Deprecated
Sources
SourcesDeprecated
The Sources API has been deprecated and replaced by the Payment Intents API.
Stripe.js provides the following methods to create and retrieve Sources, which are part of the Charges API.
Deprecated
Sources
Create a Source
stripe.createSource(element,sourceData)
Deprecated
Use stripe.createSource to convert payment information collected by elements into a Source object that you safely pass to your server to use in an API call. See the Sources documentation for more information about sources.
Method parameters
element required object
The Element containing payment information. If applicable, the Element pulls data from other elements you’ve created on the same Elements instance.
sourceData required object
A required object containing the type of Source you want to create, and any additional payment information that you have collected. See the Sources API reference for details.
This method returns a Promise which resolves with a result object. This object has either:
result.source: a Source was created successfully.result.error: there was an error. This includes client-side validation errors. Refer to the API reference for all possible errors.
Deprecated
Sources
Create a Source from data
stripe.createSource(sourceData)
Deprecated
Use stripe.createSource to convert raw payment information into a Source object that you can safely pass to your server for use in an API call. See the Sources documentation for more information about sources.
Method parameters
sourceData required object
A required object containing the type of Source you want to create, and any additional payment information that you have collected. See the Sources API reference for details.
This method returns a Promise which resolves with a result object. This object has either:
result.source: a Source was created successfully.result.error: there was an error. This includes client-side validation errors. Refer to the API reference for all possible errors.
You can pass raw card information to stripe.createSource(sourceData) to create card Sources. However, we recommend using Elements for collecting the card data to maintain the simplest form of PCI compliance.
Deprecated
Sources
Retrieve a Source
stripe.retrieveSource(source)
Deprecated
Retrieve a Source using its unique ID and client secret.
Method parameters
source required object
An object containing the unique ID and client secret for a Source.
You can use a Source object created with stripe.createSource as the argument to stripe.retrieveSource, as every Source object has both id and client_secret keys.
Hide source properties
id required string
Unique identifier of the Source.
client_secret required string
A secret available to the web client that created the Source, for purposes of retrieving the Source later from that same client.
This method returns a Promise which resolves with a result object. This object has either:
result.source: a Source was retrieved successfully.result.error: there was an error. This includes client-side validation errors. Refer to the API reference for all possible errors.