Reference

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

KeyTypeRequiredDescription
stepstringrequiredThe step in the transaction process to enact.
successbooleanoptionalDEPRECATED: Whether the step is considered successful.

Possible steps include:

StepDescriptionAction
DATARequest additional information from Lightspeed Retail (X-Series) about the current transaction.Sale JSON Sent.
SETUPThe enable_close bool can be sent to toggle the modal close button.
PRINTYou may also add content to the receipt with the receipt_html_extra field.Launches print dialogue.
ACCEPT_SIGNATUREIt will print a signature slip receipt. You may add content to the receipt with the external_transaction_id, card_last_four, payment_date, terminal_serial_number, signature_url and signature_base64 fields. If printing is enabled an approved transaction receipt will also print.Launches print dialogue and complete sale.
ACCEPTIf printing is enabled an approved transaction receipt will also print.Complete sale.
DECLINEIf printing is enabled a declined transaction receipt will also print.Return to pay screen.
EXITDoes not close the window but closes all other dialogues and unbinds postMessage handling.Clean exit.

Optional

KeyTypeRequiredDescription
receipt_html_extrastringoptionalAny text (HTML) you would like added to the receipt.
printbooleanoptionalWhether to print a receipt for this step. Ignored if the step is already set to PRINT.
copy_textstringoptionalThe merchant or customer copy label on receipts (defaults to "Customer Copy")
setupobjectoptionalSettings for the Payment dialogue.

Setup Options

KeyTypeRequiredDescription
enable_closebooleanoptionalShow or hide the close button and bar.

Accept and Accept Signature Options

KeyTypeRequiredDescription
external_transaction_idstring (36)optionalThe transaction identifier from the integrator's system.
reference_idstring (36)optionalA unique identifier that can be used to control repeat actions, such as preventing double charges (idempotency).
merchant_idstring (36)optionalThe merchant identifier from the integrator system.
terminal_serial_numberstring (36)optionalThe serial number of the payment terminal.
terminal_modelstring (36)optionalThe model of the payment terminal.
entry_methodstringoptionalEnum: SWIPED, KEYED, CONTACTLESS, CHIP, FALLBACK
card_brandstringoptionalEnum: OTHER, VISA, MASTERCARD, AMERICAN_EXPRESS, DISCOVER, DISCOVER_DINERS, JCB, CHINA_UNIONPAY, EBT, ENROUTE, INTERAC, VOYAGER, WEX
card_typestringoptionalEnum: CREDIT, DEBIT
card_last_fourstringoptionalThe last 4 digits of the card number.
emv_aidstring (16)optionalEMV application identifier
emv_application_labelstring (16)optionalEMV application label
emv_cryptogram_typestringoptionalEnum: AAC, ARQC and TC
emv_cryptogramstringoptionalCryptogram returned by the ICC
emv_pin_verifiedbooleanoptionalTo signify if a PIN was used as the verification method for the payment.
emv_tags[object]optionalAdditional EMV tags which are required on receipt. Each element is a key/value JSON object. e.g. [{ "key" : "4F", "value" : "A0000000000000" }, { "key" : "95", "value" : "0000000000" }]
signature_urlstring(200)optionalThe digital signature image as a public URL.
signature_base64stringoptionalThe signature image (PNG format) as a Base64 string. If signature_url has been provided, signature_base64 will be ignored.
approved_amountnumberoptionalThe value of approved amount. Required for partial approval.
amountnumberoptionalThe value of request amount. Required for partial approval.
messagestringoptionalThe reason for the partial approval. e.g. "Partial approval due to insufficient funds."

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.

image

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.

image

See also: