Payment card transactions

The hosted checkout integration APIs can be used to complete keyed-in or saved card transactions. The hosted checkout integration iframe allows customers to key in payment card details or to pay using one of their saved cards. To create a payment intent to use for saved card transactions, you must create a customer record. A customer record contains information about a person or organization making Toast payments and allows them to choose from their saved payment cards.

Creating a customer record

To save and display a customer's saved cards, you must first create a customer record. To create a customer record, send a POST request to the /v1/customers endpoint of the customers API to create a CustomerResponse. The CustomerResponse contains the customer description, externalReferenceId, and id. The id is the unique identifier of the customerId, which identifies the customer in the Toast platform and can be used to create or update a payment intent. To display a customer's saved cards in the iframe, include the customerId in the request to create a payment intent.

Note

When a customer record is created, this does not create a customer profile in the Toast platform. The customer record is used to match the customer to their saved cards.

Example request body

{
    "externalReferenceId": "john.smith@email.com", 
    "description": "John Smith" 
}

Represents the customer's identity in your integration. This can be the primary key for your customer, an unique UUID, an email address, or any other value to help correlate the generated customerId that the customers API provides.

Note

The POST request to create a customer record is idempotent, which means you cannot create multiple customer records using the same externalReferenceId. If you try to create a duplicate record, the customers API returns the existing customerId that was created when the customer record was initially created.

A brief description of the customer, such as an email address, name, or phone number.

Example response body

{
    "id": "4b2dfc5a-88a3-11ee-b9d1-0242ac120002", 
    "externalReferenceId": "john.smith@email.com", 
    "description": "John Smith" 
}

The unique identifier for the customer record that identifies the customer in the Toast platform and allows them to choose from the payment cards saved to their profile. Your integration should store the id for use when the customer signs into their customer profile. The customerId is not specific to a Toast location.

Note

Toast support recommends that you send the POST request to /v1/customers endpoint at the same time your customer creates their profile in your integration. This ensures that when the customer is ready to check out, they can save a new card to their profile.

Represents the customer's identity in your integration.