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"}

Update a SetupIntent

POST / v1 / setup_intents /:id

Updates a SetupIntent object.

Parameters

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. To unset this field to null, pass in an empty string.

More parameters

allowed _ payment _ method _ types array of enums
attach _ to _ self boolean
excluded _ payment _ method _ types array of enums
flow _ directions array of enums
payment _ method _ configuration string
payment _ method _ data object
payment _ method _ options object

Returns

Returns a SetupIntent object.

Response

{ "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": { "order_id": "6735" }, "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"}

Retrieve a SetupIntent

GET / v1 / setup_intents /:id

Retrieves the details of a SetupIntent that has previously been created.

Client-side retrieval using a publishable key is allowed when the client_secret is provided in the query string.

When retrieved with a publishable key, only a subset of properties will be returned. Please refer to the SetupIntent object reference for more details.

Parameters

client _ secret string Required if using publishable key The client secret of the SetupIntent. We require this string if you use a publishable key to retrieve the SetupIntent.

Returns

Returns a SetupIntent if a valid identifier was provided.

Response

{ "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"}