Setup Intents

A SetupIntent guides you through the process of setting up and saving a customer’s payment credentials for future payments. For example, you can use a SetupIntent to set up and save your customer’s card without immediately collecting a payment. Later, you can use PaymentIntents to drive the payment flow.

Create a SetupIntent when you’re ready to collect your customer’s payment credentials. Don’t maintain long-lived, unconfirmed SetupIntents because they might not be valid. The SetupIntent transitions through multiple statuses as it guides you through the setup process.

Successful SetupIntents result in payment credentials that are optimized for future payments. For example, cardholders in certain regions might need to be run through Strong Customer Authentication during payment method collection to streamline later off-session payments. If you use the SetupIntent with a Customer, it automatically attaches the resulting payment method to that Customer after successful setup. We recommend using SetupIntents or setup_future_usage on PaymentIntents to save payment methods to prevent saving invalid or unoptimized payment methods.

By using SetupIntents, you can reduce friction for your customers, even as regulations change over time.

Related guide: Setup Intents API

Was this section helpful? Yes No

Create a SetupIntent

POST / v1 / setup_intents

Update a SetupIntent

POST / v1 / setup_intents /:id

Retrieve a SetupIntent

GET / v1 / setup_intents /:id

List all SetupIntents

GET / v1 / setup_intents

Cancel a SetupIntent

POST / v1 / setup_intents /:id / cancel

Confirm a SetupIntent

POST / v1 / setup_intents /:id / confirm

Verify microdeposits on a SetupIntent

POST / v1 / setup_intents /:id / verify_microdeposits

The SetupIntent object

Attributes

id string retrievable with publishable key Unique identifier for the object.
automatic _ payment _ methods nullable object Settings for dynamic payment methods compatible with this Setup Intent
client _ secret nullable string retrievable with publishable key The client secret of this SetupIntent. Used for client-side retrieval using a publishable key. The client secret can be used to complete payment setup from your frontend. It should not be stored, logged, or exposed to anyone other than the customer. Make sure that you have TLS enabled on any page that includes the client secret.
customer nullable string Expandable ID of the Customer this SetupIntent belongs to, if one exists. If present, the SetupIntent’s payment method will be attached to the Customer on successful setup. Payment methods attached to other Customers cannot be used with this SetupIntent.
customer _ account nullable string ID of the Account this SetupIntent belongs to, if one exists. If present, the SetupIntent’s payment method will be attached to the Account on successful setup. Payment methods attached to other Accounts cannot be used with this SetupIntent.
description nullable string retrievable with publishable key An arbitrary string attached to the object. Often useful for displaying to users.
last _ setup _ error nullable object retrievable with publishable key The error encountered in the previous SetupIntent confirmation.
metadata nullable map Set of key-value pairs that you can attach to an object. This can be useful for storing additional information about the object in a structured format.
next _ action nullable object retrievable with publishable key If present, this property tells you what actions you need to take in order for your customer to continue payment setup.
payment _ method nullable string Expandable retrievable with publishable key ID of the payment method used with this SetupIntent. If the payment method is card_present and isn’t a digital wallet, then the generated_card associated with the latest_attempt is attached to the Customer instead.
status enum retrievable with publishable key Status of this SetupIntent, one of requires_payment_method, requires_confirmation, requires_action, processing, canceled, or succeeded. Possible enum values canceled processing requires_action requires_confirmation requires_payment_method succeeded
usage string retrievable with publishable key Indicates how the payment method is intended to be used in the future. Use on_session if you intend to only reuse the payment method when the customer is in your checkout flow. Use off_session if your customer may or may not be in your checkout flow. If not provided, this value defaults to off_session.

More attributes

object string, value is "setup_intent" retrievable with publishable key
allowed _ payment _ method _ types nullable array of enums
application nullable string Expandable Connect only
attach _ to _ self nullable boolean
cancellation _ reason nullable enum retrievable with publishable key
created timestamp retrievable with publishable key
excluded _ payment _ method _ types nullable array of enums
flow _ directions nullable array of enums
latest _ attempt nullable string Expandable
livemode boolean retrievable with publishable key
mandate nullable string Expandable
on _ behalf _ of nullable string Expandable Connect only
payment _ method _ configuration _ details nullable object
payment _ method _ options nullable object
payment _ method _ types array of strings retrievable with publishable key
single _ use _ mandate nullable string Expandable

The SetupIntent object

{ "id": "seti_1Mm8s8LkdIwHu7ix0OXBfTRG", "object": "setup_intent", "application": null, "cancellation_reason": null, "client_secret": "seti_1Mm8s8LkdIwHu7ix0OXBfTRG_secret_NXDICkPqPeiBTAFqWmkbff09lRmSVXe", "created": 1678942624, "customer": null, "description": null, "flow_directions": null, "last_setup_error": null, "latest_attempt": null, "livemode": false, "mandate": null, "metadata": {}, "next_action": null, "on_behalf_of": null, "payment_method": null, "payment_method_options": { "card": { "mandate_options": null, "network": null, "request_three_d_secure": "automatic" } }, "payment_method_types": [ "card" ], "single_use_mandate": null, "status": "requires_payment_method", "usage": "off_session"}

Create a SetupIntent

POST / v1 / setup_intents

Creates a SetupIntent object.

After you create the SetupIntent, attach a payment method and confirm it to collect any required permissions to charge the payment method later.

Parameters

automatic _ payment _ methods object When you enable this parameter, this SetupIntent accepts payment methods that you enable in the Dashboard and that are compatible with its other parameters.
confirm boolean Set to true to attempt to confirm this SetupIntent immediately. This parameter defaults to false. If a card is the attached payment method, you can provide a return_url in case further authentication is necessary.
customer string ID of the Customer this SetupIntent belongs to, if one exists. If present, the SetupIntent’s payment method will be attached to the Customer on successful setup. Payment methods attached to other Customers cannot be used with this SetupIntent.
customer _ account string ID of the Account this SetupIntent belongs to, if one exists. If present, the SetupIntent’s payment method will be attached to the Account on successful setup. Payment methods attached to other Accounts cannot be used with this SetupIntent.
description string An arbitrary string attached to the object. Often useful for displaying to users.
metadata map Set of key-value pairs that you can attach to an object. This can be useful for storing additional information about the object in a structured format. Individual keys can be unset by posting an empty value to them. All keys can be unset by posting an empty value to metadata.
payment _ method string ID of the payment method (a PaymentMethod, Card, or saved Source object) to attach to this SetupIntent.
usage enum Indicates how the payment method is intended to be used in the future. If not provided, this value defaults to off_session. Possible enum values off_session Use off_session if your customer may or may not be in your checkout flow. on_session Use on_session if you intend to only reuse the payment method when the customer is in your checkout flow.

More parameters

allowed _ payment _ method _ types array of enums
attach _ to _ self boolean
confirmation _ token string only when confirm=true
excluded _ payment _ method _ types array of enums
flow _ directions array of enums
mandate _ data object only when confirm=true
on _ behalf _ of string Connect only
payment _ method _ configuration string
payment _ method _ data object
payment _ method _ options object
return _ url string only when confirm=true
single _ use object
use _ stripe _ sdk boolean

Returns

Returns a SetupIntent object.

Response

{ "id": "seti_1Mm8s8LkdIwHu7ix0OXBfTRG", "object": "setup_intent", "application": null, "automatic_payment_methods": { "enabled": true }, "cancellation_reason": null, "client_secret": "seti_1Mm8s8LkdIwHu7ix0OXBfTRG_secret_NXDICkPqPeiBTAFqWmkbff09lRmSVXe", "created": 1678942624, "customer": null, "description": null, "flow_directions": null, "last_setup_error": null, "latest_attempt": null, "livemode": false, "mandate": null, "metadata": {}, "next_action": null, "on_behalf_of": null, "payment_method": null, "payment_method_options": { "card": { "mandate_options": null, "network": null, "request_three_d_secure": "automatic" } }, "payment_method_types": [ "card" ], "single_use_mandate": null, "status": "requires_payment_method", "usage": "off_session"}