Are you looking for test card numbers?

Would you like to contact support?

Point-of-sale icon

Make Pay-at-table payments

How to use terminal initiated payment flows like Pay at table or Pay at curbside.

Requirements

For Pay at table you need a Terminal API integration and terminals that have a printer and Wi-Fi.

To accept payments from your customers at a table, in a hotel room, or curbside, you can initiate payments from a terminal while keeping the terminal integrated with your POS system.

The terminal initiated payment flow offers:

  • Equal and unequal split payments.
  • Support for all payment methods that you added to your account, as well as cash.
  • Easy combination with tipping options.
    Customers can enter a tip amount on the terminal with every split payment. If you let your staff authenticate when they start the payment from the terminal, you can then log the tip with that staff member to avoid adjusting tips later.

For Pay at table you need to use portable payment terminals. These terminals have an integrated printer and a Wi-Fi connection, and can automatically switch to a cellular connection if the Wi-Fi connection drops.

Work in progress: this feature is not supported yet on Android payment terminals.

How it works

After you have configured Pay at table, the flow is as follows:

  1. On the terminal, your staff selects a button to start Pay at table, and authenticates by entering their reference number or swiping their employee card.

  2. The terminal sends an SaleWakeUp event notification to the POS system. The notification informs the POS system that the terminal is waiting to receive a payment request.

  3. Based on the employee's authentication, you decide which bill to send a payment request for. If there are multiple bills, you send an InputRequest to the terminal so that your staff can provide more details. For example, ask for a table number, a choice from a list of bills, or a ride number. See Step 1: Retrieve the sale transaction.

  4. You send a PrintRequest to print the bill using the terminal. This is optional. It depends on your business needs whether to do this and when.

  5. You send a PaymentRequest from the POS system to the terminal. See Step 2: Make a payment.

  6. The terminal shows the amount due, Split check, and options to:

    • Split the bill Equally. The terminal will ask for the number of splits.
    • Split the bill Unequally. The terminal will ask for the amount of the first split. This is also the option to choose if a single customer is paying the whole bill.

  7. Then the terminal shows the split amount and options to:

    • Pay by Card. Your staff hands the terminal to the customer so that they can pay their split and, if configured, respond to the tipping options on the terminal.
    • Pay in Cash. Your staff receives the cash and selects a button on the terminal display to confirm.

    If you don't want to accept cash payments, we can configure skipping the prompt for cash or card.

  8. After the split payment is Approved and Sent, the terminal prints a receipt.

  9. You process the split payment response, to keep track of the amount that has been paid. See Step 3: Process the payment result.

  10. If there is a remaining amount due, the terminal shows Next split and options to:

    • Pay later. This is used for a group of customers who want to pay their share of the bill at different times. The terminal shows Cancelled. When someone else from the group is ready to pay, your staff needs to start Pay at table again.
    • Pay remainder. You send another PaymentRequest for the next split payment (see Step 2 and Step 3).
      With equal splits, the terminal calculates the amount of the next split payment based on the number of splits. With unequal splits, the terminal shows the remaining amount and your staff enters the amount of the next split payment.

    This continues until the full amount has been paid.

Configure Pay at table

To enable Pay-at-table:

  1. Set up event notifications. This is necessary to let the terminal send a SaleWakeUp event notification to the POS system. This notification informs the POS system that the terminal is waiting to receive a payment request.

  2. Configure settings in your Customer Area:

    1. In your Customer Area, go to Point of Sale > Terminals and select your terminal.
    2. On the Settings page, go to Integrations > Notification button.
    3. Turn on the Enable notification button toggle switch.
    4. Set the following values:

      Field Description
      Notification category Select Sale wake up.
      Title Enter the text to show on the button that starts the flow from the terminal. For example, Pay@tTable
      Details Enter the text to ask your staff to enter their reference number or swipe their employee card.

      The reference or card number can be a maximum of 10 digits.

      If you leave this field empty, the terminal sends the SaleWakeUp event notification immediately when the button is selected, and the notification doesn't include the reference or card number.

    5. Select Save.

  3. Contact our POS Support Team to:

    • Set your staff's authentication method: entering a reference number, or swiping an employee card.
    • If you don't want to accept cash payments, skip prompting for cash or card.
  4. Add logic to your POS system so that it is able to handle the SaleWakeUp event notification.

SaleWakeUp event notification

The SaleWakeUp event notifications that the terminal sends to the POS system include:

  • EventToNotify: SaleWakeUp
  • EventDetails: the employee's reference number or employee card number. For example, reference_id=0123456789. You can use this to retrieve the associated bill, or to log sales and tips per staff member.
Example SaleWakeUp notification
{
   "SaleToPOIRequest":{
      "EventNotification":{
         "EventDetails":"reference_id=0123456789",
         "EventToNotify":"SaleWakeUp",
         "TimeStamp":"2019-11-15T10:16:10.000Z"
      },
      "MessageHeader":{
         "DeviceID":"1517998561",
         "MessageCategory":"Event",
         "MessageClass":"Event",
         "MessageType":"Notification",
         "POIID":"V400m-324688179",
         "ProtocolVersion":"3.0",
         "SaleID":"POSSystemID12345"
      }
   }
}

Step 1: Retrieve the sale transaction

When the POS system receives a SaleWakeUp event notification:

  1. Get the reference or employee card number received in the EventDetails field of the event notification.
  2. Retrieve the sale transactions (the bills) associated with the reference number or employee card number, or with the terminal.
  3. If there is only one open bill, skip to Step 2: Make a payment.
  4. If there are more open bills, make an InputRequest (or a series of input requests) to ask your staff to enter more information on the terminal.
    For example, first ask for the table number with a text input request. Then send a menu input request to show a list of bills associated with the table number and ask your staff to select one.

    While an input request is being processed, you may want to show a waiting screen animation. You can do this by creating a session that includes multiple input requests and shows the waiting screen when processing. To learn more, refer to Create a session.

  5. Process the responses to your input requests so that your POS system is able to retrieve the correct bill to send a payment request for.

Step 2: Make a payment

Technically Pay-at-table is a split payments flow. You make several subsequent payment requests for the same sale until the full amount has been paid. If a single customer pays the entire bill, that is an unequal split for the full amount and you need to make only one split payment request.

In this split payments flow, you:

  • Set the split payments flag to true in each payment request.
  • Specify a unique sale transaction ID in the first payment request, and repeat that same ID in all subsequent split payments for the same sale.
  • Make sure your POS system keeps track of the amount that has been paid already.

After you have received a SaleWakeUp event notification from the terminal and collected information to determine for which bill the terminal wants to receive a payment request, proceed as follows:

  1. Optional. From your POS system, send a PrintRequest to let the terminal print the bill.

  2. Make a POST request to a Terminal API endpoint, specifying:

    • PaymentRequest:

      Parameter Required Description
      SaleData.SaleTransactionID -white_check_mark- An object with TransactionID containing your reference for the sale (for example, the bill for table 5), and TimeStamp containing the date and time of the request in UTC format.

      All split payments belonging to the same sale (the same bill) must use this same TransactionID.

      PaymentTransaction.AmountsReq -white_check_mark- An object that indicates how much remains to be paid and how much has been paid already:
      • Currency: the currency of the transaction.
      • RequestedAmount: the amount that remains to be paid. For the first split payment, this is the full sale amount. For a subsequent split payment, this is the sale amount minus the PaidAmount.
      • PaidAmount: The amount that has already been paid. For the first split payment, this is zero. For a subsequent split payment, this is the sum of the amounts paid in previous split payments for the same sale.
      PaymentData -white_check_mark- An object that sets the split payment flag, with:
      • PaymentType: Normal
      • SplitPaymentFlag: true

    You can add other PaymentRequest fields as needed. For example to trigger the terminal to show the tipping options you configured.

    Sample first Pay at table payment request
    {
      "SaleToPOIRequest": {
        "MessageHeader": {
          "ProtocolVersion":"3.0",
          "MessageClass":"Service",
          "MessageCategory":"Payment",
          "MessageType":"Request",
          "SaleID":"POSSystemID12345",
          "ServiceID":"0207111104",
          "POIID":"V400cPlus-301506502"
        },
        "PaymentRequest": {
          "SaleData": {
            "SaleTransactionID": {
              "TransactionID": "9820s",
              "TimeStamp": "2019-11-12T12:58:23.000Z"
            }
          },
          "PaymentTransaction": {
            "AmountsReq": {
              "Currency": "USD",
              "RequestedAmount": 89.65,
              "PaidAmount": 0
            }
          },
          "PaymentData": {
            "PaymentType": "Normal",
            "SplitPaymentFlag": true
          }
        }
      }
    }

    The payment request is routed to the terminal. This shows options to split Equally or Unequally, as described in How it works.
    When the payment is processed, you receive the payment result.

    If only a partial amount has been paid, the terminal shows options to Pay later or Pay remainder.
    If Pay remainder is selected, the terminal automatically calculates the next split in case of equal splits, or asks for the next amount in case of unequal splits.
    You would then make the next split payment request as shown in the next example.

    Sample request for the next split payment after $20 has been paid
    {
      "SaleToPOIRequest": {
        "MessageHeader": {...},
        "PaymentRequest": {
          "SaleData": {
            "SaleTransactionID": {
              "TransactionID": "9820s",
              "TimeStamp": "2019-11-12T13:44:20.000Z"
            }
          },
          "PaymentTransaction": {
            "AmountsReq": {
              "Currency": "USD",
              "RequestedAmount": 69.65,
              "PaidAmount": 20
            }
          },
          "PaymentData": {
            "PaymentType": "Normal",
            "SplitPaymentFlag": true
          }
        }
      }
    }

Step 3: Process the payment result

When you receive the PaymentResponse for a split payment:

  1. Determine whether more split payments are needed to pay off the bill.
    • Response.Result: Success indicates the full RequestedAmount has been paid. Partial indicates there's still an amount due, so more split payments are needed.
  2. If more split payments are needed, keep track of the amount that has been paid with the transaction, and add this to the PaidAmount in a subsequent split payment for the same sale. Check these response fields:

    • SaleData.TransactionID: includes the TransactionID of the sale (the bill) that the split payment belongs to.
    • AmountsResp.AuthorizedAmount: the amount that has been paid with this transaction.
    Sample response for a partial card payment of $20
    {
      "SaleToPOIResponse": {
        "MessageHeader": {...},
        "PaymentResponse": {
          "POIData": {...},
          "SaleData": {
            "SaleTransactionID": {
              "TimeStamp": "2019-11-12T12:58:23.000Z",
              "TransactionID": "9820s"
            }
          },
          "PaymentResult": {
            "OnlineFlag": true,
            "PaymentAcquirerData": {...},
            "PaymentInstrumentData": {
              "CardData": {...}
              },
              "PaymentInstrumentType": "Card"
            },
            "AmountsResp": {
              "AuthorizedAmount": 20,
              "Currency": "USD"
            },
            "PaymentType": "Normal"
          },
          "Response": {
            "Result": "Partial",
            "AdditionalResponse": "tid=01506502&AID=A0000000041010&transactionType=GOODS_SERVICES&backendGiftcardIndicator=false&posadditionalamounts.originalAmountValue=2000&..."
          }
        }
      }
    }
    Sample response for cash payment of the full remaining amount
    {
      "SaleToPOIResponse": {
        "MessageHeader": {...},
        "PaymentResponse": {
          "POIData": {...},
          "SaleData": {
            "SaleTransactionID": {
              "TimeStamp": "2019-11-12T13:44:20.000Z",
              "TransactionID": "9820s"
            }
          },
          "PaymentResult": {
            "OnlineFlag": false,
            "PaymentAcquirerData": {...},
            "PaymentInstrumentData": {
              "PaymentInstrumentType": "Cash"
            },
            "AmountsResp": {
              "AuthorizedAmount": 69.65,
              "Currency": "USD"
            },
            "PaymentType": "Normal"
          },
          "Response": {
            "Result": "Success"
          }
        }
      }
    }
  • In the PaymentResponse, also note the following

    • PaymentResult.OnlineFlag: true for a card or wallet payment, or false for a cash payment.
    • PaymentResult.PaymentInstrumentData.PaymentInstrumentType: Cash or Card
    • Response.AdditionalResponse: additional transaction data. You'll receive either a string of form-encoded key-value pairs or a Base64 string that you need to decode to get a JSON object. For a cash payment, this field isn't included.

  • If Pay later is selected on the payment terminal when it receives a request for a subsequent split payment, the terminal shows Cancelled. You receive a payment result containing:

    • PaymentResponse.Response.Result: Failure
    • PaymentResponse.Response.ErrorCondition: PaymentRestriction. This indicates that the Pay-at-table flow was interrupted. It's not the preceding split payment that failed.

  • If the payment failed, the terminal shows Declined and you receive a payment result containing:

    • PaymentResponse.Response.Result: Failure
    • PaymentResponse.Response.ErrorCondition: indicates why the payment failed. For example, Refused indicates the card issuer refused the transaction, and Cancel indicates the transaction was cancelled on the terminal. Refer to our refusal reasons documentation.

Information for your staff

Authentication

To start Pay at table, your staff selects the button you configured. Then they need to authenticate. On the terminal, they can:

  • Enter their employee reference number
  • Swipe their employee card

If employees usually authenticate by swiping their employee card but don't have their card available, they can select the Cancel key to switch to entering their reference number. To switch back to swiping, they need to select the Cancel key again.

Previous step or cancel

After starting Pay at table, your staff can:

  • Press to go back a step in the flow. This is possible until the moment Cash or Card is selected.
  • Press to cancel the flow at any point.

Keeping your staff informed

The terminal will show the usual progress messages while a payment is processed. However, any errors occurring at other moments in the Pay-at-table flow are received at the POS system. Because your staff is not near the POS system, they won't know what happened and what they need to do. To help them, you can make a DisplayRequest to send a message from the POS system to the terminal.

Related steps