Transactions

POS clients can record transactions using this API. The client must use the TAG algorithm to generate the barcode for each delegate.

All the codes for a specific purchase should follow the following convention:

• Purchase Code: a barcode’s base;

• Purchase Item Code: the Purchase Code + a zero padded incremental counter starting from zero (0000, 0001, … 9999);

• Delegate Barcode: a barcode generated using TAG algorithm and the purchase code as base.

The reference implementation of the barcode generation algorithm is written in PHP, but we also have a JavaScript implementation.

A transaction recorded through a POS device should always be accepted by the system because once such transaction is confirmed in the real world that means a customer somewhere is walking around with tickets or a receipt that must be loaded into the system. For this reason, while the system will try and load all the information as correctly as it can, it will still trust the device and store the data anyway, even if some inconsistencies are detected.

POST /tx/new

A transaction is composed of global fields and transaction items.

The request should hold the following parameters:

• context The device ID all products are joined to, usually it’s an event device;

• code The Purchase Code, see introduction;

• totalAmount The total amount (in cents of a dollar);

• notes Any note entered by the staff member handling the transaction;

• createdAt The timestamp of the purchase, as an Unix timestamp, in seconds;

• recordedBy The staff member recording this transaction;

• transactions The list of individual money transactions logged for this purchase, which should add up to the totalAmount specified above. Each one should have:

  • paymentMethod Can be “cash” or “card”;

  • amount The amount paid using this method (in cents of a dollar);

  • change The change given back to the customer (in cents of a dollar). This is only valid if the payment method is “cash”;

  • transactionId The identifier of the transaction. This could be the identifier returned by the card reader or gateway used to execute the transfer of money;

• items The list of items purchased in this transaction. Each item should have:

  • code The Purchase Item Code, see introduction;

  • product The device ID of the product sold;

  • quantity The quantity sold. Should always be greater than zero;

  • description The description for this line item. Usually this is the product name;

  • unitAmount The price for an individual unit (in cents of a dollar);

  • totalAmount The total for this line item (in cents of a dollar). Usually this is just quantity times the unit amount;

  • discountAmount Total discount applied to this line item (in cents of a dollar);

  • delegates The list of delegates to create for this line item. Each delegate should have the following properties:

    • product The device ID of the product joined to this delegate (commonly called ticket). Usually this matches the product of the line item, but could be different for example if a product purchased has “sub-products”. For example a family pass provides two adult tickets and three children. In this case each unit of this line item will have 5 associated delegates, two of them with the adult product ID and three of them with the child product ID;

    • description The description of this delegate. Usually this is the product label;

    • barcode The barcode associated to this delegate. This must be generated using the barcode generation algorithm.

Below is a payload example:

• the customer has bought a total of $24 worth of tickets

  • 3 adult tickets for $4 each for a total of $12

  • 1 family pass for $12

• they paid $4 cash using a $5 note, $20 dollar using a debit card, and received $1 change

• the staff member “Richard M” who was handling the transaction wrote a note about it

{
  "context": 1,
  "code": "GJXS0LM6RYG40",
  "totalAmount": 2400,
  "notes": "Customer is paying the $4 in cash because of low balance",
  "createdAt": 1768268326,
  "recordedBy": "Richard M",
  "transactions": [
    {
      "paymentMethod": "cash",
      "amount": 400,
      "change": 100
    },
    {
      "paymentMethod": "card",
      "transactionId": "ch_3SnT0BCpzQXiFwJY0rQJrzWE",
      "amount": 2000
    }
  ],
  "items": [
    {
      "product": 2,
      "code": "GJXS0LM6RYG400000",
      "quantity": 3,
      "description": "Adult",
      "unitAmount": 400,
      "totalAmount": 1200,
      "discountAmount": null,
      "delegates": [
        {
          "product": 4,
          "description": "Adult",
          "barcode": "GJXS0LM6RYG40XJX01"
        },
        {
          "product": 4,
          "description": "Adult",
          "barcode": "GJXS0LM6RYG40XJX02"
        },
        {
          "product": 4,
          "description": "Adult",
          "barcode": "GJXS0LM6RYG40XJX03"
        }

      ]
    },
    {
      "product": 3,
      "code": "GJXS0LM6RYG400001",
      "quantity": 1,
      "description": "Family Pass",
      "unitAmount": 1200,
      "totalAmount": 1200,
      "discountAmount": null,
      "delegates": [
        {
          "product": 8,
          "description": "Adult",
          "barcode": "GJXS0LM6RYG40XJX04"
        },
        {
          "product": 8,
          "description": "Adult",
          "barcode": "GJXS0LM6RYG40XJX05"
        },
        {
          "product": 9,
          "description": "Child",
          "barcode": "GJXS0LM6RYG40XJX06"
        },
        {
          "product": 9,
          "description": "Child",
          "barcode": "GJXS0LM6RYG40XJX07"
        },
        {
          "product": 9,
          "description": "Child",
          "barcode": "GJXS0LM6RYG40XJX08"
        }
      ]
    }
  ]
}