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_ methodsobject When you enable this parameter, this SetupIntent accepts payment methods that you enable in the Dashboard and that are compatible with its other parameters.
- confirmboolean
Set to
true
to attempt to confirm this SetupIntent immediately. This parameter defaults tofalse
. If a card is the attached payment method, you can provide areturn_
in case further authentication is necessary.url - customerstring
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.
- descriptionstring
An arbitrary string attached to the object. Often useful for displaying to users.
- metadataobject
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_
methodstring ID of the payment method (a PaymentMethod, Card, or saved Source object) to attach to this SetupIntent.
- usageenum
Indicates how the payment method is intended to be used in the future. If not provided, this value defaults to
off_
.session Possible enum valuesoff_
session Use
off_
if your customer may or may not be in your checkout flow.session on_
session Use
on_
if you intend to only reuse the payment method when the customer is in your checkout flow.session
More parameters
- attach_
to_ selfboolean - confirmation_
tokenstringonly when confirm=true - flow_
directionsarray of enums - mandate_
dataobjectonly when confirm=true - on_
behalf_ ofstringConnect only - payment_
method_ configurationstring - payment_
method_ dataobject - payment_
method_ optionsobject - payment_
method_ typesarray of strings - return_
urlstringonly when confirm=true - single_
useobject - use_
stripe_ sdkboolean
Returns
Returns a 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"}
Updates a SetupIntent object.
Parameters
- customerstring
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.
- descriptionstring
An arbitrary string attached to the object. Often useful for displaying to users.
- metadataobject
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_
methodstring 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
- attach_
to_ selfboolean - flow_
directionsarray of enums - payment_
method_ configurationstring - payment_
method_ dataobject - payment_
method_ optionsobject - payment_
method_ typesarray of strings
Returns
Returns a 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": { "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"}
Retrieves the details of a SetupIntent that has previously been created.
Client-side retrieval using a publishable key is allowed when the client_
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_
secretstringRequired 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.
{ "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"}
Returns a list of SetupIntents.
Parameters
- customerstring
Only return SetupIntents for the customer specified by this customer ID.
- payment_
methodstring Only return SetupIntents that associate with the specified payment method.
More parameters
- attach_
to_ selfboolean - createdobject
- ending_
beforestring - limitinteger
- starting_
afterstring
Returns
A dictionary with a data
property that contains an array of up to limit
SetupIntents, starting after SetupIntent starting_
. Each entry in the array is a separate SetupIntent object. If no more SetupIntents are available, the resulting array will be empty.
{ "object": "list", "url": "/v1/setup_intents", "has_more": false, "data": [ { "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" } {...} {...} ],}
You can cancel a SetupIntent object when it’s in one of these statuses: requires_
, requires_
, or requires_
.
After you cancel it, setup is abandoned and any operations on the SetupIntent fail with an error. You can’t cancel the SetupIntent for a Checkout Session. Expire the Checkout Session instead.
Parameters
- cancellation_
reasonstring Reason for canceling this SetupIntent. Possible values are:
abandoned
,requested_
, orby_ customer duplicate
Returns
Returns a SetupIntent object if the cancellation succeeds. Returns an error if the SetupIntent is already canceled or isn’t in a cancelable state.
{ "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": "canceled", "usage": "off_session"}