This guide will be removed on April 29, 2022. Please use our new, easier-to-use Toast technical documentation site. All updated content is on the new site.

Overview of the credit card authorization and application process

The following procedure provides an overview of the process to authorize and apply a credit card payment.

To authorize and apply a credit card payment for an orders API order

  1. Submit a POST request to the /prices endpoint of the orders API to get the total price of each check in an order. For more information, see Getting check prices before you submit an order.

  2. Generate a UUID unique identifier for the credit card payment.

    The payment UUID is a path parameter for a PUT request to the /merchants/{merchantUuid}/payments/{paymentUuid} resource.

    You use the payment UUID to apply the authorized credit card payment to an order.

    To generate the payment UUID, you must use the algorithm described in version four of the UUID standard.

  3. Submit a PUT request to the /merchants/{merchantUuid}/payments/{paymentUuid} resource of the credit cards API.

    In the message body of the request, include the total price for all checks and encrypted credit card information. For more information, see Authorizing a credit card payment.

  4. Within five minutes, submit a POST request to the /orders endpoint of the orders API to add the order.

    In the JSON message body data for a check, set the guid value of the payment object to the payment UUID of the credit card payment. For more information, see Applying an authorized credit card payment to an orders API check.

If a credit card payment cannot be authorized, the ErrorMessage object typically includes a generic, non-null, error message such as Invalid card data.

Error messages in the credit cards API are intentionally not specific or detailed, to minimize the error information that reaches attackers that are attempting to make fraudulent payments.

For a list of common reasons for card denial, see Card declined message reference.