Setup intents

A setup intent allows customers to save a payment card without having to initiate a transaction or complete a payment. Customers can choose to save a payment card outside the checkout workflow, for example when they set up their profile in your integration or before they start an order. Benefits to saving a payment card include improving the customer checkout experience, simplifying the checkout process, and reducing the need for a customer to manually enter their card details every time they complete a payment.

The following procedure is a high-level overview of how to create and confirm a setup intent.

  1. Use your hosted checkout - payment credentials to send a POST request to v1/setup-intents endpoint of the setup intents API to create a setup intent.

    Note

    The sessionSecret from the SetupIntent response expires after 30 minutes. If the setup intent has expired, you need to create a new setup intent.

  2. Use your hosted checkout - iframe credentials to get an OAuth bearer token and pass the token and sessionSecret to your hosted checkout client. This renders the iframe onto a webpage in your integration. The iframe displays keyed-in card input fields where the customer can enter their payment card details.

    Note

    The customer must enter their payment card details and select the Remember this card checkbox in the iframe to proceed to confirming the setup intent.

  3. Monitor the result of the customer’s actions using the functions of the hosted checkout integration JavaScript SDK. If the customer’s payment card details are valid, the SDK invokes the createPaymentMethod SDK function.

  4. Confirm the setup intent by invoking the confirmIntent SDK function or send a POST request to the /v1/setup-intents/{id}/confirm endpoint of the setup intents API.

    If the payment method is valid, the SDK saves the payment card to the customerId.

    Note

    You must confirm a setup intent within 30 minutes after you create it. The time you created a setup intent is indicated by the creationDate in the response you receive from the v1/setup-intents endpoint of the setup intents API.