Customer-initiated setup intent transactions

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.

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.

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.

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.

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.

Creating a setup intent

Note

The setup intents API only supports keyed-in card payment methods.

To create a setup intent, send a POST request to the v1/setup-intents endpoint of the setup intents API. In the request body, include the customerId and set the usage value to ON_SESSION to save the payment card for future customer-initiated transactions.

Example request body

{
    "customerId": "611c1e47-8ba3-457b-8879-196da2c427ff", 
    "usage": "ON_SESSION" 
}

The unique identifier of the customer record. For more information about customer records, see Creating a customer record.

Used to determine if the customer will save the payment method for future use. Set the value to ON_SESSION to set up and save the payment method to the customer's profile for future customer-initiated transactions. The customer has selected the Remember this card checkbox in the hosted checkout iframe. The payment card cannot be used for merchant-initiated transactions.

Note

You must include the customerId to set the usage value to ON_SESSION. The payment card must be saved to a customer record.

Example response body

{
    "id":"1fdd6e15-8471-4853-8862-b755a23816d2", 
    "customerId": "611c1e47-8ba3-457b-8879-196da2c427ff", 
    "sessionSecret": "SI_1fdd6e15847148538862b755a23816d2_SECRET_1234abw125",
    "paymentMethodId": null, 
    "status": "REQUIRES_PAYMENT_METHOD", 
    "usage": "ON_SESSION",
    "creationDate": "2024-03-26T16:17:27Z", 
    "standingInstructionType": null,
    "mandateId": null 
}

	The unique identifier for the setup intent.
	The status of the setup intent. The initial status is `REQUIRES_PAYMENT_METHOD` until a payment method is attached. The values are: `REQUIRES_PAYMENT_METHOD` `PROCESSING` `SUCCEEDED`

For more information, see Setup intent statuses.

If the customerId in the request body cannot be found, the Toast platform returns an error response.

Future merchant-initiated transactions

To create a setup intent for future merchant-initiated transactions, send a POST request to the v1/setup-intents endpoint of the setup intents API. In the request body, set the usage value to OFF_SESSION to save the payment card for future merchant-initiated transactions. In the request body, include a standingInstructionType value.

Optionally, you can choose to include the customerId in the request body. The customerId represents the customer’s identity in your integration and is associated with a customer record. If you do not include the customerId, this allows the customer to create a card to be the card-on-file without having to create a customer profile. For example, you might have a customer who likes to make reservations at your restaurant, but does not want to create a customer profile. They could have a card-on-file at your restaurant to pay for reservation fees.

Example request body

{
  "usage": "OFF_SESSION", 
  "standingInstructionType": "UNSCHEDULED" 
}

Used to determine if the customer will save the payment method for future use. Set the value to OFF_SESSION to set up and store the payment method as a card-on-file for future merchant-initiated transactions. The customer has selected the I authorize this business to charge my card as outlined in the terms checkbox in the hosted checkout iframe.

Note

The payment card is not saved to the customer’s profile.

The type of merchant-initiated recurring transaction. Values are:

RECURRING: A series of set payments that are charged at regular intervals.
INSTALLMENT: The total purchase amount is split into a fixed number of periodic payments.
UNSCHEDULED: A merchant-initiated single payment that is not part of a subscription.

Example response body

{
    "id": "77c41db8-e734-46f0-8df4-16c053cfd6c5", 
    "sessionSecret": "SI_77c41db8-e734-46f0-8df4-16c053cfd6c5_SECRET_8zik1gYp*7objjB.ToCES-qkJ",
    "paymentMethodId": null,
    "status": "REQUIRES_PAYMENT_METHOD",
    "usage": "OFF_SESSION",
    "creationDate": "2024-03-26T16:17:27Z"
    "standingInstructionType": "UNSCHEDULED",
    "mandateId": null 
}

The unique identifier for the setup intent.

Updating a setup intent

If you need to update a setup intent, send a POST request to the v1/setup-intents/{id} endpoint of the setup intents API. You can update the following values:

customerId
usage

For example, you can update the customerId if you need to change the customer profile that the setup intent is associated with. You can also update the usage value, which indicates how the setup intent will be used in the future. The usage value should always be set to ON_SESSION or omitted from the request body for customer-initiated transactions. Update the usage value to OFF_SESSION for merchant-initiated transactions. For more information, see Creating a setup intent for future merchant-initiated transactions.

Example request body

{
    "usage": "ON_SESSION", 
    "customerId": "46ed1272-a628-4d7a-9f7b-d27d8e88cf18", 
    "sessionSecret": "SI_1fdd6e15847148538862b755a23816d2_SECRET_1234abw125"
}

	Used to determine if the customer will save the payment method for future use.
	The unique identifier for the customer record that identifies the customer in the Toast platform.

Example response body

{
    "id": "1fdd6e15-8471-4853-8862-b755a23816d2",
    "customerId": "46ed1272-a628-4d7a-9f7b-d27d8e88cf18",
    "sessionSecret": "SI_1fdd6e15847148538862b755a23816d2_SECRET_1234abw125",
    "paymentMethodId": null,
    "status": "REQUIRES_PAYMENT_METHOD", 
    "usage": "ON_SESSION", 
    "creationDate": "2024-03-26T16:17:27Z"
    "standingInstructionType": null,
    "mandateId": null
}

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

Creating a payment method

Similar to a payment intent, you can use the createPaymentMethod SDK function or send a POST request to the v1/payment-methods endpoint of the payment methods API to create a payment method.

In the request body, include the payment method type and card details. Set the usage value to ON_SESSION if the customer wants to save the payment method for future use. Include the following header parameters:

Toast-Session-Secret: The unique and randomized identifier for the payment or setup intent. This is returned in the response to create a payment or setup intent.
Toast-Idempotency-Key: An integration-generated universally unique identifier (UUID) that is used to recognize retries of the same request.

Example request body

{
    "type": "CARD", 
    "card": { 
      "number": "4242424242424242", 
      "cvv": "123",
      "expiry": { 
        "month": "12",
        "year": "27"
      }
    },
    "billingDetails": {
       "postalCode": "02118"
    },
    "usage": "OFF_SESSION" 
}

	The type of payment method created. The value is: `CARD`.
	The card details used to tokenize the payment card.
	The primary account number (PAN) of the card, which the API validates using the ISO-standard Luhn algorithm.
	Used to determine if the customer will save the payment method for future use. Set the value to `ON_SESSION` to save the payment card for future customer use. If the customer does not want to save the payment card for future use, set the value to `null`.

Example response body

{
    "id": "f718c101-70e4-45fe-8fc1-67ba0a12a8c5", 
    "type": "CARD",
    "usage": "OFF_SESSION"
    "card": {
        "firstSix": "411111",
        "lastFour": "1111",
        "expiry": {
            "month": "12",
            "year": "27"
        },
        "brand": "VISA",
        "type": "VISA", 
        "fingerprint": "e19f9942-942b-4716-a45c-6ee69225970d", 
        "funding": "Debit",

        [contents omitted]
    }
}

Future merchant-initiated transactions

To create a payment method for merchant-initiated transactions, you can use the createPaymentMethod SDK function or send a POST request to the v1/payment-methods endpoint of the payment methods API. In the request body, include the payment method type and card details. Set the usage value to OFF_SESSION to use for future transactions or ON_AND_OFF_SESSION if the customer wants to save the payment method to use for both customer and merchant-initiated transactions. Include the following header parameters:

Toast-Session-Secret: The unique and randomized identifier for the payment or setup intent. This is returned in the response to create a payment or setup intent.
Toast-Idempotency-Key: An integration-generated universally unique identifier (UUID) that is used to recognize retries of the same request.

Example request body

{
    "type": "CARD", 
    "card": { 
      "number": "4242424242424242", 
      "cvv": "123",
      "expiry": { 
        "month": "12",
        "year": "27"
      }
    },
    "billingDetails": {
       "postalCode": "02118"
    },
    "usage": "OFF_SESSION" 
}

The type of payment method created. The value is: CARD.

The card details used to tokenize the payment card.

The primary account number (PAN) of the card, which the API validates using the ISO-standard Luhn algorithm.

Used to determine if the customer will save the payment method for future use.

ON_SESSION: Stores and saves the payment method to the customer’s profile and creates a card-on-file for future customer-initiated transactions. The customer has selected the Remember this card checkbox in the hosted checkout iframe.

You must have have included the customerId in the request body to create a setup intent to set the usage value to ON_SESSION.

Note

The payment card cannot be used for merchant-initiated transactions.

OFF_SESSION: Stores the payment method and creates a card-on-file for merchant-initiated transactions. The customer has selected the I authorize this business to charge my card as outlined in the terms checkbox in the hosted checkout iframe.

Note

The payment card is not saved to the customer’s profile.

ON_AND_OFF_SESSION: Stores and saves the payment method to the customer’s profile and creates a card-on-file for both customer and merchant-initiated transactions. The customer has selected both the Remember this card checkbox and the I authorize this business to charge my card as outlined in the terms checkbox in the hosted checkout iframe.

You must have included the customerId in the request body to create a setup intent to set the usage to ON_AND_OFF_SESSION.

Example response body

{
    "id": "f718c101-70e4-45fe-8fc1-67ba0a12a8c5", 
    "type": "CARD",
    "usage": "OFF_SESSION"
    "card": {
        "firstSix": "411111",
        "lastFour": "1111",
        "expiry": {
            "month": "12",
            "year": "27"
        },
        "brand": "VISA",
        "type": "VISA", 
        "fingerprint": "e19f9942-942b-4716-a45c-6ee69225970d", 
        "funding": "Debit",

        [contents omitted]
    }
}

The identifier of the payment method.

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:

Retrieve the paymentMethodId by sending a GET request to the /v1/customers/{id}/payment-methods endpoint of the customers API.
Retrieve the paymentMethodId from the CreatePaymentMethodResultEventContent if the payment method was successfully created using the createPaymentMethod function.
Retrieve the paymentMethodId from the PaymentMethodResponse if the payment method was successfully created using the create payment method API endpoint.

Example request body

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

Example response body

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

	The unique identifier of the setup intent.
	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", 
    "usage": "OFF_SESSION", 
    "creationDate": "2024-03-26T16:17:27Z"
    "standingInstructionType:" "UNSCHEDULED", 
    "mandateId" : "b0e07e0f-ac2c-44e0-b589-482dcb97af64" 
}

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

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

Getting a setup intent

To get the details of a setup intent or to check if a setup intent was successfully created, send a GET request to the v1/setup-intents/{id} endpoint of the setup intents API. Include the setupIntentId in the request path.

Example response body

{
    "id": "4b30480b-848c-4667-ae68-045304a6edc9", 
    "customerId": "611c1e47-8ba3-457b-8879-196da2c427ff",
    "sessionSecret": "SI_1fdd6e15847148538862b755a23816d2_SECRET_1234abw125",
    "paymentMethodId": null, 
    "status": "REQUIRES_PAYMENT_METHOD",
    "usage": "ON_SESSION",
    "creationDate": "2024-03-26T16:17:27Z"
    "standingInstructionType": null, 
    "mandateId": null
}

Setup intent statuses

The following statuses represent the various states of a payment card being set up and saved by a customer for future use. For more information about how to get the details of a setup intent, see Getting a setup intent.

REQUIRES_PAYMENT_METHOD: The initial status of the setup intent. A payment method must be associated with the setup intent before the payment method can be saved.

A setup intent moves back to the REQUIRES_PAYMENT_METHOD status if the setup intent fails to be confirmed.
PROCESSING: The setup intent moves to the PROCESSING status once your integration calls the confirmIntent SDK function. The setup intent cannot be modified while in the PROCESSING status.
SUCCEEDED: The setup intent moves into the SUCCEEDED status if the setup intent has been successfully confirmed and associated with the customer record. The payment method can be used for future transactions and payments.