Confirming a setup intent

Note

You must confirm a setup intent within 30 minutes of the creationDate before the sessionSecret expires and the setup intent is no longer modifiable.

Confirming the setup intent represents your customer’s intention to save their payment card to their profile in your integration. After you have successfully created the setup intent and attached a payment method, you confirm the setup intent to save the payment card. If the setup intent is successfully confirmed, the hosted checkout SDK initiates an authorization for $0.00 and saves the card.

Similar to a payment intent, there are two ways to confirm a setup intent:

  • Customer-initiated confirmation: You use the confirmIntent function to initiate a payment based on your customer's actions in the hosted checkout iframe.

    Note

    The confirmIntent SDK function can be used to confirm both payment intents and setup intents.

  • Integration backend-initiated confirmation: You send a POST request to the /v1/setup-intents/{id}/confirm endpoint of the setup intents API after you have collected your customer’s payment method details. For example, you can use the integration backend-initiated confirmation to save a customer’s payment card to be used for a future merchant-initiated transaction, such as if you charge a reservation deposit (no-show fee) for customers to book a table at restaurant.

    Important

    If you collected customer payment information outside the iframe, you might need to consider regulatory compliance related to the way you store and handle that information. For example, Payment Card Industry Data Security Standard (PCI DSS) regulations might apply to the way you handle customer payment method information. Toast does not provide legal guidance. Make sure you seek legal guidance for regulatory compliance.

Customer-initiated setup intent confirmation

After you call the initialize SDK function, the SDK function inserts the iframe in a webpage in your integration. The iframe renders the keyed-in card input fields in the iframe for the customer to enter their payment card details. The monitor function observes customer actions within the iframe. The monitor function checks that the customer has entered valid payment card details and selected the Remember this card checkbox. If both actions have been successfully completed, the SDK sets the isValid value to true, and your integration invokes the createPaymentMethod function to create a payment method.

Integration backend-initiated confirmation for setup intent transactions

To confirm a setup intent without customer initiation, send a POST request to the /v1/setup-intents/{id}/confirm endpoint of the setup intents API to authorize the payment method. Include the setupIntentId in the request path. Include the Toast-Restaurant-External-ID as a header parameter. In the request body, include the sessionSecret and paymentMethodId.

There are multiple ways to retrieve the paymentMethodId to include in the request body:

Example request body

{
    "paymentMethodId": "f718c101-70e4-45fe-8fc1-67ba0a12a8c5",
    "sessionSecret": "SI_1fdd6e15847148538862b755a23816d2_SECRET_1234abw125" 
}

Example response body

{
    "id": "4b30480b-848c-4667-ae68-045304a6edc9", 1
    "customerId": "611c1e47-8ba3-457b-8879-196da2c427ff"",
    "sessionSecret": "SI_1fdd6e15847148538862b755a23816d2_SECRET_1234abw125",
    "paymentMethodId": "f718c101-70e4-45fe-8fc1-67ba0a12a8c5",
    "status": "SUCCEEDED", 2
    "usage": "ON_SESSION", 
    "creationDate": "2024-03-26T16:17:27Z"
    "standingInstructionType": null, 
    "mandateId": null
}

1

The unique identifier of the setup intent.

2

The status of the setup intent. For more information, see Setup intent statuses.


Integration backend-initiated confirmation for future merchant-initiated transactions

To confirm a setup intent for future merchant-initiated transactions, send a POST request to the /v1/setup-intents/{id}/confirm endpoint of the setup intents API to authorize the payment method. Include the setupIntentId in the request path. Include the Toast-Restaurant-External-ID as a header parameter. In the request body, include the sessionSecret and paymentMethodId.

Example request body

{
   "paymentMethodId": "3169e4f9-6a60-40dd-b87d-f4862f71d3b5",
   "sessionSecret": "SI_77c41db8-e734-46f0-8df4-16c053cfd6c5_SECRET_8zik1gYp*7objjB.ToCES-qkJI" 
}

If the setup intent was successfully confirmed, the setup intents API returns a SetupIntent response that contains the mandateId required to create a merchant-initiated transaction.

Example response body

{
    "id": "4b30480b-848c-4667-ae68-045304a6edc9", 
    "customerId": "87d8e330-2878-4742-a86f-dbbb3bf522ac",
    "sessionSecret": "SI_77c41db8-e734-46f0-8df4-16c053cfd6c5_SECRET_8zik1gYp*7objjB.ToCES-qkJ",
    "paymentMethodId": "f718c101-70e4-45fe-8fc1-67ba0a12a8c5",
    "status": "SUCCEEDED", 1
    "usage": "OFF_SESSION", 
    "creationDate": "2024-03-26T16:17:27Z"
    "standingInstructionType:" "UNSCHEDULED", 
    "mandateId" : "b0e07e0f-ac2c-44e0-b589-482dcb97af64" 2
}

1

The status of the setup intent. This indicates that the setup intent has been successfully confirmed and associated with the customer record.

2

The identifier of the mandate. The mandateId is used by the Toast platform to retrieve the standingInstructionType for the customer’s payment card. You include the mandateId in the POST request to create a payment intent for merchant-initiated transactions. The mandateId contains the following information:

  • customerId

  • paymentMethodId

  • standingInstructionType

  • status. This indicates if the mandate is active or inactive and can be used for merchant-initiated transactions.

  • createdAt

  • externalReferenceId