Skip to main content

Setup intent

Learn more about Setup IntentAPI.

A setup intent guides you to save a customer’s card details for future payments. You can use the Setup IntentAPI for future payments or advance bookings, or in any other scenario where you need to save a customer's payment information for future use. Each customer needs to be authorized for setup intents only once, and you can charge their card in the future without requiring them to re-authorize.

How do setup intents work?​

Using a Setup Intent is an easy way to collect card details for future payments. You can configure the object with or without an intended amount based on your business’ terms and conditions. The setup intent is available in captureMode: Auto only.

For the full API specification, see the Setup Intent API guide.

Merchant-Initiated Transactions​

A merchant-initiated transaction is a payment that is initiated by the merchant, rather than the customer. Merchants can set up certain terms for a one-time payment or several other payments that will be captured in the future. The customer agrees to the merchant’s terms before sharing card details and authorizing the payment.

Types​

NoShow​

A NoShow transaction occurs when a customer is unable to fulfill the merchant-initiated terms. For example, when a customer makes a reservation at a restaurant but does not show up without canceling the reservation in advance. This can be a major problem for restaurants, as they lose out on potential revenue.

Unscheduled​

An Unscheduled transaction occurs when a merchant saves the payment information of a customer and subsequently initiates a transaction without a predetermined schedule or regular frequency. This type of transaction can involve either a fixed or variable amount, depending on the merchant's terms and conditions. An Unscheduled transaction is typically not part of a recurring billing or subscription arrangement. Instead, a card is charged only after the customer's prior authorization or request.

You can initiate a setup intent with a NoShow or Unscheduled condition. Add the following to the Setup Intent request body:

{  ...
    "MerchantInitiatedTransactionType": "NoShow",
}
note

In case of a NoShow, the card can be charged only once.

Setup intent API vs Payment intent API​

Setup Intent and Payment Intent serve different purposes in the world of payments.

  • The Setup IntentAPI is ideal for scheduling a payment for the future. It does not actually charge the customer's card right away. This API allows merchants to save a card to charge later. The Setup Intent API works with captureMode: Auto only. To charge a card, you need to create a payment intent.

  • The Payment IntentAPI is ideal for creating a payment that processes immediately, or within a defined timeframe. No card details are saved in a payment intent API object when created. The payment intent API works with both captureMode: Auto and captureMode: Manual. You can collect card details and capture a payment with the same payment intent.

When to use Setup Intent API?​

You can use the Setup Intent API only to save a customer’s payment information for future use and not charge them immediately.

Business use cases​

The following use cases are some of the common ones to give you a reference point.

  • Online hotel reservation system that collects customer card details in advance when booking a room. The hotel charges the card later when the customer checks out.
  • Online table booking in a restaurant that collects customer card details in advance when booking a table for a party of 10 or more. The restaurant charges the authorized card later when the party is done with meals. The restaurant can also charge the authorized card with the booking amount in case of a no-show.
Last updated on