Returned JSON
TRANSACTION ENDPOINT returnED JSON
The returned JSON represents the status of the last request and the current state of the transaction. Note that the returned JSON contains mixed string and number JSON values, and consists of the following three sections:
- status – value containing return Status
- message – value containing description of error if status was an error
- instance – value containing the instance id that handled the successful request (normally 0 to 9)
- transaction – object containing the full transaction
The transaction consists of the following sections:
- General Information – values containing transaction wide information
- attributes – object contains transaction attributes excluding hidden (#attrname) ones
- sundries – list of sundry objects containing information about sundries
- products – list of product objects containing information about products, and sub products
- payments – list of payments objects containing payment information.
RESPONSE - Status, message, instance values
The status determines the success or failure and state of the last request and have one of the following values
- OK (success)– the transaction request was successful, and the transaction is open for more operations. Note that it is possible to get an OK even if you have sent an ‘order’ section in the request, this just shows that the transaction is still open and available to the local tills for pickup payment.
- FINAL (success) – the transaction request was successful, and the transaction is complete and fully paid for. The transaction can no longer be modified, even at the local tills. The local tills will however be able to retrieve it for viewing.
- AUTH (error) – the API key did not match any of the known virtual till instances.
- EFinchcorpXXXXXXX – this is a handled error normally presented at the till, the displayable message is contained in the message value.
- EXXXXXX – this is an unhandled exception and should be reported to support, along with logs for the instance and the message returned.
The instance is a value from 0 to 9 and is generally used for finding errors, or tracking logs and other issues.
The message will contain the description of an error if it occurs, it will not exist if the operation was successful (OK/FINAL).
TRANSACTION – General information
The general information is several name/value pairs within the transaction object, they are:
- transactionid – the 9 character unique transaction ID for this transaction, this will be returned to allow you to access it for more updates, or to allow the customer to print it out for a local cashier to retrieve the order for pickup payment.
- timestamp – ISO formatted date/time of the transaction
- tableid – for non web use, this will return the table id for the transaction.
- value – the total value of the transaction products
- gst – the total GST included in the total value of the products.
TRANSACTION – ATTRIBUTES OBJECT
This contains a list of name/value pairs for all the transaction attributes in the transaction.
This might include a transaction name, or contact number or any other attribute you wish to store.
TRANSACTION – SUNDRIES LIST
The sundries list is a JSON array of sundries objects with the following name/value pairs:
- name – the name of the sundry.
- category – the type of sundry (cover, tip, surcharge)
- amount – the cost or value of the sundry
TRANSACTION – PAYMENTS LIST
The payments list is a JSON array of payment objects with the following name/value pairs:
- name – the name of the payment
- method – the kind of payment, this corresponds to the kind used in the input, and generally corresponds to a payment gateway name (of CASH Vendor type) on the live tills.
- amount – the amount of the payment
- comments – any comments added to the payment
TRANSACTION – PRODUCTS LIST
The payments list is a JSON array of product objects with the following name/value (and one name/list pair:
- id – the product id of the product
- name – the name of the product
- qty – the quantity of product in this line item (note the same product id can appear in different product objects within the same transaction)
- price – the price per item for the product
- value – the value of the entire line item including discounts etc.
- gst – the GST included in the value of this item.
- comments – any comments added for this item (currently is a comma separated list of sub items)
- subs – a list sub items owned by this product, each sub item is an object with the same name/value pairs as for the product object (excluding gst and comments). Note that the product ID of a sub item may just be the name of the sub item, and that a sub item may have no price or value associated with it (e.g cooking instruction).
A sample of a product object:
{
"name": "HAMBURGER",
"id": "28002",
"qty": 1,
"price": 20.7,
"value": 20.7,
"gst": 1.8818,
"comments": "No Beetroot, Extra Cheese $2.00",
"subs": [
{
"id": "123",
"name": "Extra Cheese",
"qty": 1,
"price": 2,
"value": 2
},
{
"id": "No Beetroot",
"name": "No Beetroot",
"qty": 1
}
]
}
FULL SAMPLE SUCCESSFUL RESPONSE
{
"instance": "2",
"status": "FINAL",
"transaction": {
"transactionId": "A4EA3L6AE",
"timestamp": "2020-02-23T23:23:32.587+10:00",
"tableId": 0,
"items": [
{
"name": "HAMBURGER",
"id": "28002",
"qty": 1,
"price": 20.7,
"value": 20.7,
"gst": 1.8818,
"comments": "No Beetroot, Extra Cheese $2.00",
"subs": [
{
"id": "123",
"name": "Extra Cheese",
"qty": 1,
"price": 2,
"value": 2
},
{
"id": "No Beetroot",
"name": "No Beetroot",
"qty": 1
}
]
},
{
"name": "STEAK SANDWICH",
"id": "28004",
"qty": 1,
"price": 2,
"value": 2,
"gst": 0.1818
}
],
"sundries": [
{
"name": "Customer Tip",
"category": "Sundry",
"amount": 2.5
},
{
"name": "Surcharge",
"category": "Sundry",
"amount": 5
}
],
"value": 30.2,
"gst": 2.5181,
"payments": [
{
"name": "Paid CASH",
"method": "CASH Receipt",
"amount": 30.2,
"comments": "Online Payment"
}
],
"attributes": {
"PHONE": "(07) 4454 1231",
"NAME": "Freddy Mercury",
"TYPE": "delivery"
}
}
}