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:

Example request body

{
    "paymentMethodId": "f718c101-70e4-45fe-8fc1-67ba0a12a8c5", 1
    "sessionSecret": "PI_86bbcf0c-b483-4bbc-81bf-c2a9cd2baa2c_SECRET_EqYQ5^CgQWc4J?KBwq2jfv&Ov", 2
    "email": "john.smith@email.com" 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": "john.smith@email.com", 
    "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.

This image shows Remember this card and I authorize this business to charge my card as outlined in the terms checkboxes in the iframe.

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:

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": "john.smith@email.com" 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": "john.smith@email.com", 
    "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.