Create a payment intent

Creates a payment intent. If successfully created, it returns a payment intent object that contains information related to the payment intent.

SecurityOAuth2
Request
header Parameters
Toast-Restaurant-External-ID
required
string <string>

The identifier of the restaurant location.

Request Body schema: application/json
amount
required
integer <int32> [ 1 .. 99999999 ]

Amount of the payment to be taken in minor units. A positive integer representing how much to charge in the smallest currency unit (e.g., 100 cents to charge $1.00 or 100 to charge ¥100, a zero-decimal currency). The minimum amount is $0.01 US (e.g., a value of 1) or equivalent in charge currency. The amount value supports up to eight digits (e.g., a value of 99999999 for a USD charge of $999,999.99).

captureMethod
string

Controls when funds will be captured from the customer's account.

Value: "MANUAL"
currency
required
string

Three-letter ISO 4217 currency code, in uppercase. Must be a supported currency.

Value: "USD"
customerId
string <uuid>

The unique identifier of the customer record that identifies the customer in the Toast platform. The identifier is used to retrieve the customer’s payment cards saved to their profile.

email
string

The email address of the customer making the payment. Must consist of the following characters: a-z, A-Z, 0-9, =, ., -, _, +, @, :, &, ^, %, !, $.

externalReferenceId
required
string <uuid>

The unique identifier for the payment intent generated by the restaurant or integration partner. The externalReferenceId can be applied as a payment identifier for a Toast platform check.

paymentMethodConfigurationId
string <uuid>

The identifier of the payment method configuration. If the paymentMethodConfigurationId is not present, the hosted checkout iframe uses the default configuration. The default configuration only enables keyed-in and saved card payment methods.

paymentMethodId
string <uuid>

The identifier of the payment method associated to this payment intent.

Responses
200

Successful operation. Payment intent created.

400

Bad request / Missing required fields.

401

Your client is not authorized to use the API endpoint.

500

Internal server error.

post/v1/payment-intents
Request samples
application/json
{
  • "amount": 1,
  • "currency": "USD",
  • "externalReferenceId": "b31a2b46-53f5-4ad9-a2e3-1dc38ff564d5",
  • "captureMethod": "MANUAL",
  • "customerId": "87d8e330-2878-4742-a86f-dbbb3bf522ac",
  • "email": "string",
  • "paymentMethodConfigurationId": "22fa8381-1845-4222-9264-102b46a89a96",
  • "paymentMethodId": "b6df8625-cd25-4123-b345-638aa7b5d011"
}
Response samples
application/json
{
  • "id": "f8450373-f2a6-4211-8064-55b57f46c57e",
  • "externalReferenceId": "b31a2b46-53f5-4ad9-a2e3-1dc38ff564d5",
  • "sessionSecret": "string",
  • "amount": 1,
  • "currency": "USD",
  • "captureMethod": "MANUAL",
  • "status": "REQUIRES_PAYMENT_METHOD",
  • "paymentMethodId": "null",
  • "creationDate": "2025-02-17T20:33:07.011185Z",
  • "setupFutureUsage": null,
  • "customerId": "87d8e330-2878-4742-a86f-dbbb3bf522ac",
  • "amountDetails": {
    },
  • "email": "string",
  • "paymentMethodConfigurationDetails": {
    },
  • "standingInstructionType": "UNSCHEDULED",
  • "offSession": false,
  • "latestPayment": null
}