Closing the Bill

Discounts and Vouchers

When a customer uses Zapper to pay their bill, they will have the option of applying one or more types of vouchers or discounts to pay for part of the bill. When reconciling the bill on your POS software, you will need to know the types of vouchers that can be redeemed and calculate accordingly:

Merchant Voucher

This is a voucher that is explicitly given to a user by the Merchant. When paying, the user can opt to use the voucher, which will the reduce the amount paid. This is paid for by the Merchant, so if there is a differentiation in the POS software between customer paid amounts and discounts/coupons, then this will need to be taken into consideration and applied to the bill as appropriate.

Zapper Discount

This is a once-off discount that Zapper gives every new user, this is normally a set amount and is covered completely by Zapper. When closing the bill, this can be treated as though the customer is paying (i.e. simply adding it to the paid amount). This is also non-optional for the user, when paying the first time, this will be applied.

Generic Voucher

This is similar to the Zapper Discount in that the cost is covered by Zapper, however, in the UI of the app, the user can opt to use the voucher or not. The voucher is also bound by the same rules that would govern a Merchant Voucher, like minimum spend, expiration date, etc.

When calculating the amounts to use when closing the bill, please see Applying Payments to the Invoice.

Get Notified of a Zapper Payment

When a customer pays their bill through the Zapper mobile app, the Zapper API instantly records the success or failure of the transaction. The result needs to be sent to the POS as quickly as possible so that:

  • Staff can help customers resolve failed payments / take alternative payment.

  • Staff know that a customer has paid, and customers know that staff know.

  • The payment is allocated against the bill / check / table in the POS.

  • The bill / check / table can be closed as appropriate.

  • A confirmation receipt can be printed (see below) for each Zapper payment.

Zapper provides a range of alternative approaches to communicate payment notifications to POS systems, depending on your preferred integration technique:

  • Listen for a webhook / callback to your own HTTP/S API endpoint (per-merchant site if necessary) indicating a payment event. See Notification Configuration.

  • Open a connection to Zapper's SignalR Hub to receive near-instant events for each payment, and acknowledge back to confirm receipt of each payment you have received. See Realtime Notifications.

  • Fetch any "new" payments, and acknowledge (POST) back to confirm receipt of each payment you have received. See Get Unacknowledged Payments.

Notification Approaches

Note that the various API capabilities for payment notifications must be used in combination in the following configurations only:

Approach

Step 1

Step 2

Step 3

"Listen" for webhook

Listen / receive POSTs from Zapper contain payment details. Developer Documentation

For each notification GET by PosReference for the full payment details. Developer Documentation.

POST the ID of each received payment to Zapper to acknowledge that the payment notification has been received. Developer Documentation

Poll periodically for "new payments"

Poll /merchants/…/sites/…/Payments every few seconds for new, unconfirmed payments. Developer Documentation

POST the ID of each received payment to Zapper to acknowledge that the payment notification has been received. Developer Documentation

Poll periodically for "new payment notifications"

Poll /merchants/…/sites/…/PaymentNotifications every few seconds for new, unconfirmed payment notifications. Developer Documentation

For each notification, GET /payments/{id} for the full payment details. Developer Documentation

POST the ID of each received payment to Zapper to confirm the payment notification has been received. Developer Documentation

Open SignalR connection for payment notifications

Receive notification events in real time through the open SignalR connection. Developer Documentation

For each notification, GET /payments/{id} for the full payment details. Developer Documentation

POST the ID of each received payment to Zapper to confirm the payment notification has been received. Developer Documentation

Acknowledge Zapper Payment Notification

Once a payment has been received and applied to the bill you should let Zapper know, so that the notification is not re-sent. Acknowledge Notifications by calling Acknowledge Payment Notification

This must be called to let the Zapper API know that the payment went through successfully.

Applying payments to the invoice

For successful payments (ReceiptStatus = 2), the value to apply towards the bill / invoice is defined as follows:

PaidAmount + ZapperDiscountAmount + TotalVoucherAmount

The POS system must reduce the outstanding balance on the bill by this amount. This amount may be less than the bill total, if a diner is paying only part of the bill (i.e. split-bill scenarios).

If the POS system handles tax deductions on merchant discounts then the following calculation must be used to apply to the bill / invoice after the “TotalMerchantVoucherAmount” is discounted:

PaidAmount + ZapperDiscountAmount + TotalGenericVoucherAmount

Note that these attributes are available on the Payment object only, retrieved through one of the following: