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

Create a SetupIntent

• POST /v1/setup_intents

Update a SetupIntent

• POST /v1/setup_intents/:id

Retrieve a SetupIntent

• GET /v1/setup_intents/:id

List all SetupIntents

• GET /v1/setup_intents

Cancel a SetupIntent

• POST /v1/setup_intents/:id/cancel

Confirm a SetupIntent

• POST /v1/setup_intents/:id/confirm

Verify microdeposits on a SetupIntent

• POST /v1/setup_intents/:id/verify_microdeposits

Events

• setup_intent.canceled Occurs when a SetupIntent is canceled.

• setup_intent.created Occurs when a new SetupIntent is created.

• setup_intent.requires_action Occurs when a SetupIntent is in requires_action state.

• setup_intent.setup_failed Occurs when a SetupIntent has failed the attempt to setup a payment method.

• setup_intent.succeeded Occurs when an SetupIntent has successfully setup a payment method.