Create a SetupIntent

Changed on

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.

post/v1/setup_intents

Request

  • Base URL: https://api.stripe.com
  • URL: https://api.stripe.com/v1/setup_intents
  • Auth: one of:
    • HTTP basic
    • HTTP bearer

Request body application/x-www-form-urlencoded

allowed_payment_method_typesstring[]

The list of payment method types to allow for this SetupIntent. Stripe will only use methods in this list when determining the payment methods to offer. A list of valid payment method types can be found here.

attach_to_selfboolean

If present, the SetupIntent's payment method will be attached to the in-context Stripe Account.

It can only be used for this Stripe Account’s own money movement flows like InboundTransfer and OutboundTransfers. It cannot be set to true when setting up a PaymentMethod for a Customer, and defaults to false when attaching a PaymentMethod to a Customer.

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.

confirmation_tokenstring

ID of the ConfirmationToken used to confirm this SetupIntent.

If the provided ConfirmationToken contains properties that are also being provided in this request, such as payment_method, then the values in this request will take precedence.

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.

customer_accountstring

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.

descriptionstring

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

excluded_payment_method_typesstring[]

The list of payment method types to exclude from use with this SetupIntent.

expandstring[]

Specifies which fields in the response should be expanded.

flow_directionsstring[]

Indicates the directions of money movement for which this payment method is intended to be used.

Include inbound if you intend to use the payment method as the origin to pull funds from. Include outbound if you intend to use the payment method as the destination to send funds to. You can include both if you intend to use the payment method for both purposes.

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.

on_behalf_ofstring

The Stripe account ID created for this SetupIntent.

payment_methodstring

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

payment_method_configurationstring

The ID of the payment method configuration to use with this SetupIntent.

return_urlstring

The URL to redirect your customer back to after they authenticate or cancel their payment on the payment method's app or site. To redirect to a mobile application, you can alternatively supply an application URI scheme. This parameter can only be used with confirm=true.

usage'off_session' | 'on_session'

Indicates how the payment method is intended to be used in the future. If not provided, this value defaults to off_session.

use_stripe_sdkboolean

Set to true when confirming server-side and using Stripe.js, iOS, or Android client-side SDKs to handle the next actions.

Response

Successful response.

allowed_payment_method_typesstring[] nullable

The list of payment method types to allow for this SetupIntent. Stripe will only use methods in this list when determining the payment methods to offer.

attach_to_selfboolean

If present, the SetupIntent's payment method will be attached to the in-context Stripe Account.

It can only be used for this Stripe Account’s own money movement flows like InboundTransfer and OutboundTransfers. It cannot be set to true when setting up a PaymentMethod for a Customer, and defaults to false when attaching a PaymentMethod to a Customer.

cancellation_reason'abandoned' | 'duplicate' | 'requested_by_customer' nullable

Reason for cancellation of this SetupIntent, one of abandoned, requested_by_customer, or duplicate.

client_secretstring nullable

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.

createdinteger required

Time at which the object was created. Measured in seconds since the Unix epoch.

customer_accountstring nullable

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.

descriptionstring nullable

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

excluded_payment_method_typesstring[] nullable

Payment method types that are excluded from this SetupIntent.

flow_directionsstring[] nullable

Indicates the directions of money movement for which this payment method is intended to be used.

Include inbound if you intend to use the payment method as the origin to pull funds from. Include outbound if you intend to use the payment method as the destination to send funds to. You can include both if you intend to use the payment method for both purposes.

idstring required

Unique identifier for the object.

livemodeboolean required

If the object exists in live mode, the value is true. If the object exists in test mode, the value is false.

metadataobject nullable

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.

object'setup_intent' required

String representing the object's type. Objects of the same type share the same value.

payment_method_typesstring[] required

The list of payment method types (e.g. card) that this SetupIntent is allowed to set up. A list of valid payment method types can be found here.

status'canceled' | 'processing' | 'requires_action' | 'requires_confirmation' | 'requires_payment_method' | 'succeeded' required

Status of this SetupIntent, one of requires_payment_method, requires_confirmation, requires_action, processing, canceled, or succeeded.

usagestring required

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.

Changes

  • c113b1939b8fRevision changes
    • info

      added the optional property ////// to the response with the status

  • 7b8f614372caRevision changes
    • info

      added the optional property ////////// to the response with the status

Some revisions have not been checked yet.