Transaction end point – httpS://<server>/TRANSACTION,POST

The transaction end point requires JSON input and returns JSON output. The JSON input determines the exact functions performed by iCell as a Service. This end point is provided by ICAAS. Note – all values are stored as JSON strings.

The JSON input is a JSON Object with several ‘sections’ containing a name/object or name/list pair and one containing just a name/value pair.

The following sections are supported by the Transaction end point input JSON:

  • login – identifies an object with login information to allow access to the API
  • transactionid – identifies a value of existing transaction ID, or sets a table number for a new one.
  • customer – identifies an object with loyalty or account information for a in shop customer.
  • products – identifies a list of products to add
  • extras – identifies an object with extras (covers, sundries etc)
  • payments – identifies a list of payments that should be processed.
  • order – identifies an object with various order settings, and initiates the processing of the transaction.

The above represents the order in which the sections are processed, independent of the JSON order.

Each section is described blow in detail:

Transaction Id Value

The transaction ID value has two purposes:

  • To specify a table number for a new transaction. This is only supported for tablet Apps, and not for web ordering.
  • To specify a table number or a valid nine character transaction ID to continue on a previous transaction.

For example – to retrieve an existing transaction you could have:

"transactionid": "A2B9GA6CP"

If you wish to create a new transaction on table 14, you would have

"transactionid": "14"

API KEY VALUE

  • apikey (required)  – a GUID (all caps, no braces) specifies the access key to the particular virtual till on the iCaaS service. A GUID will either match a till reserved for web user, or one used for tablet app use. This apikey will be provided by the operator of the store at which iCaaS is running, and is configured in icmsSettings.

"apikey": "04A7E88F-0933-4295-AA02-34A79472BB2C",

LOGIN OBJECT

The login object is only required for tablet use, web access does not require it.

  • cashier – for tablet app use, specify the cashier login token
  • password – for tablet app use, specify the cashier login password (as per iCell usage)

The following is a sample of a login section object (for a tablet app):

"login": {
    "cashier": "123",  
    "password": "12345"
}

CUSTOMER OBJECT

If the store that iCell as a Service has loyalty or account customers, then you can use this section to register the customer so that the transaction will generate loyalty points for the transaction, award discounts and specials based on their membership. It does not allow the Web App to pay for orders via their account however.

The customer object has two name/value pairs:

  • id – the remote loyalty/member system’s account ID.
  • source – the payment gateway ID of the remote loyalty system, currently only supports the FINCHCORP vendor.

A sample of a customer section is as follows:

 "customer": {
    "id": "1001",
    "source": "ACCOUNT"
  }


PRODUCTS LIST

The products list is a JSON Array of product JSON Objects. There is no inherent limit in how many products can be added here, the same product can be added in different objects if required (if it has a different price, comments etc).

Each product object has the following attributes:

  • product (required) – the product id (from the catalog) of the product to be added.
  • quantity (required) – the quantity of the product to add
  • price – the price to sell the item for, will override the till price.
  • instructions – side items, or instructions (e.g. chips, cook rare etc) these are listed as sub items. These will generally be instructions to the kitchen (for prepared items). Instructions are a comma separated list of free text, free text with a $ amount, or a product id.
  • comments - comments to add to the product. These will generally be to the customer and/or cashier.

Sample products section.

“products": [
    {
       "product" : "28002",
       "quantity" : "4",
       "comment" : "Chef's Special",
       "instructions" : "Extra Ice $2, Lemon, 1001"
    },
    {
       "product" : "28004",
       "quantity" : "4",
       "price" : "12.45"
    }
]


EXTRAS OBJECT

The extras object contains three name/value pairs:

  • tip – determines the amount added as a tip
  • surcharge – determines the amount added for a surcharge (e.g. holiday surcharge)
  • covers – the number of covers included.

"extras": {
    "tip": "2.5",
    "surcharge": "5",
    "covers": "2"
}


PAYMENTS LIST

The payments list is a JSON array containing JSON objects each representing a payment. Generally speaking one payment is all that is required, but any number of payments can be supplied I the list.

The structure of each payment object is as follows:

  • kind – the name of the payment gateway to apply this as. As iCaaS doesn’t actually take payments via the web, the only iCell Vendor supported here is CASH, however multiple cash gateways can be set up with meaningful names (VISA etc).
  • amount – the amount of the payment being recorded,  or a question mark (?) to represent pay out the transaction.
  • comment – a comment to apply to the payment

Sample of a payments section:

"payments": [
  {
     "kind": "CASH",
     "amount": "?",
     "comment": "Online Payment"
  }
]



ORDER object

The order object serves two functions, to set various options and attributes on the transaction and signal the app or website is finished with the order. You should only include an order object if you do not intend to make any further modifications.

If the transaction is balanced (no money owing) then the transaction will finalised at the store, if not it will remain in the store system to be loaded by an in store till for paying the remaining money.

The name/value pairs for the order object are:

  • tag – tag the transaction file so it can easily be grouped with others of the same tag. A web order should use the tag “WEB” to allow in store iCell operators to see all the WEB orders.
  • receipt – if set to “yes” will print a copy of the transaction at the assigned receipt printer in store.
  • kitchen – if set to “yes’ will send a copy of the transaction to the kitchen printer or kitchen monitor.
  • <any name> - any other name here will be set as a transaction attribute with the same name/value.

Sample order section:

"order": {
  "tag" : "WEB",
  "name" : "Freddy Mercury",
  "phone" : "(07) 4454 1231",
  "receipt" : "yes",
  "kitchen" : "yes",
  "type":  "delivery"
}

A finalised transaction will return ‘FINAL’ in the status (see response section below), a transaction that is still requiring payment will return ‘OK’. If there are errors then the error code and message will be in the response.