Initialising a Site

If a particular restaurant has decided to use Zapper payments, a Zapper QR code is printed on every bill from the POS in that restaurant – there is no need for a customer or staff member to select or enable Zapper on a per-table, per-customer basis.

Of course, not all restaurants will use Zapper, so you will need a way of enabling Zapper functionality in your POS software on a per-restaurant basis.

Zapper models restaurants using the concepts of Merchants and Sites. Each restaurant (actual geographic location) has a unique pair of MerchantId and SiteId; both values must be configurable for each restaurant using Zapper payments.

The process of facilitating and processing a Zapper payment relies on information you store, configure or create – some of which varies per site and some per-transaction, etc.

Initialising a site with the Zapper API

When a merchant chooses to enable Zapper payments in your POS system, they need to initialise each site with the Zapper API. Your solution should provide a mechanism which does the following:

  1. Allow the merchant to enter the Zapper Merchant Id (Integer) and Zapper Site Id (Integer) for the site they are initialising.

  2. Make a call to the Request one-time pin API endpoint (See Developer Documentation). This sends a PIN / verification code to the merchant.

  3. Allow the merchant to enter their PIN / verification code (Integer)

  4. Use the MerchantId, SiteId and PIN / verification code to pull down (and store) the per-site identity and authentication details from Zapper (See Developer Documentation).

The MerchantId, SiteId and other details provided by Zapper in the second of these steps should be stored and used in subsequent API calls for that site.

Site-specific Configuration

As described above, Zapper provides certain per-merchant and per-site values which you will need to use in API calls. These include:

  • MerchantId – an integer, provided by the Merchant at initialisation

  • SiteId – an integer, provided by the Merchant at initialisation

  • PosKey – a GUID (string), provided by the Zapper API at initialisation

  • PosToken – a GUID (string), provided by the Zapper API at initialisation

  • Currency – an ISO code (string), provided by the Zapper API at initialisation

In addition the following sections describe several other values you should store, relating to the site, the POS system, or the terminal.

App Functions

When generating the QR code you will also need to set the following settings, which may vary per-merchant and per-site (i.e. you should allow merchants to configure these per-site):

  • Tip Function Enabled/Disabled – this controls the Tip function in the Zapper mobile app.

  • Tip Function Default Percentage – this sets the tip function to a particular value when the customer scans a bill in the Zapper app. Possible values: 0%, 10%, 12.5%, 15%, 20%, 30%

  • Split Bill Function Enabled/Disabled – this turns on or off the Split Bill function in the Zapper mobile app

PosID (per terminal)

You should also create a "PosID" value (a GUID) to use in certain API calls. This should be a unique value for each "terminal" (till, Master, Slave, host, server etc) accessing the API (or virtually represented by server-side code acting on behalf of the terminals). Therefore there may be multiple PosID's per site. This is the only per-terminal value required in the Zapper API.

POS System Identity

Finally, note that the API also requires the following values to be included in request headers (see Request headers) for logging / support purposes:

  • POS Type – a string representing the name of your POS software.

  • POS Version – a string indicating the version of your POS software which is calling the API.