Using the hosted checkout integration APIs

Note

To make Toast API requests, you need to include an OAuth 2 bearer authentication token. For more information, see Authentication and restaurant access.

Using a different API hostname for hosted checkout integration requests

To use the hosted checkout integration, you need to use a different hostname in your requests. The hosted checkout integration APIs use a different hostname to maintain security.

You use the different API request hostname with the following APIs:

You get the hostname for the hosted checkout integration APIs from the Toast integrations team.

Accepting a payment using hosted checkout integration APIs

The following procedure is a high-level overview of how to accept a payment using the hosted checkout integration APIs.

Create a payment intent for your customer payment using the /v1/payment-intents endpoint of the payment intents API. Use your Toast API authentication credentials for the server component of your integration. Include the payment amount in the request. Generate and include an identifier for the payment intent in the request.
Initiate a payment session and display the hosted checkout iframe interface to your customer using hosted checkout integration APIs JavaScript SDK. Include the OAuth bearer token that you get with the Toast API authentication credentials for your hosted checkout client.
Monitor the result of the customer payment authorization using functions of the hosted checkout integration APIs JavaScript SDK.
Apply the payment identifier you successfully generated as a payment for a Toast orders API check. The payment must be applied to a Toast order within five minutes of the payment card authorization. After five minutes the Toast platform automatically voids the payment.

Payment intents

A payment intent represents your intent to take a payment from a customer on your checkout page. A payment intent is associated with a single shopping cart or an individual customer shopping session during the checkout phase. For example, you might create a payment intent to pay for a customer's online restaurant order. When you create a payment intent, you must include the payment amount and the currency type.

Creating a payment intent

Note

To create a payment intent, the restaurant has to enable the integration with your hosted checkout provider on the Integrations page in Toast Web. The restaurant has to enable the integration even if your hosted checkout integration is developed by the restaurant organization itself.

There are two options to create a payment intent. You can choose to either create a payment intent for keyed-in card transactions or saved card transactions. For detailed information on how to create a payment intent, see Keyed-in card transactions or Saved card transactions.

If the payment intent is successfully created, the payment intents API generates and returns a PaymentIntentResponse that contains data relating to the payment intent as well as a sessionSecret. The sessionSecret is used to verify communication between your integration and the Toast platform in the iframe. You need to pass an active sessionSecret that you get from a payment intent to the client-side of your application in order to initialize and display the hosted checkout iframe and to create and confirm payments.

Note

The payment intent expires after 24 hours. If the payment intent has expired, you need to create a new payment intent. When you create a new payment intent, this creates a new, corresponding sessionSecret.

Keyed-in card transactions

In a keyed-in card transaction, a customer manually enters payment card details into card input fields for authorization. When a customer places an order, they enter their payment card details on a checkout page to complete the order.

To create a payment intent for keyed-in card transactions, send a POST request to the /v1/payment-intents endpoint of the payment intents API to create a PaymentIntentResponse. Include the Toast-Restaurant-External-ID as a header parameter in the request to specify the GUID of the restaurant that you are creating a payment intent for.

Note

Do not make this request from the ordering interface client browser. You send hosted checkout integration API requests from a server component of your integration.

You can also include a paymentMethodConfigurationId value to enable a customized payment method configuration. A payment method configuration allows you to present various payment methods in your hosted checkout iframe. If you do not include a paymentMethodConfigurationId, your integration uses the default payment method configuration. The default payment method configuration only enables Google Pay®, keyed-in card and saved card payment methods.

You can add, view, and manage payment method configurations on the Payment methods page in the Toast developer portal. For more information, see Managing payment method configurations.

Note

If the hosted checkout integration fails to retrieve your payment method configuration, the iframe defaults to displaying keyed-in and saved card payment methods.

Example request body

{
    "amount": 1000, 
    "currency": "USD", 
    "externalReferenceId": "73edc827-0c18-485f-b581-1ef79f93b940", 
    "captureMethod": "MANUAL", 
    "email": "john.smith@email.com", 
    "paymentMethodConfigurationId": "497f6eca-6276-4993-bfeb-53cbbbba6f08", 
    "paymentMethodId": "f718c101-70e4-45fe-8fc1-67ba0a12a8c5" 
}

	The payment amount in minor units represented as a positive integer. The minimum amount is `0.01` (represented as .01). In this example, `1000` represents ten USD and zero cents.
	Supported currency type is United States Dollar (USD).
	The identifier for the payment intent generated by the restaurant or your integration. The `externalReferenceId` can be applied as a payment identifier for a Toast platform check.
	Controls when funds are captured from the customer's bank account. `MANUAL`: Places a hold on your customer's funds when the payment is authorized. Funds are captured at a later date.
	The customer's email address. The customer's email address only needs to be provided once when you create or update the payment intent.
	(Optional) The identifier of the payment method configuration. The `paymentMethodConfigurationId` enables the payment method configuration in your integration. For more information, see Managing payment method configurations.
	(Optional) The identifier of the payment method associated with the payment intent. For more information, see Getting a list of payment methods attached to a customer record.

Example response body

{
    "id": "86bbcf0c-b483-4bbc-81bf-c2a9cd2baa2c", 
    "externalReferenceId": "73edc827-0c18-485f-b581-1ef79f93b940", 
    "sessionSecret": "PI_86bbcf0c-b483-4bbc-81bf-c2a9cd2baa2c_SECRET_EqYQ5^CgQWc4J?KBwq2jfv&Ov", 
    "amount": 1000,
    "currency": "USD",
    "captureMethod": "MANUAL",
    "status": "REQUIRES_PAYMENT_METHOD", 
    "paymentMethodId": "f718c101-70e4-45fe-8fc1-67ba0a12a8c5",
    "creationDate": "2023-09-29T16:42:36.239579Z", 
    "setupFutureUsage": null, 
    "customerId": null, 
    "amountDetails": {
        "tip": 0,
        "surcharge": null,
        "lineItemModifiers": null
    }, 
    "email": "john.smith@email.com", 
    "paymentMethodConfigurationDetails": { 
        "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08" 
    }, 
    "latestPayment": null, 
    "offSession": false,  
    "standingInstructionType": null 
}

	The identifier of the payment intent. You use this identifier to update the payment intent.
	The identifier for the payment intent generated by the restaurant or your integration. The `externalReferenceId` can be applied as a payment identifier for a Toast platform check.
	A unique identifier for the payment intent that you use to create a payment method.
	The status of the payment intent. Values are: `REQUIRES_PAYMENT_METHOD` `PROCESSING` `REQUIRES_CAPTURE` `REQUIRES_CONFIRMATION` `SUCCEEDED` `REQUIRES_ACTION` `FAILED` `CANCELLED` For more information, see Payment intent status values.
	The date and time the payment intent was created in ISO 8601 format. Toast support recommends that you store the `creationDate` in the server component of your integration. You use the `creationDate` to check that the payment intent has not expired. If the payment intent has expired, you must create a new payment intent.
	Used to determine if the customer will save the payment method for future use. If the payment method can only be used one time, the response returns a `null` value. Values are: `ON_SESSION`: Saves the payment method for future use by the customer. `OFF_SESSION`: Saves the payment method for future use initiated by the restaurant.
	The `paymentMethodConfigurationDetails` object that provides information about payment method configuration. If the `id` is `null`, the hosted checkout `iframe` only enables and presents input fields for keyed-in and saved card payment methods. For more information, see Managing payment method configurations.
	The `latestPayment` object that provides information about the payment associated with the payment intent. The value is `null` until the payment has been confirmed.

Saved card transactions

Note

To initiate the saved cards transaction workflow, your customer must be signed into their profile in your integration. This allows you to include the customerId when you create a payment intent. If your customer has not signed into their profile, they will proceed through the anonymous customer checkout workflow where they can key in their payment card details.

Saved card transactions use payment cards that have been stored for future use by a customer. If you store profiles for easier checkout, you can allow your customers to save payment cards for future use. For more information, see Setup intents. To allow customers to use saved cards, you must create a customer record and include the customerId in the payment intent request body. For more information, see Creating a customer record.

To create a payment intent for saved card transactions, send a POST request to the /v1/payment-intents endpoint of the payment intents API to create a PaymentIntentResponse. Include the customerId in the POST request body, as well as the Toast-Restaurant-External-ID as a header parameter. You can also include a paymentMethodConfigurationId value to enable a customized payment method configuration.

Note

Do not make this request from the ordering interface client browser. You send hosted checkout integration API requests from a server component of your integration.

The saved cards transaction workflow displays the Remember this card checkbox. Customers can then choose to checkout with a saved card or choose to enter their payment card details and then select the Remember this card checkbox to save the payment card to their customer profile.

Remember this card checkbox emphasized in an iframe.

If your customer signs into their profile after the payment intent was created, send a POST request to update the payment intent with the customerId. This allows the iframe to detect and initiate the save cards transaction workflow. For more information, see Updating a payment intent.

Example request body

{
    "amount": 1000,
    "currency": "USD", 
    "externalReferenceId": "73edc827-0c18-485f-b581-1ef79f93b940", 
    "captureMethod": "MANUAL",
    "customerId": "4b2dfc5a-88a3-11ee-b9d1-0242ac120002",    
    "email" : "john.smith@email.com" 
    "paymentMethodConfigurationId": "497f6eca-6276-4993-bfeb-53cbbbba6f08",  
    "paymentMethodId": "f718c101-70e4-45fe-8fc1-67ba0a12a8c5" 
}

	The identifier for the payment intent generated by the restaurant or your integration. The `externalReferenceId` can be applied as a payment identifier for a Toast platform check.
	The identifier for the customer record that identifies the customer in the Toast platform and allows them to choose from payment cards saved to their profile.
	The customer's email address.

Example response body

{
    "id": "86bbcf0c-b483-4bbc-81bf-c2a9cd2baa2c", 
    "externalReferenceId": "73edc827-0c18-485f-b581-1ef79f93b940", 
    "sessionSecret": "PI_86bbcf0c-b483-4bbc-81bf-c2a9cd2baa2c_SECRET_EqYQ5^CgQWc4J?KBwq2jfv&Ov", 
    "amount": 1000,
    "currency": "USD",
    "captureMethod": "MANUAL",
    "status": "REQUIRES_PAYMENT_METHOD",
    "paymentMethodId": "f718c101-70e4-45fe-8fc1-67ba0a12a8c5",
    "creationDate": "2023-09-29T16:42:36.239579Z", 
    "setupFutureUsage": null, 
    "customerId": "4b2dfc5a-88a3-11ee-b9d1-0242ac120002",
    "amountDetails": {
        "tip": 0,
        "surcharge": null,
        "lineItemModifiers": null
    }, 
    "email": "john.smith@email.com", 
    "paymentMethodConfigurationDetails": { 
        "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08" 
    },
    "latestPayment": null,
    "offSession": false,   
    "standingInstructionType": null 
}

	The identifier of the payment intent.
	A unique identifier for the payment intent that you use to create a payment method.

The response contains a payment intent and sessionSecret and initializes and loads the iframe onto your checkout page. In the iframe, the customer can see and select from their saved cards to use as a payment method.

Updating a payment intent

Note

Before updating the payment intent, check that the payment intent has not expired. The payment intent is valid for 24 hours from the creationDate. To check if the payment intent is still valid, compare the creationDate returned in the PaymentIntentResponse with the current time. If your customer's shopping cart is more than 24 hours old, updating the original payment intent results in a 404 error.

If your customer adds a tip, applies a discount, or adds more items to their order, you must update the payment intent to reflect the new amount. You send a POST request to the /v1/payment-intents/{paymentIntentId} endpoint of the payment intents API with the final amount to be charged upon checkout.

You must include the tip amount in the AmountDetails object with the updated payment amount. You must update the payment intent with the final amount and tip before the customer enters payment details in the hosted checkout integration iframe. You update the payment intent from the server component of your integration (not from the client browser).

If your customer has not signed into their profile during the checkout process, they can choose to sign in when they update the payment intent. Include the customerId in the POST request body to /v1/payment-intents/{paymentIntentId} endpoint to update the payment intent. Then invoke the fetchUpdates function to fetch the updates applied to the payment intent, including the updated amount and the customerId. The client-side of your integration calls the fetchUpdates function in the Toast object, which re-renders the hosted checkout integration iframe to show the customer’s saved cards and the Remember this card checkbox.

Note

If you only want to update the customer's email address, you do not have to update the amount or amountDetails.

Example request body

{
    "amount" : 2000, 
    "email": "john.smith@email.com", 
    "amountDetails": { 
        "tip": 100 
    }
}

	The updated payment amount to be charged. In this example, `2000` represents twenty USD and zero cents.
	This value only appears if you include a customer's email address when you create or update a payment intent.
	The tip amount to be charged. Tip can only be added when you update the payment intent. In this example, `100` represents one USD and zero cents.

Example response body

{
    "id": "86bbcf0c-b483-4bbc-81bf-c2a9cd2baa2c",
    "externalReferenceId": "73edc827-0c18-485f-b581-1ef79f93b940",
    "sessionSecret": "PI_86bbcf0c-b483-4bbc-81bf-c2a9cd2baa2c_SECRET_EqYQ5^CgQWc4J?KBwq2jfv&Ov",
    "amount": 2000,
    "currency": "USD",
    "captureMethod": "MANUAL",
    "status": "REQUIRES_PAYMENT_METHOD", 
    "paymentMethodId": null,
    "creationDate": "2023-09-29T16:42:36.239579Z",
    "setupFutureUsage": null,
    "customerId": "4b2dfc5a-88a3-11ee-b9d1-0242ac120002", 
    "amountDetails": {
        "tip": 100,
        "surcharge": null,
        "lineItemModifiers": null
    }, 
    "email": "john.smith@email.com", 
    "paymentMethodConfigurationDetails": { 
        "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08"  
    },
    "latestPayment": null,
    "offSession": false,   
    "standingInstructionType": null 
}

The status of the payment intent. A payment intent with a status of PROCESSING or REQUIRES_CAPTURE cannot be updated. Any request to update the payment intent with either of those statuses returns an error.

Confirming a payment intent

Note

You can only call the /v1/payment-intents/{paymentIntentId}/confirm endpoint if your customer has previously saved a card to their customer profile in your integration. For more information, see Setup intents.

After you have created a payment intent and attached a payment method, the next step is to confirm the payment intent. Confirming the payment intent represents your customer’s intention to pay the amount with the attached payment method. If the payment intent is successfully confirmed, the hosted checkout client SDK initiates and captures the payment.

There are two methods to confirm a payment intent. You can choose either:

Customer-initiated confirmation: Confirm a payment intent using the confirmIntent function.
Integration-initiated confirmation: Send a POST request to the /v1/payment-intents/{paymentIntentId}/confirm endpoint of the payment intents API.

You use the confirmIntent function to initiate a payment based on your customer's actions in the hosted checkout iframe. To confirm a payment without your customer's initiation, send a POST request to the /v1/payment-intents/{paymentIntentId}/confirm endpoint of the payment intents API. For example, send a POST request if your integration allows dine-in orders and needs to auto-close checks at the end of the day or when a customer leaves your restaurant without paying their check.

Note

If you created a payment intent with a saved card as the payment method, you must include the customerId in the request body. The customerId is required to ensure that the payment intent is not confirmed with the wrong payment method.

To confirm a payment intent without customer initiation, send a POST request to the /v1/payment-intents/{paymentIntentId}/confirm endpoint of the payment intents API to create a PaymentIntentResponse. Include the paymentIntentId in the request path. All other request fields are optional. Include the Toast-Restaurant-External-ID as a header parameter.

Example request body

{
"email": "john.smith@email.com"  
}

The customer’s email address. The customer’s email address is required if it was not provided when the payment intent was created or updated.

Example response body

{
    "id": "86bbcf0c-b483-4bbc-81bf-c2a9cd2baa2c", 
    "externalReferenceId": "73edc827-0c18-485f-b581-1ef79f93b940",
    "sessionSecret": "PI_86bbcf0c-b483-4bbc-81bf-c2a9cd2baa2c_SECRET_EqYQ5^CgQWc4J?KBwq2jfv&Ov",
    "amount": 2000,
    "currency": "USD",
    "captureMethod": "MANUAL",
    "status": "REQUIRES_CAPTURE", 
    "paymentMethodId": "f718c101-70e4-45fe-8fc1-67ba0a12a8c5",
    "creationDate": "2023-09-29T16:42:36.239579Z",
    "setupFutureUsage": null,
    "customerId": "4b2dfc5a-88a3-11ee-b9d1-0242ac120002", 
    "amountDetails": {
        "tip": 100,
        "surcharge": null,
        "lineItemModifiers": null
    }, 
    "email": "john.smith@email.com", 
    "paymentMethodConfigurationDetails": { 
        "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08"  
    },
    "latestPayment": { 
        "card": {
             "brand": "VISA",
             "lastFour": "1111",
             "expiry": {
                 "month": "12", 
                 "year": "27"
             }  
         } 
    }, 
    "offSession": false,   
    "standingInstructionType": null 
}

	The unique identifier of the payment intent.
	Payment card details associated with the latest payment intent.

Payment intent status values

The statuses represent the various states of a customer's payment as it interacts with the hosted checkout integration.

REQUIRES_PAYMENT_METHOD: The initial status of the payment intent. A payment method must be attached to the payment intent before the payment intent can be confirmed and the payment captured. Attempts to confirm a payment intent with this status will fail. A payment intent moves back to the REQUIRES_PAYMENT_METHOD status if the payment method fails to authorize the payment.

PROCESSING: The payment intent moves to the PROCESSING status once your integration calls the confirmPayment function. The payment intent cannot be modified while in the PROCESSING status. Modifications to the payment intent return an HTTP 409 conflict response code until the payment intent moves into the REQUIRES_PAYMENT_METHOD or REQUIRES_CAPTURE status.

Important

In the event of a payment processor outage, the confirm payment intent endpoint results in the payment intent remaining in the PROCESSING status. The hosted checkout integration invokes the success callback function in the SDK, but it is up to you to decide if a payment intent in the PROCESSING status after confirm payment intent returns is acceptable as a success or a failure. If you accept the risk that the payment authorization may fail once the payment processor comes back online, you can consider the payment intent as a success and proceed with creating the order. If you do not accept the risk and want to consider the payment intent as a failure, you should not proceed with creating the order.

REQUIRES_CAPTURE: The payment intent moves into the REQUIRES_CAPTURE status if the payment intent has been successfully confirmed. The payment method has an associated authorization that can capture the payment amount in the payment intent. You use the externalReferenceId in the payment intent as the payment identifier for a Toast platform check.
REQUIRES_CONFIRMATION: This status is reserved for future use.
SUCCEEDED: This status is reserved for future use.
REQUIRES_ACTION: This status is reserved for future use.
FAILED: This status is reserved for future use.
CANCELLED: This status is reserved for future use.

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 for future use include improving the customer checkout experience, simplifying the checkout process for recurring payments, 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.

Send a POST request to v1/setup-intents endpoint of the setup intents API to return a SetupIntent response. Use your Toast API authentication credentials for the server component of your integration.

Use the Toast API authentication 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 APIs JavaScript SDK. If the customer’s payment card details are valid, the SDK invokes the createPaymentMethod SDK function.
Invoke the confirmIntent SDK function to confirm the setup intent. If the payment method is valid, the SDK associates the payment method with the customerId.

Note

You must confirm a setup intent within 30 minutes of when 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. The sessionSecret from the SetupIntent response expires after 30 minutes. If the setup intent has expired, you need to create a new setup intent.

The process to create and confirm a setup intent uses some of the same hosted checkout integration Javascript SDK functions used to create a payment intent. The SDK functions used are the monitor and createPaymentMethod functions. The setup intent workflow uses a new SDK function, the confirmIntent function, which is used to confirm a payment intent and setup intent.

Note

The confirmPayment SDK function is deprecated and has been replaced by the confirmIntent SDK function.

Creating a setup intent

Note

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

To create a setup intent, you send a POST request to the v1/setup-intents endpoint of the setup intents API. Include the customerId and usage in the request body. The customerId represents the customer’s identity in your integration. For more information about customer identifiers, see Creating a customer record.

Example request body

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

	The unique identifier of the customer record.
	Used to determine if the customer will save the payment method for future use. Set the value to `ON_SESSION`.

Example response body

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

	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.

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 id, the identifier of the setup intent, in the request path.

Example response body

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

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.

After you pass the sessionSecret into the initalize SDK function, the SDK function inserts the iframe onto 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.

If a payment method was successfully created, your integration invokes the confirmIntent function to associate the payment method with the customer record.

Note

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

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 attached to 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.