# Point of Sale UI Guidelines The checkout process at the Point of Sale (POS) triggers an interaction with the cashier in order to gather customer information and determine if the customer wants a digital receipt. This section has example screenshots and explanations of what is required and the expected behavior of the POS UI. ## In This Guide * [Receipts API Integration Guide](/receipts/receipts-integration-guide.html) — authentication, request/response flow, error handling, and best practices. * [Request Field Reference](/receipts/request-reference.html) — field-by-field usage notes for headers, discounts, loyalty, tenders, taxes, items, custom fields, and more. * [Receipt Data Elements](/receipts/receipt-data-elements.html) — how request fields map to sections of a rendered receipt (orders, returns, totals, deposits, payment history, and more). * **Point of Sale UI Guidelines** — recommended configuration options and UI flow. * [Printed Offers](/receipts/printed-offers.html) — for merchants whose package includes printed offers. * [SMS Receipts](/receipts/sms-receipts.html) — for merchants whose package includes SMS delivery. * [Integration Testing Checklist](/receipts/testing-checklist.html) — validate your integration before launch. ## Configurability The following information should be configurable, either stored and changeable as part of the POS setup in a configuration file, or via a setup screen: * Ability to independently turn the POS screen prompts ON/OFF per register. * This allows the Merchant to disable prompting for Customer Information. For example, the Merchant may not have time to obtain email address from each customer at a high velocity location such as a concession stand. The POS should still send all captured Customer Information in the web service requests. * Ability to independently turn the flexEngage integration ON/OFF per register. * This allows the Merchant to disable the integration for individual registers. For example, the Merchant may be experiencing issues at only one specific register at a store, and would not want to disable the integration at the other working registers. * URL for web services. * Should allow for fully qualified URL (including https://). * Can have editable presets for Production, Test, and Custom. * Merchant ID (provided by flexEngage). * API Keys used for HTTP Basic Authentication. * Store Information (including address if not available directly from the POS). * Timeout setting (in seconds). * Email domain preset buttons to speed email address entry (e.g., @gmail.com, @yahoo.com, etc). ## Setup Screens In order to make the integration configurable (per merchant, per store, per register), one or more setup screens should be created like the below examples: **General Settings** The following information is provided by flexEngage and should be configurable without modifying source code (i.e. changes in a setup screen or in a properties file): * **Merchant ID**: This is a flexEngage Merchant ID that is provided by flexEngage and allows the merchant to send digital receipts. * **Web Service URLs**: These are the URLs needed for different flexEngage environments: * Production - This is the URL for normal operation once a Merchant is live in production. * Test - This is the URL for testing purposes or troubleshooting. * Custom - This provides future flexibility to point to alternate environments if needed. * All values should be written to a properties file for persistence. Updating the values on this screen should also update the properties file. * URLs should be fully qualified (e.g., `https://api.flexreceipts.com/ws/rest/v1`). ![General Settings setup screen](/receipts/images/pos-setup-general-settings.png) **Store Information** If the POS does not already store the Store Name and Store Address information in a compatible format, you may need to setup a Store Information configuration screen. ![Store Information setup screen](/receipts/images/pos-setup-store-information.png) **Email Providers** The email domain presets should be configurable and allow the store to add additional common domain names that are appended when pressed (e.g., @gmail.com, @hotmail.com, @yahoo.com, @aol.com, etc). Up to five configurable email domain presets should be available to speed email address entry. ![Email Providers setup screen](/receipts/images/pos-setup-email-providers.png) ## Receipt Selection When the customer is offered a digital receipt, a dialog box (such as the example below) should be presented at the POS to collect their email address and receipt option. ![Receipt Selection dialog](/receipts/images/pos-receipt-selection-dialog.png) ***Note: You will get a higher adoption rate if customers are told that you now email your receipts rather than just asking if they would like an email receipt.*** Populate the email field if the POS has the customer's email address on file for verification by the customer. **If the customer changes the pre-populated email address, you should update the POS customer record (if applicable) and send the updated email with the Request web service message.** The email address structure should be validated before accepting the email in this form: * The 'Email' field cannot be blank for 'Digital Receipt Only' and 'Digital Receipt + Printed Receipt'. * The email address should not contain any illegal characters for email addresses. * The email address should be complete with the format xxx@xxx.yyy where 'xxx' is at least 1 legal character and 'yyy' is a valid domain extension. ## Transmission Message When transmitting information to flexEngage an information box should be presented at the POS: ![Transmission Message](/receipts/images/pos-transmission-message.png) ## Confirmation Message Upon a successful response from **Response** web service message (i.e., the digital receipt was successfully sent), a confirmation box should be presented at the POS to notify the cashier or customer: ![Confirmation Message](/receipts/images/pos-confirmation-message.png) ***Note: Paper Only transactions should NOT display a confirmation message about the receipt being sent to flexEngage.*** ## Error Message In the event that the flexEngage service is unavailable (e.g., network connection issues, power outage) or the digital receipt cannot be processed, an error message is displayed at the POS to notify the cashier or customer: ![Error Message](/receipts/images/pos-error-message.png) **NOTE:** flexEngage sends detailed error codes and error messages that will greatly reduce troubleshooting time. Descriptive exception codes and error messages should be included in the error dialog box. flexEngage will require the error code, message, and referenceId returned in order to troubleshoot issues in a timely manner. See [Common Error Responses](/receipts/receipts-integration-guide.html#common-error-responses) in the main guide.