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
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.
- 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
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.
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.
Three arguments are provided as query parameters to your gateway URL. These are the
origin (Lightspeed Retail (X-Series) domain prefix, that looks like xxxx.vendhq.com), the
register_id which is the identifier for hte current register, and the transaction
Therefore a sale processed on myvendstore.vendhq.com for $50.25 would look like
this to your gateway:
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.
- 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_idso I know which unique register this came from (the retailer could have multiple registers).
- IDENTIFY TERMINAL: Use the
register_idfrom 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
Updated 3 months ago