Customer-initiated payment intent transactions

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 create a payment intent for a customer's online order. When you create a payment intent, you must include the payment amount and the currency type.

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

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

2. Send a POST request to the v1/payment-methods endpoint of the payment methods API to create a payment method to attach to the payment intent. This returns a PaymentMethodResponse.

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

Creating a payment intent

Note

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

You can create a payment intent for three transaction types:

• Keyed-in card transactions

• Saved card transactions

• Future merchant-initiated transactions

If the payment intent is successfully created, the payment intents API returns a PaymentIntentResponse that contains payment intent details as well as a sessionSecret string. The sessionSecret is used to verify communication between your integration and the Toast platform in the iframe. You need to pass an active sessionSecret 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

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.

For a keyed-in card transaction, the customer manually enters payment card details into card input fields for authorization. When the customer places an order, they enter their payment card details and submit the payment 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 return a PaymentIntentResponse. Include the Toast-Restaurant-External-ID as a header parameter in the request to specify the GUID of the Toast POS location that you are creating a payment intent for.

You can also include a paymentMethodConfigurationId value to enable a custom 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, (1)
    "currency": "USD", (2)
    "externalReferenceId": "73edc827-0c18-485f-b581-1ef79f93b940", (3)
    "captureMethod": "MANUAL", (4)
    "email": "[e-mail]", (5)
    "paymentMethodConfigurationId": "497f6eca-6276-4993-bfeb-53cbbbba6f08", (6)
    "paymentMethodId": "f718c101-70e4-45fe-8fc1-67ba0a12a8c5" (7)
}

• (1):

  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.

• (2):

  The supported currency type is the United States Dollar (USD).

• (3):

  The identifier for the payment intent generated by the Toast POS location or your integration. The externalReferenceId can be applied as a payment identifier for a Toast POS check.

• (4):

  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.

  • AUTOMATIC: Reserved for future use.

• (5):

  The customer's email address. The customer's email address only needs to be provided once when you create, update, or confirm the payment intent.

• (6):

  (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.

• (7):

  (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", (1)
    "externalReferenceId": "73edc827-0c18-485f-b581-1ef79f93b940", (2)
    "sessionSecret": "PI_86bbcf0c-b483-4bbc-81bf-c2a9cd2baa2c_SECRET_EqYQ5^CgQWc4J?KBwq2jfv&Ov", (3)
    "amount": 1000,
    "currency": "USD",
    "captureMethod": "MANUAL",
    "status": "REQUIRES_PAYMENT_METHOD", (4)
    "paymentMethodId": "f718c101-70e4-45fe-8fc1-67ba0a12a8c5",
    "creationDate": "2023-09-29T16:42:36.239579Z", (5)
    "usage": null, (6)
    "customerId": null, 
    "amountDetails": {
        "tip": 0
    }, 
    "email": "[e-mail]", 
    "paymentMethodConfigurationDetails": { (7)
        "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08" 
    }, 
    "latestPayment": null, (8)
    "offSession": false,  
    "standingInstructionType": null, 
    "mandateId": null 
}

• (1):

  The identifier of the payment intent. You use this identifier to update the payment intent. For more information, see Updating a payment intent.

• (2):

  The identifier for the payment intent generated by the Toast POS location or your integration. The externalReferenceId can be applied as a payment identifier for a Toast POS check.

• (3):

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

• (4):

  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 statuses.

• (5):

  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.

• (6):

  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. Usage 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 Toast POS location (merchant).

  • ON_AND_OFF_SESSION: Saves the payment method for future use by either the customer or the Toast POS location.

• (7):

  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.

• (8):

  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. For more information, see Setup intents. To allow a customer to use their saved cards, you must create a customer record. For more information, see Creating a customer record.

The following procedure is a high-level overview of how to create a payment intent for a saved card transaction:

1. Use your hosted checkout - payment credentials to send a POST request to the /v1/customers endpoint of the customers API to create a customer record. This returns a customerId.

2. Send a POST request to the /v1/payment-intents endpoint of the payment intents API and include the customerId in the request body. This returns a PaymentIntentResponse.

Note

Do not make the request to create a payment intent for a saved card transaction from the ordering interface client browser. You send hosted checkout integration API requests from a server component of your integration.

To create a payment intent for saved card transactions, send a POST request to the /v1/payment-intents endpoint of the payment intents API. Include the customerId in the request body and the Toast-Restaurant-External-ID as a header parameter. You can also include a paymentMethodConfigurationId value to enable a custom payment method configuration. For more information, see Managing payment method configurations.

The saved cards transaction workflow displays the Remember this card checkbox in the hosted checkout iframe. 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.

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", (1)
    "captureMethod": "MANUAL",
    "customerId": "4b2dfc5a-88a3-11ee-b9d1-0242ac120002",  (2)  
    "email" : "[e-mail]", (3)
    "paymentMethodConfigurationId": "497f6eca-6276-4993-bfeb-53cbbbba6f08",  
    "paymentMethodId": "f718c101-70e4-45fe-8fc1-67ba0a12a8c5" 
}

• (1):

  The identifier for the payment intent generated by the Toast POS location or your integration. The externalReferenceId can be applied as a payment identifier for a Toast POS check.

• (2):

  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.

• (3):

  The customer's email address.

Example response body

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

• (1):

  The identifier of the payment intent.

• (2):

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

• (3):

  The status of the payment intent. For more information, see Payment intent statuses.

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.

Future merchant-initiated transactions

To complete a merchant-initiated transaction, you must first complete a customer-initiated payment or setup intent transaction where the customer is actively participating. The customer must authorize the payment card for future use during this transaction.

To create a payment intent that saves the payment method for merchant-initiated transactions, send a POST request to the /v1/payment-intents endpoint of the payment intents API to return a PaymentIntentResponse. Include the Toast-Restaurant-External-ID as a header parameter in the request to specify the GUID of the Toast POS location that you are creating a payment intent for. Set the offSession value to false to indicate that this is a customer-initiated transaction as part of the merchant-initiated transaction workflow.

In the request body, provide a value for the standingInstructionType. The standingInstructionType is the instruction type used by the merchant and sent to the payment processor. Choose from one of the following values:

• RECURRING: A series of set payments that are charged at regular intervals. For example, use recurring payments for a monthly wine club subscription.

• INSTALLMENT: The total purchase amount is split into a fixed number of periodic payments. For example, use installment payments to pay for a wedding cake, where the cake is paid off in five installments.

• UNSCHEDULED: A single merchant-initiated payment. For example, use an unscheduled payment for a restaurant reservation fee.

You can also include a paymentMethodConfigurationId value to enable a custom payment method configuration. For more information, see Managing payment method configurations.

Example request body

{
    "amount": 1000, (1)
    "currency": "USD", (2)
    "externalReferenceId": "73edc827-0c18-485f-b581-1ef79f93b940", (3)
    "captureMethod": "MANUAL", (4)  
    "email" : "[e-mail]", (5)
    "offSession": false, (6)
    "standingInstructionType": "RECURRING", (7)
    "paymentMethodConfigurationId": "497f6eca-6276-4993-bfeb-53cbbbba6f08", (8)
    "paymentMethodId": "f718c101-70e4-45fe-8fc1-67ba0a12a8c5" (9)
}

• (1):

  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.

• (2):

  The supported currency type is the United States Dollar (USD).

• (3):

  The identifier for the payment intent generated by the Toast POS location or your integration. The externalReferenceId can be applied as a payment identifier for a Toast POS check.

• (4):

  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.

  • AUTOMATIC: Reserved for future use.

• (5):

  The customer's email address. The customer's email address only needs to be provided once when you create, update, or confirm the payment intent.

• (6):

  Used to determine if the transaction is a customer-initiated transaction or a merchant-initiated transaction.

  • Set the offSession value to false to indicate that the transaction is customer-initiated. If no value is provided, the value defaults to false.

  • Set the offSession value to true to indicate that the transaction is merchant-initiated. For more information, see Creating a payment intent for a merchant-initiated transaction.

• (7):

  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 single merchant-initiated payment.

• (8):

  (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.

• (9):

  (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": "a9c8a2b0-a824-46df-a6dc-4415c556df94",
    "externalReferenceId": "73edc827-0c18-485f-b581-1ef79f93b940",
    "sessionSecret": "PI_a9c8a2b0-a824-46df-a6dc-4415c556df94_SECRET_JT!M!YA4zL1yxrGHnC6PrYTQX",
    "amount": 100,
    "currency": "USD",
    "captureMethod": "MANUAL",
    "status": "REQUIRES_PAYMENT_METHOD",
    "creationDate": "2025-11-19T20:04:33.052477879Z",   
    "customerId": null,
    "amountDetails": {
       "tip": 100
    },
    "email": "[e-mail]",
    "paymentMethodConfigurationDetails": {
        "id": "5855c2ae-e3aa-45d9-b78d-88fafacf0ec2"
    },
    "standingInstructionType": "RECURRING",
    "latestPayment": null,
    "offSession": false,
    "mandateId": null 
}

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.

There are various customer actions where you must update the payment intent. You must update the payment intent with the new amount to be charged if your customer completes any of the following actions:

• Adds a tip

• Applies a discount

• Adds more items to their order

You can choose to update the payment intent if your customer wants to sign into their profile during the checkout process. 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.

To update the payment amount, send a POST request to the /v1/payment-intents/{paymentIntentId} endpoint of the payment intents API with the updated amount to be charged upon checkout. If you update the amount, you must include the tip amount in the AmountDetails object. You must update the payment intent with the final amount and tip before the customer enters payment details in the iframe. You update the payment intent from the server component of your integration (not from the client browser).

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, (1)
    "email": "[e-mail]", (2)
    "amountDetails": { 
        "tip": 100 (3)
    }
} 

• (1):

  The updated payment amount to be charged in minor units represented as a positive integer. In this example, 2000 represents twenty USD and zero cents.

• (2):

  This value only appears if you include a customer's email address when you create or update a payment intent.

• (3):

  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", (1)
    "paymentMethodId": "f718c101-70e4-45fe-8fc1-67ba0a12a8c5",
    "creationDate": "2023-09-29T16:42:36.239579Z",
    "usage": null,
    "customerId": "4b2dfc5a-88a3-11ee-b9d1-0242ac120002", 
    "amountDetails": {
        "tip": 100
    }, 
    "email": "[e-mail]", 
    "paymentMethodConfigurationDetails": { 
        "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08"  
    },
    "latestPayment": null,
    "offSession": false,   
    "standingInstructionType": null, 
    "mandateId": null
}

• (1):

  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.

  For more information, see Payment intent statuses.

Creating a payment method

Note

If you use the payment methods API to create a payment method, you must integrate and support your chosen payment method types, such as Apple Pay and Google Pay. The hosted checkout iframe automatically integrates all Toast platform supported payment method types.

After you have successfully created the payment intent, the next step is to create and attach a payment method to the intent. A payment method is any method that your customer can use to pay for a product or service. You can create a payment method using the createPaymentMethod SDK function or you can choose to create a payment method by sending a POST request to the v1/payment-methods endpoint of the payment methods API. You create a payment method using the payment methods API if you want to take payments using the Toast platform, but do not want to use the iframe to capture customer payment card data.

Important

If you choose to create a payment method using the payment methods API, this puts your integration and the customer’s card data under PCI scope.

Compliance with PCI DSS and all other regulations or laws is solely your responsibility. The information provided is for informational purposes only and should not be relied upon or used as a substitute for consultation with a Qualified Security Assessor or other legal advisor. Please consult a professional advisor for a qualified opinion on the applicability of requirements to your business operations.

Keyed-in and saved card transactions

Note

To create a payment method for a saved card, you must have included the customerId in the request to create a payment intent.

After you have successfully created a payment intent, you create and attach a payment method to the intent. To create a payment method, 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 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", (1)
    "card": { (2)
      "number": "4242424242424242", (3)
      "cvv": "123",
      "expiry": { 
        "month": "12",
        "year": "27"
      }
    },
    "billingDetails": {
       "postalCode": "02118"
    },
    "usage": "ON_SESSION" (4)
}

• (1):

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

• (2):

  The card details used to tokenize the payment card.

• (3):

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

• (4):

  Used to determine if the customer will save the payment method for future use. If the customer wants to save the payment card, set the value to ON_SESSION. 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", (1)
    "type": "CARD",
    "usage": "ON_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]
    }
}

• (1):

  The identifier of the payment method.

Future merchant-initiated transactions

To create a payment method for future merchant-initiated transactions, 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 OFF_SESSION to use for future merchant-initiated 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: A unique and randomized identifier for the 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", (1)
    "card": { (2)
      "number": "4242424242424242", (3)
      "cvv": "123",
      "expiry": { 
        "month": "12",
        "year": "27"
      }
    },
    "billingDetails": {
       "postalCode": "02118"
    },
    "usage": "ON_AND_OFF_SESSION" (4)
}

• (1):

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

• (2):

  The card details used to tokenize the payment card.

• (3):

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

• (4):

  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 included the customerId in the request body to create a payment intent to set the usage to ON_SESSION. The payment card must be saved to a customer record.

    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 payment intent to set the usage to ON_AND_OFF_SESSION.

Example response body

{
    "id": "f718c101-70e4-45fe-8fc1-67ba0a12a8c5", (1)
    "type": "CARD",
    "usage": "ON_AND_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]
    }
}

• (1):

  The identifier of the payment method.

Confirming a payment intent

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 authorizes the payment.

For more information on how to create a payment intent, see Creating a payment intent. For more information on creating a payment method, see Creating a payment method.

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

• 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/payment-intents/{paymentIntentId}/confirm endpoint of the payment intents API after you collected your customer’s payment method details. For example, you can use the integration backend-initiated confirmation 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.

  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 payment intent confirmation

After you pass the sessionSecret into 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. If the action has been successfully completed, the SDK sets the isValid value to true, and your integration invokes the createPaymentMethod function to create a payment method. If the payment method was successfully created, your integration invokes the confirmIntent function to authorize the payment intent using the payment method created.

Integration backend-initiated confirmation for keyed-in and saved cards transactions

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 authorize the payment method. Include the paymentIntentId in the request path. Include the Toast-Restaurant-External-ID as a header parameter. In the request body, include the sessionSecret and paymentMethodId, and the customer's email address if the email was not provided when the payment intent was created or updated.

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", (1)
    "sessionSecret": "PI_86bbcf0c-b483-4bbc-81bf-c2a9cd2baa2c_SECRET_EqYQ5^CgQWc4J?KBwq2jfv&Ov", (2)
    "email": "[e-mail]" (3)
}

• (1):

  The identifier of the payment method. For more information about payment methods, see Creating a payment method or Getting a list of payment methods attached to a customer record.

• (2):

  Used to verify communication in the iframe between your integration and the Toast platform. An active session secret is required to initialize the hosted checkout iframe.

• (3):

  The customer's email address. The customer's email address only needs to be provided once when you create, update, or confirm the payment intent.

Example response body

{
    "id": "86bbcf0c-b483-4bbc-81bf-c2a9cd2baa2c", (1)
    "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", (2)
    "paymentMethodId": "f718c101-70e4-45fe-8fc1-67ba0a12a8c5",
    "creationDate": "2023-09-29T16:42:36.239579Z",
    "usage": "ON_SESSION",
    "customerId": "4b2dfc5a-88a3-11ee-b9d1-0242ac120002", 
    "amountDetails": {
        "tip": 100
    }, 
    "email": "[e-mail]", 
    "paymentMethodConfigurationDetails": { 
        "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08"  
    },
    "latestPayment": { (3)
        "card": {
             "brand": "VISA",
             "lastFour": "1111",
             "expiry": {
                 "month": "12", 
                 "year": "27"
             }  
         } 
    }, 
    "offSession": false,   
    "standingInstructionType": null, 
    "mandateId": null 
}

• (1):

  The unique identifier of the payment intent.

• (2):

  The status of the payment intent. For more information, see Payment intent statuses.

• (3):

  Payment card details associated with the latest payment intent.

Integration backend-initiated confirmation for future merchant-initiated transactions

Similar to keyed-in and saved card transactions, confirm a setup intent for future merchant-initiated transactions, by sending a POST request to the /v1/payment-intents/{paymentIntentId}/confirm endpoint of the payment intents API to authorize the payment method.

Confirming the payment intent securely stores the customer’s payment card as a card-on-file. A card-on-file can be used for merchant-initiated transactions, like deposits on catering orders. To use a card-on-file for a merchant-initiated transaction, the customer must have checked the I authorize this business to charge my card as outlined in the terms checkbox in the iframe during a previous transaction.

If the customer also selects the Remember this card checkbox in the iframe, this stores and saves the payment card to the customer profile. The payment card can be used for both customer and merchant-initiated transactions.

Include the paymentIntentId in the request path. Include the Toast-Restaurant-External-ID as a header parameter. In the request body, include the sessionSecret and paymentMethodId, and the customer's email address if the email was not provided when the payment intent was created or updated.

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.

Note

If the payment method associated with the payment intent is a saved payment card, you must include the customerId in the request to create a payment intent.

Example request body

{
    "paymentMethodId": "f718c101-70e4-45fe-8fc1-67ba0a12a8c5", (1)
    "sessionSecret": "PI_a9c8a2b0-a824-46df-a6dc-4415c556df94_SECRET_JT!M!YA4zL1yxrGHnC6PrYTQX", (2)
    "customerId": "611c1e47-8ba3-457b-8879-196da2c427ff", 
    "email": "[e-mail]" (3)  
}

• (1):

  The identifier of the payment method. For more information about payment methods, see Creating a payment method or Getting a list of payment methods attached to a customer record.

• (2):

  Used to verify communication in the iframe between your integration and the Toast platform. An active session secret is required to initialize the hosted checkout iframe.

• (3):

  The customer's email address. The customer's email address only needs to be provided once when you create, update, or confirm the payment intent.

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

Example response body

{
    "id": "a9c8a2b0-a824-46df-a6dc-4415c556df94", (1)
    "externalReferenceId": "73edc827-0c18-485f-b581-1ef79f93b940",
    "sessionSecret": "PI_a9c8a2b0-a824-46df-a6dc-4415c556df94_SECRET_JT!M!YA4zL1yxrGHnC6PrYTQX",
    "amount": 2000,
    "currency": "USD",
    "captureMethod": "MANUAL",
    "status": "REQUIRES_CAPTURE", (2)
    "paymentMethodId": "f718c101-70e4-45fe-8fc1-67ba0a12a8c5",
    "creationDate": "2023-09-29T16:42:36.239579Z",
    "customerId": "611c1e47-8ba3-457b-8879-196da2c427ff",
    "amountDetails": {
        "tip": 100
    }, 
    "email": "[e-mail]", 
    "paymentMethodConfigurationDetails": { 
        "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08"  
    },
    "latestPayment": { (3)
        "card": {
             "brand": "VISA",
             "lastFour": "1111",
             "expiry": {
                 "month": "12", 
                 "year": "27"
             }  
         } 
    }, 
    "standingInstructionType": "RECURRING" 
    "offSession": false,  
    "mandateId": "d1bc0870-b8e9-44ee-9a49-7d6c416305cc" (4)
}

• (1):

  The unique identifier of the payment intent.

• (2):

  The status of the payment intent. For more information, see Payment intent statuses.

• (3):

  Payment card details associated with the latest payment intent.

• (4):

  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. The status of the mandate. The status can be either ACTIVE or INACTIVE.

    • ACTIVE: The mandate can be used to initiate a payment.

    • INACTIVE: The mandate can no longer be used to initiate a payment.

  • createdAt

  • externalReferenceId

  Important

  Your integration must delete the mandate associated with a payment method if the mandate has a standingInstructionType of UNSCHEDULED. The Toast platform will delete the payment method when there are no mandates associated with the payment method and if the payment method is not a saved card.

Payment intent statuses

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 amount 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 confirmIntent function. The payment intent cannot be modified while in the PROCESSING 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. Modifications to the payment intent in this status return an HTTP 409 conflict response code. 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: The payment intent moves to the SUCCEEDED status if the payment amount was successfully captured.

• REQUIRES_ACTION: This status is reserved for future use.

• FAILED: The payment intent failed to authorize or capture the payment amount.

• CANCELLED: The payment was cancelled before authorization or the payment was voided.