Payments API - Pairing Flow

Overview

If servicing multi-outlet (or multi-lane) merchants, then your payment integration needs to have some concept of association between Lightspeed Retail (X-Series) Registers and Payment Terminals, so that your web service knows which terminal in the store - or in the country - a transaction is intended for.

We call the method the user follows to create this association the Pairing Flow. And will aim to describe the best practice for pairing here.

If you think you are getting ahead of yourself, see the Getting Started Guide.

Concepts

Registers in Lightspeed Retail (X-Series)

A register in Lightspeed Retail (X-Series) refers to a place in an outlet (or store), where goods or services are sold from. This means that a register is its own device, iPad or computer, and needs its own ability to take payments. For this reason, we recommend associating each individual register in Lightspeed Retail (X-Series) with a Payment terminal (by serial number).

Unique Pairings

Each register in Lightspeed Retail (X-Series) has a Universally Unique Identifier (UUID), and each payment terminal has a unique Serial Number (S/N), which can be used to create a unique association that your service can then store and use to direct transactions to the correct terminals.

To access the UUID of a register, you will need OAuth access to the Lightspeed Retail (X-Series) store. You are then able to
For help with OAuth, read our documentation on How to OAuth with Lightspeed Retail (X-Series).
For help with requesting register info, see our REST API Reference for the /registers endpoint.

Step by Step

Merchant starts pairing flow.
Your service requests OAuth access to the Merchant's Lightspeed Retail (X-Series) account.
Merchant allows OAuth access.
Present a field asking for Terminal Serial Number or asking for Terminal Pairing Code (Recommended: you can display the pairing code on the device being paired).
The pairing code entered should match what the device is showing.
Present a dropdown list of Register Name choices which you retrieve from the REST API.
Store the association between the chosen register and the terminal that was identified.
You are now ready to receive payments from that register.

Where to Pair

You may notice from official payment integrations, that there is a "Configure your X Account with Lightspeed Retail (X-Series)" button in the Edit Payment page, which launches a modal and takes the user through the pairing flow.

This is reserved for preferred payment integrations, meaning that your pairing flow would need to exist outside of Lightspeed Retail (X-Series), or as a first step BEFORE payments can be taken on the sell page.

If you include the pairing option in the transact screens, then it's possible to instruct users to do their register pairing from within the modal that opens on the Pay screen.

However, if you are at this stage, and what is more, reading through the documentation, we probably want to chat about the possibility of including your flow in-app.
Email [email protected] and let us know what you're working on.

Routing Payments

To recap, by this point you have:

A web service that is able to talk to your payment terminals
A flow for getting approved OAuth to a Lightspeed Retail (X-Series) store
A database in which to store RegisterUUID<->TerminalSN pairings
Some method of allowing the user to choose which Register to associate a terminal SN to

As we know from DATA Step in the Payments API, we have access to the register_id which has sent a payment request to our gateway.
Abridged Payload from the DATA step:

{
    "success": true,
    "step": "DATA",
    "register_sale": {...},
    "payment": {
        "register_id": "0800278f-358c-11e6-fcf3-9005a15d99d9",
        "amount": "8.00"
    }
}

We can, therefore, look up that UUID in our database and find the associated terminal SN to route the payment to.

If you receive multiple requests, you should have multiple different UUIDs to respond to.