Payments API - Getting started

Overview

The aim of this guide is to provide a practical example of how to get your payment
integration ready for use with Lightspeed Retail (X-Series).

To use the payment API, your application will need to be set up as a payment
type in the retailer's Lightspeed Retail (X-Series) account. When a user is finished adding products to
a sale, they will click 'Pay', and then on the button for your integration to
take payment.

A modal/lightbox style window will appear containing an iFrame. In this
iFrame we will load the URL you specify (this is referred to as the
payment type's "Gateway URL"). Once your page is loaded into the iframe, you will be able to
communicate with the parent window (in this case the Lightspeed Retail (X-Series) Sell Screen) using
Window.postMessage(), documented here.

Find the API Reference docs here

Prerequisites

A Hosted Web Gateway (recommend AWS)
- HTTPS Only
- Failure Resilient
- High Availability
Familiarity with the postMessage() API
A Lightspeed Retail (X-Series) account to test with

In-App Experience

Your payment integration will look just as if it were a built-in payment method,
but when invoked will launch your service via an iFrame of your gateway URL.

Example

I create a public-facing payment gateway at https://mygateway.com which can communicate with
payment terminals directly.
In my Lightspeed Retail (X-Series) account I go to Setup -> Payment Types.

Choose Add Payment Type.

From the dropdown choose Credit Card and rename it to My Gateway -> Then Save.

Now Edit "My Gateway" -> enter https://mygateway.com (this is your actual gateway URL) in the Gateway (optional) field -> Save. The payment type is now configured to launch my custom payment gateway.

On the Sell screen choose to buy an item -> And press Pay.

Now click the payment button named My Gateway.

The gateway for that payment type is now requested and your gateway will show embedded in a modal.

How it Works

Three arguments are provided as query parameters to your gateway URL. These are the origin (Lightspeed Retail (X-Series) domain prefix, that looks like example.retail.lightspeed.app), the register_id which is the identifier for the current register, and the transaction amount.

Therefore a sale processed on example.retail.lightspeed.app for $50.25 would look like
this to your gateway:

GET https://mygateway.com?origin=example.retail.lightspeed.app&amount=50.25&register_id=0242ac12-0012-11e7-ec9f-809071f870b8

NOTE: You should not make any assumption on how many digits will be given as the amount. You code should be robust enough to handle either 10, 10.0 or 10.00 as the same $10 amount request.
The built-in JS method parseFloat, or any library dealing with floating point numbers appropriately, should be used and tested to cover all scenarios.

You then use the Window.postMessage() API, to handle that transaction.
More instructions on how can be found in the Payment API Reference.

Example Flow

RECEIVE FROM Lightspeed Retail (X-Series): A GET request with the payment amount and origin.
SEND TO Lightspeed Retail (X-Series): "DATA" step to get more sale info like register_id so I know which unique register this came from (the retailer could have multiple registers).
IDENTIFY TERMINAL: Use the register_id from the DATA step to match which terminal to send the payment to.
SEND TO TERMINAL: Payment sent, terminal checks with the processor, and my gateway gets a response of "ACCEPTED".
SEND TO Lightspeed Retail (X-Series): "ACCEPT" step.

Lightspeed Retail (X-Series) then completes the sale and prints a receipt with any receipt_html_extra you provide embedded in the receipt (this might be EMV data or the customer
receipt info).