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.

Retrieve payments

The Toast platform retrieves payments after applying the discounts received from the PMS provider.

Retrieve payments workflow

  1. The Toast platform sends a TENDER_RETRIEVE_PAYMENTS request to the PMS provider. The request includes a TenderTransaction object that holds the guest identifier (tenderIdentifier) and the updated Check object in a paymentsTransactionInformation object.

  2. Your tender integration determines the payment and responds to the Toast platform with a paymentsResponse value in the TenderTransactionResponse object, which includes the payment information.

  3. The Toast platform applies the payment and updates the Check object.

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"
}