Merchant-initiated transactions

Note

A saved card must have a mandate attached to be used for merchant-initiated transactions. A mandate is returned if the payment or setup intent was successfully confirmed. For more information, see Mandates.

A merchant-initiated transaction is a transaction initiated by the integration (merchant) and not the customer. Some examples of merchant-initiated transactions include charging for a monthly wine club subscription, charging fixed payments for large catering orders, or charging a one-time fee (unscheduled) payment such as a restaurant reservation fee.

After you have completed a customer-initiated transaction and created a card-on-file, you use the mandateId from the PaymentIntentResponse, SetupIntent response, or the ConfirmIntentResultEvent to create and confirm a payment intent.

For merchant-initiated transactions, you can use either a card-on-file or a saved card.

• Card-on-file: The payment card is created during the customer-initiated payment or setup intent transaction and can be used for future transactions. The payment card is not associated with a customer record and cannot be selected in the hosted checkout iframe. The card-on-file is deleted after the transaction is completed.

  Note

  After the transaction is complete, your integration must revoke (delete) the mandate associated with the transaction. For more information, see Revoking a mandate. After the mandate is revoked, then the payment method can be deleted. For more information, see Deleting a payment method.

  To authorize a payment card for merchant-initiated transactions, the customer must select the I authorize this business to charge my card as outlined in the terms checkbox in the hosted checkout integration iframe.

• Saved card: The payment card is created during the customer-initiated payment or setup intent workflow and can be used for future transactions. The payment card is associated with a customer record. To use a saved card for merchant-initiated transactions, the customer must have selected the Remember this card checkbox in the hosted checkout iframe to save the card during a previous customer-initiated transaction. Saved cards are displayed in the hosted checkout iframe for the customer to use once they log into their customer profile.

  To authorize a payment card to be used for merchant-initiated transactions, the customer must select the I authorize this business to charge my card as outlined in the terms checkbox in the hosted checkout integration iframe.

Merchant-initiated transactions workflow

The workflow for completing a merchant-initiated transaction is:

1. Complete a customer-initiated transaction. For more information, see Customer-initiated payment intent transactions or Customer-initiated setup intent transactions.

   The response returns a mandateId that you need to store in your integration. The mandateId authorizes your integration to charge a customer’s payment card for future merchant-initiated transactions.

2. Complete a merchant-initiated transaction by creating a payment intent and include the mandateId from the confirm response. Set the offSession value to true to indicate that the transaction is merchant-initiated.

3. Confirm the payment intent.

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": "[e-mail]", 
    "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": "[e-mail]",
    "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@[e-mail]"  
}

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": "[e-mail]",
   "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"
}