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.
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
Key | Type | Required | Description |
---|---|---|---|
step | string | required | The step in the transaction process to enact. |
success | boolean | optional | DEPRECATED: Whether the step is considered successful. |
Possible steps include:
Step | Description | Action |
---|---|---|
DATA | Request additional information from Lightspeed Retail (X-Series) about the current transaction. | Sale JSON Sent. |
SETUP | The enable_close bool can be sent to toggle the modal close button. | |
PRINT | You may also add content to the receipt with the receipt_html_extra field. | Launches print dialogue. |
ACCEPT_SIGNATURE | It 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. |
ACCEPT | If printing is enabled an approved transaction receipt will also print. | Complete sale. |
DECLINE | If printing is enabled a declined transaction receipt will also print. | Return to pay screen. |
EXIT | Does not close the window but closes all other dialogues and unbinds postMessage handling. | Clean exit. |
Optional
Key | Type | Required | Description |
---|---|---|---|
receipt_html_extra | string | optional | Any text (HTML) you would like added to the receipt. |
print | boolean | optional | Whether to print a receipt for this step. Ignored if the step is already set to PRINT. |
copy_text | string | optional | The merchant or customer copy label on receipts (defaults to "Customer Copy") |
setup | object | optional | Settings for the Payment dialogue. |
Setup Options
Key | Type | Required | Description |
---|---|---|---|
enable_close | boolean | optional | Show or hide the close button and bar. |
Accept and Accept Signature Options
Key | Type | Required | Description |
---|---|---|---|
external_transaction_id | string (36) | yes(*) | The transaction identifier from the integrator's system. It must be unique per merchant to track and reference individual transactions. |
reference_id | string (36) | The reference identifier from the integrator's system. | |
merchant_id | string (36) | The merchant identifier from the integrator system. | |
terminal_serial_number | string (36) | The serial number of the payment terminal. | |
terminal_model | string (36) | The model of the payment terminal. | |
entry_method | string | Enum: SWIPED , KEYED , CONTACTLESS , CHIP , FALLBACK | |
card_brand | string | Enum: OTHER , VISA , MASTERCARD , AMERICAN_EXPRESS , DISCOVER , DISCOVER_DINERS , JCB , CHINA_UNIONPAY , EBT , ENROUTE , INTERAC , VOYAGER , WEX | |
card_type | string | Enum: CREDIT , DEBIT | |
card_last_four | string | The last 4 digits of the card number. | |
emv_aid | string (16) | EMV application identifier | |
emv_application_label | string (16) | EMV application label | |
emv_cryptogram_type | string | Enum: AAC , ARQC and TC | |
emv_cryptogram | string | Cryptogram returned by the ICC | |
emv_pin_verified | boolean | To signify if a PIN was used as the verification method for the payment. | |
emv_tags | [object] | Additional 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_url | string(200) | The digital signature image as a public URL. | |
signature_base64 | string | The signature image (PNG format) as a Base64 string. If signature_url has been provided, signature_base64 will be ignored. | |
approved_amount | number | yes(*) | The approved amount. Required for partial approval. |
amount | number | yes(*) | The requested amount. Required for partial approval. |
message | string | The reason for the partial approval. e.g. "Partial approval due to insufficient funds." |
(*): 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:
Updated 10 days ago