Core Resources
Payment Methods
Products
Checkout
Payment Links
Billing
Capital
Connect
Fraud
Issuing
Terminal
Treasury
Entitlements
Sigma
Reporting
Financial Connections
Tax
Identity
Crypto
Climate
Forwarding
Webhooks

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

Endpoints

The SetupIntent object 

Attributes

  • idstringretrievable with publishable key

    Unique identifier for the object.

  • automatic_payment_methodsnullable object

    Settings for dynamic payment methods compatible with this Setup Intent

  • client_secretnullable stringretrievable 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.

  • customernullable stringExpandable

    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.

  • descriptionnullable stringretrievable with publishable key

    An arbitrary string attached to the object. Often useful for displaying to users.

  • last_setup_errornullable objectretrievable with publishable key

    The error encountered in the previous SetupIntent confirmation.

  • metadatanullable object

    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_actionnullable objectretrievable 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_methodnullable stringExpandableretrievable 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.

  • statusenumretrievable 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

  • usagestringretrievable 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

  • objectstringretrievable with publishable key

  • applicationnullable stringExpandableConnect only

  • attach_to_selfnullable boolean

  • cancellation_reasonnullable enumretrievable with publishable key

  • createdtimestampretrievable with publishable key

  • flow_directionsnullable array of enums

  • latest_attemptnullable stringExpandable

  • livemodebooleanretrievable with publishable key

  • mandatenullable stringExpandable

  • on_behalf_ofnullable stringExpandableConnect only

  • payment_method_configuration_detailsnullable object

  • payment_method_optionsnullable object

  • payment_method_typesarray of stringsretrievable with publishable key

  • single_use_mandatenullable stringExpandable

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 

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 to false. If a card is the attached payment method, you can provide a return_url in case further authentication is necessary.

  • 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 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

  • 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.

POST /v1/setup_intents
curl https://api.stripe.com/v1/setup_intents \
  -u "sk_test_4eC39Hq...arjtT1zdp7dcsk_test_4eC39HqLyjWDarjtT1zdp7dc:" \
  -d "payment_method_types[]"=card
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"
}

Update a SetupIntent 

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.

POST /v1/setup_intents/:id
curl https://api.stripe.com/v1/setup_intents/seti_1Mm8s8LkdIwHu7ix0OXBfTRG \
  -u "sk_test_4eC39Hq...arjtT1zdp7dcsk_test_4eC39HqLyjWDarjtT1zdp7dc:" \
  -d "metadata[order_id]"=6735
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 

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_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.

GET /v1/setup_intents/:id
curl https://api.stripe.com/v1/setup_intents/seti_1Mm8s8LkdIwHu7ix0OXBfTRG \
  -u "sk_test_4eC39Hq...arjtT1zdp7dcsk_test_4eC39HqLyjWDarjtT1zdp7dc:"
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"
}