Transaction Details

POST https://webhook.example.com

What subscriber endpoint implementation will receive when a transaction is made. Subscriber implementation should follow the payload backward compatibility rules below:

What considered as backward compatible:
- Addition of new fields, enums, headers, or parameters.
- Transition from optional to required fields. Which means Lightspeed will consistently send the parameter/field from now on.
What considered as backward incompatible:
- Alteration of schema structure, such as switching from a map to an array.
- Removal of field/enum/header
- Changes in data types, such as converting from string to integer.
- Changes of property name

Headers

Accept string Required

The expected response content type from subscriber. Only application/json is supported.
X-Lightspeed-Idempotency-Key string Required

Subscribers should utilize the Idempotency Key to ensure duplicates are handled appropriately on their end.

application/json

Body Required

name string

Name of the transaction
openDate string(date-time)

The date and time when the transaction was opened in UTC
closeDate string(date-time)

The date and time when the transaction was closed in UTC
covers integer

The number of covers (guests) in this transaction.
ownerId string

The ID of the POS user (staff) who owns this transaction
ownerName string

The name of the POS user (staff) who owns this transaction
deviceId number(int64)

The ID of the device on which the transaction was started
businessExternalReference string

Client name
apiKey string

API Key.
receiptId string

Receipt ID
fiscId string

Unique identifier for the transaction, can be used this for any identification purposes.
uuid string

A b64 encoded uuid which also act as unique identifier for the transaction, also can be used for any identification purposes.
initialAccountId string

Initial Account ID, if any. This is used to correlate the transaction with the initial account, such on REFUND or VOID.
identifier string Deprecated

Refer to the non null value of either the fiscId or uuid as fallback.
revenueCenterId number(int64)

Revenue Center (POS Configuration) ID
revenueCenterName string

Revenue Center (POS Configuration) Name
transactions array[object]
Hide transactions attributes Show transactions attributes object
- unitAmount number
  
  The price of single item.
- quantity number Deprecated
  
  The quantity of the items. Negative quantity indicates a refund/cancellation/void.
- amount number
  
  The total pre-tax amount of this transaction sale line.
- description string
  
  The item name
- staffId number(int64)
  
  The ID of the POS user (staff) who processed this transaction line
- staffName string
  
  The name of the POS user (staff) who processed this transaction line
- groupId number(int64)
  
  Lightspeed accounting group id which the item belongs to.
- groupName string
  
  Lightspeed accounting group name which the item belongs to.
- taxId number(int64) Deprecated
  
  Deprecated, refer to taxLines.
- taxName string Deprecated
  
  Deprecated, refer to taxLines.
- taxRate number Deprecated
  
  The tax rate of the items.
- taxIncluded boolean Deprecated
  
  Deprecated, refer to taxLines.
- sku string
  
  The SKU of the items.
- type string
  
  The type of the transaction line.
  
  Values are Sale, LineDiscount, AccountDiscount, or PercentItem.
- serviceChargeContribution number
  
  The amount of the service charge contribution.
- taxLines object
  Hide taxLines attributes Show taxLines attributes object
  
  taxId string
  
  The tax identifier.
  
  taxName string
  
  The name of the tax.
  
  taxAmount number
  
  The amount of the tax.
  
  taxRate number
  
  The rate of the tax.
  
  taxIncluded boolean
  
  Whether the tax is included in the price (VAT).
payments array[object]
Hide payments attributes Show payments attributes object
- paymentDate string(date-time)
  
  The date and time when the payment was made in UTC
- staffId number(int64)
  
  The ID of the POS user (staff) who processed this payment
- staffName string
  
  The name of the POS user (staff) who processed this payment
- gratuity number
  
  The amount of the gratuity (tips).
- amount number
  
  The total amount of the received payment.
- methodName string
  
  The name of the payment method.
- methodCode string
  
  The code of the payment method.
- reservationId string Deprecated
  
  The reservation ID of the payment. At block this is the authCode.
serviceCharge object
Hide serviceCharge attributes Show serviceCharge attributes object
- amount number
  
  The amount of the service charge.
- type string
  
  The type of the service charge.
  
  Values are UNTAXED or APPORTIONED.

Responses

200

Subscriber should return this code if it successfully processed the charge request at PMS. Following that, Lightspeed will mark the PMS charge transaction as SUCCESS as well.
500 application/json

If an Internal Server Error occurs subscriber can pass their own custom message to the POS. The response body content need to follow the schema, else only 500 Internal Server Error will be sent.
Hide response attribute Show response attribute object
The error response body content should follow this schema. If the response body content does not follow this schema, only the status code will be sent. All other property beside customerErrorMessage will be ignored.
- customerErrorMessage string
  
  The error message that will be sent and printed at the POS. Length should not exceed 50 characters to avoid truncation.
  
  Maximum length is 50.
4XX application/json

If any client error occurs subscriber can pass their own custom message to the POS. The response body content need to follow the schema, else only 4XX {Error Type} will be sent.
Hide response attribute Show response attribute object
The error response body content should follow this schema. If the response body content does not follow this schema, only the status code will be sent. All other property beside customerErrorMessage will be ignored.
- customerErrorMessage string
  
  The error message that will be sent and printed at the POS. Length should not exceed 50 characters to avoid truncation.
  
  Maximum length is 50.

POST Charge Transaction

Request examples

# Headers
Accept: application/json
X-Lightspeed-Idempotency-Key: LS1_123e4567-e89b-12d3-a456-426614174000

# Payload
{
  "name": "string",
  "openDate": "2021-01-01T00:00:00Z",
  "closeDate": "2021-01-01T00:00:00Z",
  "covers": 2,
  "ownerId": "12345",
  "ownerName": "John Doe",
  "deviceId": 12345,
  "businessExternalReference": "quickbooks-123",
  "apiKey": "quickbooks-key-345",
  "receiptId": "R51.3",
  "fiscId": "A1234.5",
  "uuid": "xfe9ldKWSfW8VrAYUcnvGA==",
  "initialAccountId": "A1234.1",
  "identifier": "A1234.5",
  "revenueCenterId": 94489280528,
  "revenueCenterName": "Fixed POS",
  "transactions": [
    {
      "unitAmount": 10.0,
      "quantity": 2.0,
      "amount": 20.0,
      "description": "French Fries",
      "staffId": 6,
      "staffName": "John Doe",
      "groupId": 25769803810,
      "groupName": "Food",
      "taxId": 12345,
      "taxName": "VAT 10%",
      "taxRate": 1.1,
      "taxIncluded": true,
      "sku": "F07",
      "type": "Sale",
      "serviceChargeContribution": 4.5,
      "taxLines": {
        "taxId": "12345",
        "taxName": "VAT 10%",
        "taxAmount": 1.0,
        "taxRate": 1.1,
        "taxIncluded": true
      }
    }
  ],
  "payments": [
    {
      "paymentDate": "2021-01-01T00:00:00Z",
      "staffId": 6,
      "staffName": "John Doe",
      "gratuity": 1.0,
      "amount": 66.0,
      "methodName": "MEWS",
      "methodCode": "IKPMS",
      "reservationId": "001"
    }
  ],
  "serviceCharge": {
    "amount": 1.0,
    "type": "UNTAXED"
  }
}

Response examples (500)

{
  "customerErrorMessage": "Network failure"
}

Response examples (4XX)

{
  "customerErrorMessage": "Network failure"
}