Using payment methods

The hosted checkout integration APIs support the following payment methods:

  • Keyed-in cards

  • Saved cards

  • Apple Pay®

  • Google Pay®

Some payment methods require additional setup before they can be used with the hosted checkout integration APIs. For example, to allow customers to use a saved card, you must create a payment intent with the customerId. You get the customerId when you send a POST request to the /v1/customers endpoint of the customers API. To use Apple Pay, you must register and validate your domains prior to completing your integration and using the hosted checkout integration APIs. For more information, see Registering and verifying a payment method domain.

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", 1
    "description": "John Smith" 2
}

1

Represents the restaurant 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.

2

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


Example response body

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

1

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 restaurant 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.

2

Represents the customer's identity in your integration.


Deleting a payment method

Note

The server component of your integration makes the API request to delete a saved payment method.

If you allow customers to store payment cards, you can also allow them to remove payment cards by deleting the payment method from their customer record. Deleting a payment method from a customer record is permanent and the payment method cannot be reattached to their record. For more information on payment methods, see Creating a payment method.

There are two API requests associated with deleting a saved payment method from a customer record.

  • Getting a list of payment methods attached to the customer record.

  • Delete the payment method from the customer record using the customerId and paymentMethodId. The paymentMethodId is the unique identifier of the payment method.

Getting a list of payment methods attached to a customer record

To get a list of payment methods saved to a customer record, send a GET request to the v1/customers/{customerId}/payment-methods endpoint of the customers API using your Toast API authentication credentials for the server component of your integration. You cannot use the API credentials for your hosted checkout client component. Requests made to this endpoint using the token for your hosted checkout client return an error. Include the Toast-Restaurant-External-ID as a header parameter in the request and the customerId in the request path.

Note

Customers cannot save digital wallets such as Apple Pay and Google Pay as payment methods.

Example response body

{
    "results": 1,  1
    "paymentMethods": [  2
        {
            "id": "f718c101-70e4-45fe-8fc1-67ba0a12a8c5", 3
            "type": "CARD",
            "cardType": "VISA",
            "lastFour": "1111",
            "month": "12",
            "year": "27"
        }
    ]
}

1

The number of payment methods attached to the customer record.

2

The paymentMethods value that holds an array of paymentMethods objects. The paymentMethod object contains information about the payment card, the unique identifier for the payment card, card type, last four digits of the payment card, and the expiration month and year.

3

The unique identifier for the payment card. Use this id to delete a saved payment card from the customer record.


Deleting a payment method from a customer record

Note

You must use the Toast API authentication credentials for the server component of your integration.

To delete a payment method from a customer record, send a POST request to v1/payment-methods/{paymentMethodId}/detach endpoint of the payment methods API. Include Toast-Restaurant-External-ID as a header parameter in the request and the paymentMethodId in the request path. The paymentMethodId is the identifier for the payment card. Include the customerId in the request body.

Note

You cannot update the expiration date on a saved payment card. Your customer will need to add the payment card with the new expiration date and then delete the expired card.

Example request body

{
    "customerId": "4b2dfc5a-88a3-11ee-b9d1-0242ac120002" 1
}

1

The identifier for the customer record that identifies the customer in the Toast platform. You use the customerId to display the payment cards saved to the customer profile in your integration.


Example response body

{
    "id": "f718c101-70e4-45fe-8fc1-67ba0a12a8c5", 1
    "type": "CARD",
    "card": {
        "lastFour": "1111",
        "type": "VISA",
        "expiry": {
            "month": "12",
            "year": "27"
        }
    }
}

1

The identifier for the deleted payment card.

Apple Pay transactions

Important

Apple Pay® is currently only available for Toast platform integrations on Apple’s Safari web browser.

You can use the hosted checkout integration to accept Apple Pay payments for orders placed on your registered domains and subdomains. To make Apple Pay available as a payment method, you need to host the static domain verification file, and then register and validate your domains to complete your Apple Pay integration. The iframe, static domain verification file, and Apple Pay registration must all be on the same domain for Apple Pay to be available for use in the iframe.

You can register and validate your domains on the Toast developer portal. The Payment method domains section on the Payment methods page in the Toast developer portal lists all your domains and subdomains and their verification statuses (if applicable). From the Payment method domains section, you can also choose to delete a domain or subdomain.

Registering and verifying a payment method domain

To accept Apple Pay payments, you must host a static domain verification file at a publicly accessible location on your domain. The static domain verification file needs to be available on each domain and subdomain used for Apple Pay transactions. You can download the static domain verification file for your sandbox or production environment below.

  • Sandbox: https://sandbox.eng.toasttab.com/.well-known/ME_sandbox_toast

    For information about how to test Apple Pay in a sandbox environment, see Sandbox Testing.

  • Production: https://www.toasttab.com/.well-known/ME_prod_toast

The file is titled apple-developer-merchantid-domain-association. You can rename the file before you upload it to your domain.

Host the static domain verification file at the following path on your domain: https://[DOMAIN_NAME]/.well-known/apple-developer-merchantid-domain-association.

To register and verify a domain on the Toast developer portal

  1. On the Payment methods page of the Toast developer portal, navigate to the Payment method domains section.

  2. Select the + Add a new domain button to open the Register domain for Apple Pay dialog box.

  3. Enter the domain name in the text field.

    Note

    You can create an unlimited number of payment method domains.

    Add payment method domain dialog on the developer portal.

  4. Select the Register button. After you register your domain, this creates a payment method domain record. A payment method domain record is the record of your registered domains in the Toast platform. The domain record lists all digital wallets available for use.

  5. Navigate back to the Payment method domains section on the Payment methods page. Your newly registered domain is listed under the Domain heading.

  6. Select the Verify now link next to the domain name to open the Verify domain for Apple Pay dialog box.

  7. In the Verify domain for Apple Pay dialog, complete the following actions:

    • Open and save the static verification file at a publicly accessible location on your domain.

    • Host the static verification file at the specified path on your domain. For more information, see Preparing Merchant Domains for Verification.

    Verify domain for Apple Pay dialog on the developer portal.

  8. Select the Verify button to verify your domain or the Cancel button to close out of the dialog box.

    If the verification was successful, the domain displays Apple Pay as an enabled payment method under the Enabled payment methods heading in the Payment method domains section. If the verification was unsuccessful, an error message appears on the Verify domain for Apple Pay dialog. You will be unable to process Apple Pay transactions until Apple successfully validates the file. Make sure that the static verification file was hosted correctly on your domain.

Deleting a payment method domain

In the Payment method domains section on the Payment methods page of the Toast developer portal, you can delete a domain by selecting the trash icon next to the domain name. This opens the Delete domain dialog box. In the Delete domain dialog box, select the Delete button to delete the domain.

If you choose to delete a payment method domain, the deletion is permanent and the domain cannot be recovered. To enable Apple Pay for the domain, you will need to re-register and verify the domain again.

Google Pay transactions

You can allow customers to use Google Pay® as a payment method using the hosted checkout integration APIs. Unlike Apple Pay, Google Pay does not require individual domain registration and is automatically enabled for you if choose to use the hosted checkout integration APIs to initialize and display the iframe on your checkout page.

You can turn Google Pay on or off in the Toast developer portal. For more information, see Managing payment method configurations.

Google Pay displayed in an iframe.