Skip to main content

Setup intent

Learn more about Setup IntentAPI.

You can use the Setup IntentAPI for a future payment or an advanced booking, or in any other scenario where you need to save a customer's payment information for future use. Please note that this setup intent can only be used once, and subsequent charges will need to be re-authorized by creating a new setup intent ID.

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 and does not 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.

Business use cases​

The following are some common business use cases for setup intents.

  • Online Hotel Reservation systems in which customer card details are required to be collected in advance when making a booking. The hotel is then able to charge the customer during check-out without re-presenting of the card.
  • 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 is then able to charge the card once the booking is completed.
Last updated on