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

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

List all SetupIntents 

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_after. Each entry in the array is a separate SetupIntent object. If no more SetupIntents are available, the resulting array will be empty.

GET /v1/setup_intents
curl -G https://api.stripe.com/v1/setup_intents \
  -u "sk_test_4eC39Hq...arjtT1zdp7dcsk_test_4eC39HqLyjWDarjtT1zdp7dc:" \
  -d limit=3
Response
{
  "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"
    }
  ]
}

Cancel a SetupIntent 

You can cancel a SetupIntent object when it’s in one of these statuses: requires_payment_method, requires_confirmation, or requires_action.

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_by_customer, or 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.

POST /v1/setup_intents/:id/cancel
curl -X POST https://api.stripe.com/v1/setup_intents/seti_1Mm8s8LkdIwHu7ix0OXBfTRG/cancel \
  -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": "canceled",
  "usage": "off_session"
}

Confirm a SetupIntent 

Confirm that your customer intends to set up the current or provided payment method. For example, you would confirm a SetupIntent when a customer hits the “Save” button on a payment method management page on your website.

If the selected payment method does not require any additional steps from the customer, the SetupIntent will transition to the succeeded status.

Otherwise, it will transition to the requires_action status and suggest additional actions via next_action. If setup fails, the SetupIntent will transition to the requires_payment_method status or the canceled status if the confirmation limit is reached.

Parameters

  • payment_methodstring

    ID of the payment method (a PaymentMethod, Card, or saved Source object) to attach to this SetupIntent.

More parameters

  • confirmation_tokenstring

  • mandate_dataobject

  • payment_method_dataobject

  • payment_method_optionsobjectsecret key only

  • return_urlstring

  • use_stripe_sdkboolean

Returns

Returns the resulting SetupIntent after all possible transitions are applied.

POST /v1/setup_intents/:id/confirm
curl https://api.stripe.com/v1/setup_intents/seti_1Mm2cBLkdIwHu7ixaiKW3ElR/confirm \
  -u "sk_test_4eC39Hq...arjtT1zdp7dcsk_test_4eC39HqLyjWDarjtT1zdp7dc:" \
  -d payment_method=pm_card_visa
Response
{
  "id": "seti_1Mm2cBLkdIwHu7ixaiKW3ElR",
  "object": "setup_intent",
  "application": null,
  "cancellation_reason": null,
  "client_secret": "seti_1Mm2cBLkdIwHu7ixaiKW3ElR_secret_NX6phB7HbSmlkpqzKZ3Bxr7uXFRf9Jg",
  "created": 1678918571,
  "customer": null,
  "description": null,
  "flow_directions": null,
  "last_setup_error": null,
  "latest_attempt": "setatt_1Mm2cBLkdIwHu7ixdEp1VkXJ",
  "livemode": false,
  "mandate": null,
  "metadata": {},
  "next_action": null,
  "on_behalf_of": null,
  "payment_method": "pm_1Mm2cBLkdIwHu7ixGoOfZSsV",
  "payment_method_options": {
    "card": {
      "mandate_options": null,
      "network": null,
      "request_three_d_secure": "automatic"
    }
  },
  "payment_method_types": [
    "card"
  ],
  "single_use_mandate": null,
  "status": "succeeded",
  "usage": "off_session"
}

Verify microdeposits on a SetupIntent 

Verifies microdeposits on a SetupIntent object.

Parameters

  • amountsarray of integers

    Two positive integers, in cents, equal to the values of the microdeposits sent to the bank account.

  • descriptor_codestring

    A six-character code starting with SM present in the microdeposit sent to the bank account.

Returns

Returns a SetupIntent object.

POST /v1/setup_intents/:id/verify_microdeposits
curl https://api.stripe.com/v1/setup_intents/seti_1Mm5yZLkdIwHu7ixm0sPzrx4/verify_microdeposits \
  -u "sk_test_4eC39Hq...arjtT1zdp7dcsk_test_4eC39HqLyjWDarjtT1zdp7dc:" \
  -d "amounts[]"=32 \
  -d "amounts[]"=45
Response
{
  "id": "seti_1Mm5yZLkdIwHu7ixm0sPzrx4",
  "object": "setup_intent",
  "application": null,
  "cancellation_reason": null,
  "client_secret": "seti_1Mm5yZLkdIwHu7ixm0sPzrx4_secret_NXAJ5iPM38ITW1pI7o8VZZhoZyDrrWR",
  "created": 1678931491,
  "customer": null,
  "description": null,
  "flow_directions": null,
  "last_setup_error": null,
  "latest_attempt": "setatt_1Mm5yZLkdIwHu7ix7QtOkLAu",
  "livemode": false,
  "mandate": "mandate_1Mm5yaLkdIwHu7ixmNoLkKLC",
  "metadata": {},
  "next_action": null,
  "on_behalf_of": null,
  "payment_method": "pm_1Mm5yZLkdIwHu7ixf89jW57b",
  "payment_method_options": {
    "acss_debit": {
      "currency": "cad",
      "mandate_options": {
        "interval_description": "First of every month",
        "payment_schedule": "interval",
        "transaction_type": "personal"
      },
      "verification_method": "automatic"
    }
  },
  "payment_method_types": [
    "acss_debit"
  ],
  "single_use_mandate": null,
  "status": "succeeded",
  "usage": "off_session"
}