Completing a merchant-initiated transaction

Creating a payment intent

To complete a merchant-initiated transaction, send a POST request to the /v1/payment-intents endpoint of the payment intents API to create a payment intent. Include the Toast-Restaurant-External-ID as a header parameter in the request to specify the GUID of the Toast location that you are creating a payment intent for. In the request body, include the mandateId and set the offSession value to true to indicate the transaction is merchant-initiated.

Example request body

{
    "amount": 1000,
    "currency": "USD",
    "externalReferenceId": "acd578a5-bb6d-4c3e-b6c7-c3a0d53f2a71",
    "captureMethod":"MANUAL",
    "email": "john.smith@email.com", 
    "customerId": "cd5fe473-7255-417a-be39-41261906c02d",
    "offSession": true, 1
    "mandateId": "d1bc0870-b8e9-44ee-9a49-7d6c416305cc" 2
}

1

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

  • Set the offSession value to true to indicate that the transaction is merchant-initiated.

  • Set the offSession value to false to indicate that the transaction is customer-initiated. If no value is provided, the value defaults to false. For more information, see Creating a payment intent for a customer-initiated transaction.

2

The identifier of the mandate.

Example response body

{
    "id": "47d9c5e4-09aa-4242-a03d-a892eb7fb924",
    "externalReferenceId": "acd578a5-bb6d-4c3e-b6c7-c3a0d53f2a71",
    "sessionSecret": "PI_47d9c5e4-09aa-4242-a03d-a892eb7fb924_SECRET_8dfBkcR-K1gdFwP*9VecvLWNT",
    "amount": 100,
    "currency": "USD",
    "captureMethod": "MANUAL",
    "status": "REQUIRES_PAYMENT_METHOD",
    "paymentMethodId": null,
    "creationDate": "2025-11-20T22:06:15.165038025Z",
    "usage": null,
    "customerId": "cd5fe473-7255-417a-be39-41261906c02d",
    "amountDetails": {
       "tip": 0,
        "surcharge": null,
        "lineItemModifiers": null,
        "tax": null
    },
    "email": "john.smith@email.com",
    "paymentMethodConfigurationDetails": {
        "id": "5855c2ae-e3aa-45d9-b78d-88fafacf0ec2"
    },
    "standingInstructionType": "RECURRING",
    "offSession": true,
    "mandateId": "d1bc0870-b8e9-44ee-9a49-7d6c416305cc"
}

Confirming a payment intent

Confirm the merchant-initiated transaction by sending a POST request to the /v1/payment-intents/{paymentIntentId}/confirm endpoint of the payment intents API. 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 the customer's email address if the email was not provided when the payment intent was created or updated.

Example request body

{
    "sessionSecret": "PI_47d9c5e4-09aa-4242-a03d-a892eb7fb924_SECRET_8dfBkcR-K1gdFwP*9VecvLWNT",
    "email": "john@smith@email.com"  
}

Example response body

{
   "id": "47d9c5e4-09aa-4242-a03d-a892eb7fb924",
   "externalReferenceId": "acd578a5-bb6d-4c3e-b6c7-c3a0d53f2a71",
   "sessionSecret": "PI_47d9c5e4-09aa-4242-a03d-a892eb7fb924_SECRET_8dfBkcR-K1gdFwP*9VecvLWNT",
   "amount": 1000,
   "currency": "USD",
   "captureMethod": "MANUAL",
   "status": "SUCCEEDED",
   "paymentMethodId": "c92244df-46fe-4fc2-b0dc-ffce1f63fa52",
   "paymentMethodData": null,
   "creationDate": "2026-01-07T16:42:51.920913144Z",
   "usage": "OFF_SESSION",
   "customerId": "cd5fe473-7255-417a-be39-41261906c02d",
   "amountDetails": {
       "tip": 0,
       "surcharge": null,
       "lineItemModifiers": null,
       "tax": null
   },
   "email": "john.smith@email.com",
   "paymentMethodConfigurationDetails": {
       "id": "5855c2ae-e3aa-45d9-b78d-88fafacf0ec2"
   },
   "standingInstructionType": "RECURRING",
   "offSession": true,
   "latestPayment": {
       "card": {
           "lastFour": "1111",
           "expiry": {
               "month": "12",
               "year": "27"
           },
           "brand": "VISA"
       }
   },
   "mandateId": "d1bc0870-b8e9-44ee-9a49-7d6c416305cc"
}