Property management systems (PMS) are used by hotels and motels to coordinate systems used for servicing guests, charges, and further accounting. You can use the tender API to implement an integration between a PMS and the Toast platform. The tender integration allows an employee at a hotel or restaurant to look up a guest's account and post charges to their hotel folio.
The tender API supports the following transaction types for the PMS integration workflow:
-
TENDER_SEARCH_CONFIG: Request configured search terms for the restaurant. Search terms can be First Name, Last Name, Room Number, Email, or Company. -
TENDER_SEARCH: Search for an account. -
TENDER_RETRIEVE_DISCOUNTS: Retrieve applicable discounts for a check. -
TENDER_RETRIEVE_PAYMENTS: Retrieve payment for a check. -
TENDER_REDEEM: Confirm payment and discounts applied to a check. -
TENDER_GRATUITY: Add a tip to a previously confirmed payment. -
TENDER_REVERSE: Reverse a previous discount redemption or gratuity.
Configuring the search is the first transaction that occurs when an employee initiates the workflow to charge a check to a guest's account.
Configure search workflow
-
A guest wants to charge a check to a hotel room.
-
An employee selects Pay ($) to tender the check and selects hotel room charge as the payment method on the Toast POS device.
-
The Toast platform sends a
TENDER_SEARCH_CONFIGrequest to the hotel PMS provider to get the search terms used by the provider to look up guest information. -
The PMS provider sends a response in a
searchConfigResponseobject. Each key-value pair in this object defines an input field (key) with its type (value). Optional attributes for maximum length (maxLength) and tender property type (tenderProperType) for the key-value pair may be included.The
valuemust be one of the following:Value
Description
NUMBERA numeric value such as room number, or reservation number.
TEXTAn alphanumeric value such as a guest's name or their company's name.
EMAILThe guest's email address.
PHONE_NUMBERA numeric-only value for the guest's phone number.
The first four search terms are displayed on the guest lookup screen on the Toast POS device. The
valuealso determines the type of virtual keyboard that is displayed for the search term. For example,TEXTdoes not allow a number pad to be used.
The following example shows the search terms configured as room number, name, reservation number and phone number.
Configure search request
The TENDER_SEARCH_CONFIG transaction is a
POST request to your tender API endpoint
https://api.
with the following header parameters:
{your endpoint}
-
Toast-Transaction-Type -
Toast-Restaurant-External-ID -
Toast-Transaction-GUID -
Authorization
This request has no message body.
Successful configure search response
The following is an example of a successful configure search response.
{
searchConfigResponse: {
searchTermNames: [
{ key: 'Room Number', value: 'NUMBER', 'tenderPropertyType': 'ROOM_ID' }, 
{ key: 'Name', value: 'TEXT' },
{ key: 'Reservation Number', value: 'NUMBER' },
{ key: 'Company Name', value: 'TEXT' }
]
},
transactionStatus: 'ACCEPT'
}|
The |
After the search configuration request, the Toast POS device displays the guest search criteria. An employee can search for a guest on the Toast POS device using a guest's information, such as name, room number, or reservation number.
Guest search workflow
-
An employee enters the guest's identifying information in the input fields on the Toast POS device and searches for the guest.
-
The Toast POS device sends a
TENDER_SEARCHrequest to the PMS provider. The request is aTenderTransactionobject that contains asearchTransactionInformationobject which contains asearchTermsobject. ThissearchTermsobject contains the search criteria, in the form of a key-value pair:-
The
keycorresponds to the input field where the restaurant employee enters the guest's identifying information. -
The
valuecorresponds to the string that the employee types on the Toast POS device. Thevaluecan be partial. For example, only first or last name, or partial name.
-
-
The PMS provider returns the results of the search request in a
searchResponseobject that contains asearchResultsproperty. ThesearchResultsproperty contains an array ofAccountInfoobjects. Each entry in the array corresponds to a guest and includes:-
An identifier for the guest (
tenderIdentifier). EachtenderIdentifiershould be unique for each guest returned in theTENDER_SEARCH response.Important
tenderIdentifieris generated by the integration partner and should never be generated using a guest's sensitive information, such as credit card details. -
The search results returned as key-value pairs with the guest information such as name and room number.
Guest search results are displayed on the Toast POS device.
-
The following example shows a search for a guest whose name
contains john. The PMS provider responds with three
results for john adams, tommy john, and
jimmy john and their information.
Search request message body
{
discountsTransactionInformation: null,
paymentsTransactionInformation: null,
redeemTransactionInformation: null,
gratuityTransactionInformation: null,
reverseTransactionInformation: null,
searchTransactionInformation: {
swipeData: null,
scanData: null,
searchTerms: [
{ key: 'Room Number', value: '' },
{ key: 'Name', value: 'john' },
{ key: 'Reservation Number', value: '' },
{ key: 'Company Name', value: '' }
]
}
}Successful search response
{
searchResponse: {
searchResults: [
{
tenderIdentifier: '2',
properties: [
{ key: 'Room Number', value: '406', 'tenderPropertyType': 'ROOM_ID' },
{ key: 'Name', value: 'john adams' },
{ key: 'Reservation Number', value: '7492936' },
{ key: 'Company Name', value: 'Information Dynamix, Inc.' },
{ key: 'Guest Status', value: 'Active' },
{ key: 'Charge Limit', value: '$120.00' }
],
additionalProperties: [ { key: 'storedValue', value: 60 } ]
},
{
tenderIdentifier: '4',
properties: [
{ key: 'Room Number', value: '1234', 'tenderPropertyType': 'ROOM_ID' },
{ key: 'Name', value: 'tommy john' },
{ key: 'Reservation Number', value: '12531953' },
{ key: 'Company Name', value: 'Toast, Inc.' },
{ key: 'Guest Status', value: 'Active' },
{ key: 'Charge Limit', value: '$200.00' }
],
additionalProperties: [ { key: 'storedValue', value: 400000 } ]
},
{
tenderIdentifier: '5',
properties: [
{ key: 'Room Number', value: '555', 'tenderPropertyType': 'ROOM_ID' },
{ key: 'Name', value: 'jimmy john' },
{ key: 'Reservation Number', value: undefined },
{ key: 'Company Name', value: 'Jackie's Jackhammers' },
{ key: 'Guest Status', value: undefined },
{ key: 'Charge Limit', value: '$2450.00' }
],
additionalProperties: [ { key: 'storedValue', value: 980.73 } ]
}
]
},
transactionStatus: 'ACCEPT'
}
After an employee selects a guest from the search results on the Toast POS device, the Toast platform retrieves discounts from the PMS provider.
Retrieve discounts workflow
-
The Toast platform sends a
TENDER_RETRIEVE_DISCOUNTSrequest to the PMS provider. The request includes aTenderTransactionobject that holds the guest identifier (tenderIdentifier) and check (Check) in adiscountsTransactionInformationobject. -
Your PMS integration determines the discounts to be applied to the check and responds to the Toast platform with a
discountsResponsevalue in theTenderTransactionResponseobject. Discount information is contained in this object. Note that the number of discounts can be zero. -
The Toast platform applies the discounts and adds or updates the
appliedDiscountsvalue of theCheckobject.Note
As a provider, you might not support discounts for your restaurant. In this case, you can return an empty array in your response to the
TENDER_RETRIEVE_DISCOUNTSrequest.
Retrieve discounts request body
{
discountsTransactionInformation: {
tenderIdentifier: '5',
orderGuid: '397e4458-8443-4153-8054-f72a3a95e57d',
check: {
guid: '8b838419-c262-4b90-b27d-63b94b2b3034',
entityType: null,
externalId: null,
displayNumber: '2',
payments: [],
appliedDiscounts: [],
shift: null,
lastModifiedDevice: null,
voidDate: null,
appliedPreauthInfo: null,
paidDate: null,
appliedLoyaltyInfo: null,
voided: null,
paymentStatus: null,
amount: 32.13,
tabName: null,
taxExempt: null,
netAmount: null,
tipAmount: null,
totalDiscountAmount: null,
pickedUpDate: null,
openedDate: null,
totalAmount: null,
selections: [
{
guid: '8de6e601-feb2-400b-900b-2b298d88dc4e',
entityType: null,
externalId: null,
deferred: null,
preDiscountPrice: 28,
voidReason: null,
optionGroup: null,
displayName: null,
appliedDiscounts: [],
externalPriceAmount: null,
modifiers: [],
seatNumber: null,
voidDate: null,
fulfillmentStatus: null,
optionGroupPricingMode: null,
salesCategory: null,
selectionType: null,
price: null,
voided: false,
appliedTaxes: [],
storedValueTransactionId: null,
itemGroup: null,
item: {
guid: '5045a930-f4d6-4e07-89eb-38f7340769be',
entityType: null,
externalId: null,
multiLocationId: null
},
taxInclusion: null,
quantity: null,
receiptLinePrice: null,
unitOfMeasure: null,
refundDetails: null,
toastGiftCard: null,
tax: null,
diningOption: null,
openPriceAmount: null,
voidBusinessDate: null,
createdDate: null,
preModifier: null,
modifiedDate: null
}
],
voidBusinessDate: null,
createdDate: null,
deleted: null,
createdDevice: null,
closedDate: null,
deletedDate: null,
modifiedDate: null,
taxAmount: null,
driverShift: null,
appliedServiceCharges: [],
customer: null
},
totalDiscountable: 28
},
paymentsTransactionInformation: null,
redeemTransactionInformation: null,
gratuityTransactionInformation: null,
reverseTransactionInformation: null,
searchTransactionInformation: null
}
Successful retrieve discounts response
tenderDiscountsApplied: [
{
name: 'Tender Discount',
identifier: '7509f8f8-2d15-4c79-bb76-eb1d3b73351a',
amount: 10,
selectionGuid: null,
appliedDiscountGuid: '8dffb8b7-96e8-4d9c-8b5a-4e0a1057e482'
}
]
},
gratuityTransactionInformation: null,
reverseTransactionInformation: null,
searchTransactionInformation: null
}
Successful response:
{ transactionStatus: 'ACCEPT' }
The retrieved discounts tenderDiscounts can be
check-level or item-level discounts.
The Toast platform retrieves payments after applying the discounts received from the PMS provider.
Retrieve payments workflow
-
The Toast platform sends a
TENDER_RETRIEVE_PAYMENTSrequest to the PMS provider. The request includes aTenderTransactionobject that holds the guest identifier (tenderIdentifier) and the updatedCheckobject in apaymentsTransactionInformationobject.Note
When discounting item groups, item quantities cannot be greater than
1in your discount response. Break up item groups into separate selections where itemquantity = 1and specify the discount for each separate selection. -
Your tender integration determines the payment and responds to the Toast platform with a
paymentsResponsevalue in theTenderTransactionResponseobject, which includes the payment information. -
The Toast platform applies the payment and updates the
Checkobject.
Retrieve payments request body
{
"discountsTransactionInformation":null,
"paymentsTransactionInformation": {
"tenderIdentifier": "2670f8d0-c9c1-4dd1-b234-6922a81a7792",
"amount": 2.11,
"tipAmount":0.00,
"orderGuid": "04ade72f-28c9-441c-a197-16d42c4c8f84",
"check":{
...
appliedDiscounts: [
{
guid: '8dffb8b7-96e8-4d9c-8b5a-4e0a1057e482',
entityType: 'AppliedDiscount',
externalId: null,
approver: null,
loyaltyDetails: null,
discountPercent: null,
comboItems: [],
discountAmount: 10,
discount: null,
triggers: [],
appliedPromoCode: null,
processingState: 'PENDING_APPLIED',
name: 'Tender Discount',
nonTaxDiscountAmount: null,
discountType: null
}
],
...
"selections":[
...
"appliedDiscounts":[
{
"guid":"6b11b9d2-7a3e-4b52-9c74-b451e41ec306",
"entityType":"AppliedExternalDiscount",
"externalId":null,
"approver":null,
"processingState":"PENDING_APPLIED",
"loyaltyDetails":null,
"name":"Tender Discount",
"comboItems":[
],
"discountAmount":10.0,
"discount":null,
"nonTaxDiscountAmount":null,
"triggers":[
],
"appliedPromoCode":null
}
],
...
},
tenderDiscountsApplied: [
{
name: 'Tender Discount',
identifier: '7509f8f8-2d15-4c79-bb76-eb1d3b73351a',
amount: 10,
selectionGuid: null,
appliedDiscountGuid: '8dffb8b7-96e8-4d9c-8b5a-4e0a1057e482'
}
]
},
gratuityTransactionInformation: null,
reverseTransactionInformation: null,
searchTransactionInformation: null
}
Successful response:
{ transactionStatus: 'ACCEPT' }
Successful retrieve payments response
{
"paymentsResponse":{
"account":{
"tenderIdentifier":"2670f8d0-c9c1-4dd1-b234-6922a81a7792",
"properties":[
{
"key":"name",
"value":"john adams"
}
]
},
"tenderPayments":[
{
"name":"Tender Payment",
"identifier":"b1727f60-a5ce-4391-9ed6-e37e8a92f1b9",
"type":"STORED_VALUE",
"amount":2.11,
"tipAmount":0
}
]
},
"transactionStatus":"ACCEPT"
}
After the Toast platform applies payments to the check, the discounts and payments are redeemed. For more information about gratuity payments, see Gratuity.
Redeem discounts and payments workflow
-
The Toast platform sends a
TENDER_REDEEMrequest to the PMS provider. -
The PMS provider marks the discounts as used and adds the payment to the guest's account.
-
The restaurant employee closes the check if the full amount is covered by the room charge.
Redeem discounts and payments request body
{
"discountsTransactionInformation":null,
"paymentsTransactionInformation":null,
"redeemTransactionInformation": {
"tenderIdentifier": "2670f8d0-c9c1-4dd1-b234-6922a81a7792",
"orderGuid": "04ade72f-28c9-441c-a197-16d42c4c8f84",
"check":{ [content omitted]},
"tenderPaymentsApplied": [
{
"name": "Tender Payment",
"identifier": "b1727f60-a5ce-4391-9ed6-e37e8a92f1b9",
"type": "STORED_VALUE",
"amount": 2.11,
"tipAmount": 0.0,
"paymentGuid":"af10f95f-9ee7-4975-933d-afa2cf6806e2"
}
],
"tenderDiscountsApplied": [
{
"name": "Tender Discount",
"identifier": "0e557a20-b36d-4be4-9367-221d3d082780",
"amount": 4.0,
"selectionGuid":null,
"appliedDiscountGuid":"26595a7b-9ad9-497a-aa45-4539989e10a2"
},
{
"name":"Tender Discount",
"identifier":"31d6cdf2-e766-4754-8759-f8a0f17aa9cf",
"amount":5.00,
"selectionGuid":"145071fe-ef70-4dda-a9ce-520bde54abca",
"appliedDiscountGuid":"6b11b9d2-7a3e-4b52-9c74-b451e41ec306"
}
]
},
"gratuityTransactionInformation":null,
"reverseTransactionInformation":null
}
If configured, the Toast platform prompts the restaurant employee for a gratuity after the Toast platform receives a response from the PMS provider about the discounts and payments redemption.
|
Note |
|
Gratuity functionality is configurable through Toast Web. Toast support recommends that integration developers use the gratuity transaction to consume all tips related to tender payments. Partners that do so should ignore non-zero values in the tipAmount field contained within the redeem transaction. |
Gratuity workflow
-
After an employee enters a gratuity amount, the Toast POS system sends a
TENDER_GRATUITYrequest that specifies a gratuity amount to add to aTENDER_REDEEMtransaction. TheToast-Transaction-GUIDofTENDER_REDEEMto add the gratuity amount is provided in thetransactionToUpdatevalue in the body of theTENDER_GRATUITYrequest. -
The PMS provider responds to the Toast platform with a
gratuityResponsevalue in theTransactionResponseGratuityobject, which contains the value of gratuity that the guest added.
Gratuity request body
{
discountsTransactionInformation: null,
paymentsTransactionInformation: null,
redeemTransactionInformation: null,
gratuityTransactionInformation: {
tenderIdentifier: '2',
accountInfo: {
tenderIdentifier: '2',
properties: [[content omitted]],
expansionSearchCriteria: []
},
transactionToUpdate: 'c8b6eee9-7bae-478b-a9d1-54b01d769bd8',
additionalGratuity: 2.86,
paymentGuid: '5ac74eb2-2b79-4921-8624-d269b0ba29d5',
tenderPayments: [
{
name: 'Tender Payment',
identifier: 'dc6579c3-ce49-490a-b4d1-9ca955d453e4',
type: 'STORED_VALUE',
amount: 1.29,
tipAmount: 0,
paymentGuid: '5ac74eb2-2b79-4921-8624-d269b0ba29d5'
}
],
checkInfo: {
guid: 'e1adf897-df21-4b14-8e3f-6d7c26dad6b5',
displayNumber: '2'
},
orderGuid: '1be33a7f-7f17-45ed-87f2-4dfb845a439e',
check: {[content omitted] 
],
reverseTransactionInformation: null,
searchTransactionInformation: null
}
Successful gratuity response body
{
gratuityResponse: {
account: {
tenderIdentifier: '2',
properties: [
{ key: 'Room Number', value: '406' },
{ key: 'Name', value: 'john adams' },
{ key: 'Reservation Number', value: '7492936' },
{ key: 'Company Name', value: 'Apple, Inc.' },
{ key: 'Guest Status', value: 'Active' },
{ key: 'Charge Limit', value: '$120.00' }
],
additionalProperties: [ { key: 'storedValue', value: 55.85 } ]
},
tenderPayments: [
{
name: 'Tender Payment',
identifier: 'dc6579c3-ce49-490a-b4d1-9ca955d453e4',
type: 'STORED_VALUE',
amount: 1.29,
tipAmount: 2.86,
paymentGuid: '5ac74eb2-2b79-4921-8624-d269b0ba29d5'
}
]
},
transactionStatus: 'ACCEPT'
A transaction is reversed in the following situations:
-
If the restaurant employee voids the payment, the Toast POS system sends a
TENDER_REVERSErequest to the PMS provider to reverse the payment and any applied discounts. -
If the restaurant employee voids the order, then the Toast POS system sends a
TENDER_REVERSErequest to the PMS provider. -
If a discount times out during redemption, then the Toast POS system sends a
TENDER_REVERSErequest to the PMS provider.
Reverse requests can be one or more of the following:
-
Payments
-
Discounts
In the request body, the value of
transactionToUpdate is the
Toast-Transaction-GUID of the TENDER_REDEEM
request. The discountsToRemove and
paymentsToRemove contain the discounts and payment
identifiers, respectively. The orderGuid is the order's
unique Toast identifier.
Reverse request body
{{
discountsTransactionInformation: null,
paymentsTransactionInformation: null,
redeemTransactionInformation: null,
gratuityTransactionInformation: null,
reverseTransactionInformation: {
tenderIdentifier: '2',
accountInfo: {
tenderIdentifier: '2',
properties: [<content omitted>
}
],
additionalProperties: [
{
key: 'storedValue',
value: '55.85',
tenderPropertyType: 'OTHER',
maxLength: null
}
],
expansionSearchCriteria: []
},
transactionToUpdate: '1426c50c-8f84-4f20-ae02-f54185133573',
discountsToRemove: [
'86cd8aa2-ccc6-43ff-9b8b-5e0e13028dc9',
'c7995999-3f54-4d05-a6e8-62677870e6a0'
],
paymentsToRemove: [ 'ac10fa62-0bb9-4e75-a96e-b2fbbe2236a3' ],
tenderPaymentsToRemove: [
{
name: 'Tender Payment',
identifier: 'ac10fa62-0bb9-4e75-a96e-b2fbbe2236a3',
type: 'STORED_VALUE',
amount: 3.36,
tipAmount: 5,
paymentGuid: 'dcf60b0e-60c2-47b2-a246-f6e73c1e46e3'
}
],
tenderDiscountsToRemove: [
{
name: 'Tender Discount',
identifier: '86cd8aa2-ccc6-43ff-9b8b-5e0e13028dc9',
amount: 8.21,
selectionGuid: null,
appliedDiscountGuid: '9438ff81-5b50-4e53-bdcc-b56d1560faab'
},
{
name: 'Tender Discount',
identifier: 'c7995999-3f54-4d05-a6e8-62677870e6a0',
amount: 0.65,
selectionGuid: null,
appliedDiscountGuid: '6a291621-dcce-4ec5-a7f7-37e29ba7f760'
}
],
checkInfo: {
guid: '775fed9a-70ce-4acc-b329-88aad0c4828b',
displayNumber: '1'
},
originalTransactionStatus: 'ACCEPT',
orderGuid: '8c07e3d0-6804-4a39-912a-dd06d0887b88'
},
searchTransactionInformation: null
This section describes the user interface workflow in the Toast platform for billing a hotel restaurant guest using the hotel's PMS provider.
At the payment phase of the Toast platform order workflow:
-
A guest chooses to pay a balance due by applying the balance to their room charge.
-
An employee selects the Pay ($) button to navigate to the Payments screen.
-
The restaurant employee selects the Other button.
-
The dialog appears and Hotel Room Charge is listed as an option.
Note
The name of the payment option is configurable from the Toast Web at Payments > Other Payment Options.
-
After selecting room charge, a Lookup Hotel Guest dialog appears.
-
The restaurant employee enters information to look up a guest and selects Search. For example, they enter a room number in the Enter Room # field.
-
Once the search is complete, a list of search results appears on the Toast POS device.
-
The restaurant employee selects the record corresponding to the guest that owes the check amount and processes the payment with the PMS provider. If digital receipts are configured, the Toast POS device prompts the restaurant employee to add the tip amount.
If the restaurant employee chose to print a receipt, the Room Charge payment and any applied discounts are printed on the receipt.
You can view information about tender transactions in the Sales Summary report. This report can be accessed by navigating to Reports > Sales > Sales Summary in Toast Web. Room charge tender payments appear in the Other section of the Sales Summary report, as shown below, and in the Payments tab. The payment Type is shown as Other from the Payments tab.
