Creating a setup intent

Note

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

To create a setup intent, send a POST request to the v1/setup-intents endpoint of the setup intents API. In the request body, include the customerId and set the usage value to ON_SESSION to save the payment card for future customer-initiated transactions.

Example request body

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

1

The unique identifier of the customer record. For more information about customer records, see Creating a customer record.

2

Used to determine if the customer will save the payment method for future use. Set the value to ON_SESSION to set up and save the payment method to the customer's profile for future customer-initiated transactions. The customer has selected the Remember this card checkbox in the hosted checkout iframe. The payment card cannot be used for merchant-initiated transactions.

Note

You must include the customerId to set the usage value to ON_SESSION. The payment card must be saved to a customer record.


Example response body

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

1

The unique identifier for the setup intent.

2

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.


Future merchant-initiated transactions

To create a setup intent for future merchant-initiated transactions, send a POST request to the v1/setup-intents endpoint of the setup intents API. In the request body, set the usage value to OFF_SESSION to save the payment card for future merchant-initiated transactions. In the request body, include a standingInstructionType value.

Optionally, you can choose to include the customerId in the request body. The customerId represents the customer’s identity in your integration and is associated with a customer record. If you do not include the customerId, this allows the customer to create a card to be the card-on-file without having to create a customer profile. For example, you might have a customer who likes to make reservations at your restaurant, but does not want to create a customer profile. They could have a card-on-file at your restaurant to pay for reservation fees.

Example request body

{
  "usage": "OFF_SESSION", 1
  "standingInstructionType": "UNSCHEDULED" 2
}

1

Used to determine if the customer will save the payment method for future use. Set the value to OFF_SESSION to set up and store the payment method as a card-on-file for future 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.

2

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 merchant-initiated single payment that is not part of a subscription.


Example response body

{
    "id": "77c41db8-e734-46f0-8df4-16c053cfd6c5", 1
    "sessionSecret": "SI_77c41db8-e734-46f0-8df4-16c053cfd6c5_SECRET_8zik1gYp*7objjB.ToCES-qkJ",
    "paymentMethodId": null,
    "status": "REQUIRES_PAYMENT_METHOD",
    "usage": "OFF_SESSION",
    "creationDate": "2024-03-26T16:17:27Z"
    "standingInstructionType": "UNSCHEDULED",
    "mandateId": null 
}

1

The unique identifier for the setup intent.