Transaction Details

POST https://webhook.example.com

What subscriber endpoint implementation will receive when a transaction is made. Subscriber path need to end with /charge. 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 number

    The number of covers (guests) in this transaction.

  • ownerId integer(int64)

    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 integer(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 integer(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

      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 integer(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 integer(int64)

      Lightspeed accounting group id which the item belongs to.

    • groupName string

      Lightspeed accounting group name which the item belongs to.

    • taxId integer(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 array[object]
      Hide taxLines attributes Show taxLines attributes object
  • 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 integer(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

      The reservation ID of the payment.

  • 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.

  • 5XX application/json

    If any server error occurs subscriber can pass their own custom message to the POS. The response body content need to follow the schema, else only 5XX {Error Type} will be sent.

    Hide response attribute Show response attribute object
    • 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
    • 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 {subscriber-host}/charge
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 (5XX) 
{
  "customerErrorMessage": "Network failure"
}
Response examples (4XX) 
{
  "customerErrorMessage": "Network failure"
}