Provides information about a tender transaction to a tender provider.

Provides information about a tender transaction processed by the Toast POS system. The transaction information in the message body is intended to allow a tender provider to perform corresponding operations on the tender account, maintained by that provider. The response to this message allows the Toast POS system to update the check, including posting payments and discounts to the check.

You define the endpoint name for this implementation. The Toast POS system makes requests to the REST path that you supply during integration setup.

Each POST request to the endpoint includes a Toast-Transaction-Type header parameter value to indicate the type of tender transaction it represents. The supported transaction types are:

  • Retrieve discounts that are available on a given check.
  • Retrieve payments that are available on a given check.
  • Redeem retrieved payments and/or discounts.
  • Add a tip to a previously confirmed payment.
  • Reverse a previous redemption or gratuity.
  • Request configured search terms for the restaurant.
  • Search for an account.

The TenderTransaction object in the message body includes a set of information that is specific for each transaction type.

The response time for a tender transaction request must be less than 500ms on average. A response time of greater than 5000ms will be considered a timeout.

All tender transactions must be considered idempotent. The implementation must handle multiple requests with the same Toast-Transaction-GUID, Toast-Transaction-Type, and tenderIdentifier.

Request
header Parameters
Authorization
string

A JSON Web Token (JWT) used to authenticate the request. This API key is provided by the tender partner and can be found in the request header. For more information, see [https://doc.toasttab.com/doc/devguide/apiAuthenticatingRequestsFromToastApiClients.html](Authenticating outbound API requests).

Toast-Restaurant-External-ID
string

The unique identifier of the restaurant, defined by the Toast POS system.

Toast-Transaction-GUID
string

A unique identifier of the tender transaction, defined by the Toast POS system. This value is referenced if there is a future reverse transaction call.

Toast-Transaction-Type
string

The type of tender transaction that occurred. Values are:

  • TENDER_RETRIEVE_DISCOUNTS
  • TENDER_RETRIEVE_PAYMENTS
  • TENDER_REDEEM
  • TENDER_GRATUITY
  • TENDER_REVERSE
  • TENDER_SEARCH_CONFIG
  • TENDER_SEARCH
Enum: "TENDER_SEARCH" "TENDER_SEARCH_CONFIG" "TENDER_RETRIEVE_DISCOUNTS" "TENDER_RETRIEVE_PAYMENTS" "TENDER_REDEEM" "TENDER_GRATUITY" "TENDER_REVERSE"
Request Body schema: application/json

A TenderTransaction object containing information about the tender transaction that the Toast POS system is requesting.

object (TransactionInformationDiscounts)

A request for the provider to return a list of discounts (if any) that apply to the given check. The Toast POS system will then send a TENDER_RETRIEVE_PAYMENTS request with the discounts applied to the check.

object (TransactionInformationGratuity)

A request to add an additional gratuity to a existing tender transaction.

object (TransactionInformationPayments)

A request for the provider to return a list of payments that apply to the check. The Toast POS system will then send a TENDER_REDEEM request with the discounts and payments applied to the check.

object (TransactionInformationRedeem)

A request for the provider to mark as consumed the discounts and payments included in this message, that were previously retrieved with TENDER_RETRIEVE_DISCOUNTS and TENDER_RETRIEVE_PAYMENTS calls.

object (TransactionInformationReverse)

A request to reverse discounts and/or payments made as part of a previous transaction.

object (TransactionInformationSearch)

A request to search for all tender accounts that match the given search terms.

Responses
200

OK. The transactionStatus value of the TenderTransactionResponse object is ACCEPT.

400

Bad request. The transactionStatus value of the TenderTransactionResponse object is one of:

  • ERROR_INVALID_TOAST_TRANSACTION_TYPE
  • ERROR_INVALID_INPUT_PROPERTIES
  • ERROR_INVALID_TOKEN
  • ERROR_INVALID_RESTAURANT
  • ERROR_TRANSACTION_DOES_NOT_EXIST
  • ERROR_TRANSACTION_CANNOT_BE_REVERSED
  • ERROR_ACCOUNT_INVALID
  • ERROR_ACCOUNT_NO_POST
  • ERROR_INSUFFICIENT_FUNDS
  • ERROR_UNABLE_TO_PROCESS
  • FOLIO_IN_USE
500

Internal server error.

post/yourendpointname
Request samples
application/json
{
  • "searchTransactionInformation": {
    },
  • "discountsTransactionInformation": {
    },
  • "paymentsTransactionInformation": {
    },
  • "redeemTransactionInformation": {
    },
  • "gratuityTransactionInformation": {
    },
  • "reverseTransactionInformation": {
    }
}
Response samples
application/json
{
  • "transactionStatus": "ACCEPT",
  • "searchConfigResponse": {
    },
  • "searchResponse": {
    },
  • "discountsResponse": {
    },
  • "paymentsResponse": {
    },
  • "gratuityResponse": {
    }
}