Payments API - Reference

Overview

Lightspeed Retail (X-Series)'s Payments API utilises the HTML5 postMessage() API to
allow interactions with the Lightspeed Retail (X-Series) Sell Screen at the point of sale.

Integrators can manipulate the current sale and control its flow, by using options like approve, decline and print.

NOTE: Complete custom gateway sample project available here

Messaging

Messages are expected to be sent and received as JSON-encoded strings.

Sending

Sending messages are done by calling postMessage() on the parent window.

var message = JSON.stringify({
    "step": "DATA"
});

window.parent.postMessage(message, "https://<domain_prefix>.vendhq.com");

Note that you will need to provide the store address for the origin argument.
An origin GET parameter is added to your gateway URL, so you should be able to use window.location.search to find this value.

Response

The response payload when requesting the "DATA" step, as above, includes sales totals and the register_id so that the integrator can differentiate between multiple Lightspeed Retail (X-Series) registers. You can also use this ID to associate registers with payment terminals by serial number, for how to do this see the Pairing Flow Guide.

Example response payload:

{
    "success": true,
    "step": "DATA",
    "register_sale": {
        "id": "5194354d-9080-8dda-11e6-9660dfac7dce",
        "client_id": "web_register",
        "client_sale_id": "5194354d-9080-8dda-11e6-9660dfac7dce",
        "totals": {
            "total_tax": "3.16957",
            "total_price": "21.13043",
            "total_paid": "10.00",
            "total_to_pay": "24.30000"
        },
        "line_items": [
            {
                "product_id": "0800278f-358c-11e6-fcf3-9005a15efdc0",
                "name": "T-shirt",
                "quantity": "1",
                "sku": "10001",
                "unit_price": "23.47826",
                "unit_tax": "3.52174",
                "tax_id": "00000000-0002-0002-0002-000000000003",
                "tax_rate": "0.15000",
                "image_url": "https://vendimageuploadcdn.global.ssl.fastly.net/350,fit,q90/vend-images/product/original/9/a/9af1395fc088f1fc811e9314e701515123b9cc85.jpg",
                "discount": "3.00000"
            }
        ],
        "customer_id": "0800278f-358c-11e6-fcf3-9005a1e4b2b9",
        "discount": {
            "product_id": "0242ac11-0002-11e9-e08f-e02aaec1dbd3",
            "price": "2.34783",
            "tax": "0.35217",
            "tax_id": "0242ac12-0002-11e9-e8c4-6594948eac5c"
        }
    },
    "payment": {
        "amount": "14.30",
        "reference_id": "0f6799a5-3a64-a24f-11e9-e87ae63b0167",
        "register_id": "0800278f-358c-11e6-fcf3-9005a15d99d9"
    }
}

Types

Messages are JSON objects with one required field.

Required

Possible steps include:

Optional

Setup Options

Accept and Accept Signature Options

(*): required for partial approvals. In other cases, it is not technically required for backward compatibility reasons, but we strongly ask you to provide those values so any mismatch between the POS and your integration can be detected.

Example:

window.parent.postMessage(
'{
    "step": "SETUP",
    "setup": {
        "enable_close": false
    }
}'
, origin);

Receiving

Receiving messages is done by binding the message event on the child window
(your iFrame's window):

window.addEventListener(
  'message',
  function (event) {
    var data = JSON.parse(event.data)

    // ... handle the messages
  },
  false
)

Examples

For an example of how a gateway works on the Sell Screen, go to Setup > Payment Types, then add a payment type for "Other Payment Method" and set its gateway URL as https://vend-app-assets.s3.us-west-2.amazonaws.com/pay-example/index.html. You can then see example steps and data from the sell screen.

This will provide you with a page to test each of the messages. You can use
the source of this as a good starting point.

See also:

• Mozilla Developer Network - Window.postMessage
• David Walsh - HTML5's window.postMessage API