TenderTransactionResponse

Information about a tender transaction from the tender provider. The Toast POS system uses this information to complete guests' tender transactions.

The set of information in this object depends on the tender transaction type. The transaction type is specified in the Toast-Transaction-Type header parameter for the request.

All TenderTransactionResponse objects must include a transactionStatus value.

The TenderTransactionResponse object includes the following values for specific transaction types:

  • TENDER_RETRIEVE_DISCOUNTS - includes a discountsResponse value.
  • TENDER_RETRIEVE_PAYMENTS - includes a paymentsResponse value.
  • TENDER_REDEEM - optionally includes a redeemResponse value.
  • TENDER_GRATUITY - includes a gratuityResponse value.
  • TENDER_REVERSE - no additional fields.
  • TENDER_SEARCH_CONFIG - includes a searchConfigResponse value.
  • TENDER_SEARCH - includes an searchResponse value.
object (TransactionResponseDiscounts)

A list of discounts that apply to the given check with the given account identifier.

object

Additional details about an error displayed to the POS operator, supplied by the provider along with specific error statuses.

object (TransactionResponseGratuity)

Response to a request to update the gratuity amount on an already tendered payment.

object (TransactionResponsePayments)

A list of discounts that apply to the given check with the given account identifier.

object (TransactionResponseRedeem)

Response to a request to redeem previously retrieved discounts and payments. This value is optional. Include it to report the account that the discounts and payments were redeemed against, for example when the tender provider resolved the request to a different account than the one in the request.

object (TransactionResponseSearchConfig)

A list of search terms supported by the tender provider. This will populate the list of search terms displayed by the Toast POS system when a search is requested.

object (TransactionResponseSearch)

A list of accounts matching the search terms submitted as part of a search request.

transactionStatus
string (TenderTransactionStatus)

Indicates the result of a tender transaction, reported by the tender service provider. This property must be present on all responses. Possible values are:

  • `ACCEPT` - The tender service provider processed the transaction successfully.
  • `ERROR_INVALID_TOAST_TRANSACTION_TYPE` - The requested Toast-Transaction-Type is not valid.
  • `ERROR_INVALID_INPUT_PROPERTIES` - The specified JSON properties in the request body are not valid.
  • `ERROR_INVALID_TOKEN` - The token supplied in the `Authorization` header field is invalid.
  • `ERROR_INVALID_RESTAURANT` - The restaurant specified by the `Toast-Restaurant-External-ID` is invalid.
  • `ERROR_ACCOUNT_INVALID` - The tender identifier provided did not correspond to an account, or the account is not valid at the current restaurant.
  • `ERROR_ACCOUNT_NO_POST` - The tender identifier provided corresponded to an account which has no card on file or has been marked as "no post".
  • `ERROR_FOLIO_IN_USE` - Some property management systems limit guest folio access to one source at a time. If the front desk agent is using the property management system to access a guest folio, it may be locked and therefore unavailable for room charge posting during that time.
  • `ERROR_INSUFFICIENT_FUNDS` - The payment or tip, specified in TENDER_RETRIEVE_PAYMENTS or TENDER_RETRIEVE_GRATUITY, cannot be retrieved because the tender account does not have sufficient balance.
  • `ERROR_UNABLE_TO_PROCESS` - The transaction cannot be processed by the integration.
  • `ERROR_TRANSACTION_DOES_NOT_EXIST` - The transaction that is being requested to be reversed or updated does not exist. Only occurs on a `TENDER_REVERSE` or `TENDER_GRATUITY` response.
  • `ERROR_TRANSACTION_CANNOT_BE_REVERSED` - The specified transaction cannot be reversed. Only `TENDER_REDEEM` and `TENDER_GRATUITY` transactions can be reversed.
  • `ERROR_UNABLE_TO_PROCESS_REASON` - The transaction cannot be processed by the integration, and the integration is supplying the reason. Include the reason text in the `errorMessage` key of the `errorDetails` value so that the Toast POS system can display it to the restaurant employee.
  • `ERROR_CHECKED_OUT` - The account is no longer available for posting because the guest has checked out.
  • `ERROR_UNMAPPED_SPECIFIC_ITEMIZER` - The check contains a menu item that is not fully configured for the integration. Include the name of the data extension type in the `dataExtensionType` key of the `errorDetails` value.
  • `ERROR_NETWORK` - Reserved for the Toast POS system. The Toast POS system reports this status when it cannot reach the tender provider. Tender providers should not return this value.
  • `ERROR` - Reserved for the Toast POS system. The Toast POS system reports this status for an unknown error, including a response body that does not conform to this specification. Tender providers should not return this value.
Enum: "ACCEPT" "ERROR" "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_CHECKED_OUT" "ERROR_FOLIO_IN_USE" "ERROR_INSUFFICIENT_FUNDS" "ERROR_NETWORK" "ERROR_UNABLE_TO_PROCESS" "ERROR_UNABLE_TO_PROCESS_REASON" "ERROR_UNMAPPED_SPECIFIC_ITEMIZER"
{
  • "transactionStatus": "ACCEPT",
  • "searchConfigResponse": {
    },
  • "searchResponse": {
    },
  • "discountsResponse": {
    },
  • "paymentsResponse": {
    },
  • "gratuityResponse": {
    },
  • "redeemResponse": {
    },
  • "errorDetails": {
    }
}