The Setup Intents API

Use the Setup Intents API to set up a payment method for future payments. It’s similar to a payment, but no charge is created. Set up a payment method for future payments now.

The goal is to have payment credentials saved and optimized for future payments, meaning the payment method is configured correctly for any scenario. When setting up a card, for example, it may be necessary to authenticate the customer or check the card’s validity with the customer’s bank. Stripe updates the SetupIntent object throughout that process.

Saving and reusing payment methods

The Setup Intents API is useful for businesses that onboard customers but don’t charge them right away:

• A car rental company that collects payment method details before the customer rents the car and charges the card after the rental period ends
• A crowdfunding website that collects card details to be charged later, only if the campaign reaches a certain amount
• A utility company that charges a different amount each month based on usage but collects SEPA payment details before the first month’s payment

Get started

• Save cards without making an initial payment
• Save bank details for SEPA Direct Debit payments
• Save bank details for BECS Direct Debit payments

Getting permission to save a payment method

If you set up a payment method for future off-session payments, you need permission. Creating an agreement (sometimes called a mandate) up front allows you to charge the customer when they’re not actively using your website or app.

Add terms to your website or app that state how you plan to process payments, and let customers opt in. At a minimum, ensure that your terms cover the following:

• The customer’s permission to your initiating a payment or a series of payments on their behalf
• The anticipated frequency of payments (that is, one-time or recurring)
• How the payment amount will be determined

See recommended mandate text for saving cards or saving SEPA bank details.

For users impacted by SCA, this agreement helps payments succeed without interruption. When you set up your integration to properly save a card, Stripe marks any subsequent off-session payment as a merchant-initiated transaction (MIT) so that your customers don’t have to come back online and authenticate. Merchant-initiated transactions require an agreement between you and your customer.

Increasing success rate by specifying usage

The usage parameter tells Stripe how you plan to use payment method details later. For some payment methods, Stripe can use your usage setting to pick the most frictionless flow for the customer. This optimisation is designed to increase the number of successful payments.

For example, credit and debit cards under European SCA regulation may require the customer to authenticate the card during the saving process. Setting usage to off_session properly authenticates a credit or debit card for off-session payments so that your customer doesn’t have to come back online and re-authenticate. So although it creates initial friction in the setup flow, setting usage to off_session can reduce customer intervention in later off-session payments.

However, if you only plan to use the card when the customer is checking out, set usage to on_session. This lets the bank know you plan to use the card when the customer is available to authenticate, so you can postpone authenticating the card details until then and avoid upfront friction.

Usage is an optimisation. You can still use a card that’s set up for on-session payments to make off-session payments, but banks are more likely to reject the off-session payment and require authentication from the customer. Either case might still require authentication later, so build a recovery process in your app. When an off-session card payment requires authentication, bring your customer back online to complete the payment.

If not specified, usage defaults to off_session. See how to create a SetupIntent on your server and specify the usage:

curl https://api.stripe.com/v1/setup_intents \
  -u "
sk_test_4eC39HqLyjWDarjtT1zdp7dc
:" \
  -d usage=on_session