Create a payment intent

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

SecurityOAuth2 or OAuth2
Request
header Parameters
Toast-Idempotency-Key
string [ 1 .. 255 ] characters

A unique key for the request. A retry with the same key and request returns the original response instead of repeating the operation. Reusing a key with a different request, or while the original request is still in progress, returns a 409. Keys expire after 24 hours. A blank key returns a 400.

Toast-Restaurant-External-ID
required
string <string>

The identifier of the 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).

object (AmountDetails)

Details about a tip amount.

captureMethod
string

Controls when funds are captured from the customer's account.

  • MANUAL - This places a hold on your customer's funds when the payment is authorized.
  • AUTOMATIC - Funds are captured automatically at authorization. Gift card payments must use AUTOMATIC; MANUAL is rejected for gift cards.
Enum: "MANUAL" "AUTOMATIC"
currency
required
string

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

Enum: "USD" "CAD" "EUR" "AUD" "GBP"
customerId
string <uuid>

The unique identifier of the customer record that identifies the customer in the Toast platform. You can optionally include the customerId to retrieve the customer's payment methods 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, =, ., -, _, +, @, :, &, ^, %, !, $. An email address is required for digital or online transactions and must be provided at least once during the payment intent workflow by including it in the request body of the create payment intent, update payment intent, or confirm payment intent request.

externalReferenceId
required
string <uuid>

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

mandateId
string or null <uuid>

The unique identifier of the mandate. The mandateId is required to create a merchant-initiated transaction. The mandateId retrieves the standingInstructionType for the customer's payment card.

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.

object

Configurable options for each payment method type.

standingInstructionType
string

The instruction type used by the merchant and sent to the payment processor.

  • INSTALLMENT - The total purchase amount charged on a repeating basis.

  • RECURRING - A series of set payments charged at regular intervals.

  • UNSCHEDULED - A single merchant-initiated payment.

Responses
200

Successful operation. Payment intent created.

400

Bad request / Missing required fields.

401

Your client is not authorized to use the API endpoint.

409

The Toast-Idempotency-Key conflicts with a previous request.

500

Internal server error.

post/v1/payment-intents
Request samples
application/json
{
  • "amount": 1,
  • "amountDetails": {
    },
  • "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",
  • "paymentMethodOptions": {
    },
  • "mandateId": "d4dbf0da-b5aa-43ae-b9db-c2aff331d3ad",
  • "standingInstructionType": "string"
}
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",
  • "creationDate": "2025-02-17T20:33:07.011185Z",
  • "customerId": "87d8e330-2878-4742-a86f-dbbb3bf522ac",
  • "amountDetails": {
    },
  • "email": "string",
  • "paymentMethodConfigurationDetails": {
    },
  • "standingInstructionType": "UNSCHEDULED",
  • "offSession": false,
  • "latestPayment": null,
  • "mandateId": null
}