Documentation Powered by ReDoc

Point-of-Sale HTTP API (4.0.0)

Download OpenAPI specification:Download

Introduction

The LOKE POS API enable your POS (or similar) system to accept in-store / at-counter payments from LOKE mobile applications.

Note that the API was originally built for quite a different system (not a loyalty platform). As such some of the field names may need some explaining.

itemTotal should be the sum of the items on the bill. This should be straightforward enough.

total should generally always be the same as itemTotal unless there was some sort of discount applied by the point-of-sale, eg if they had a “50% Staff Discount” applied then itemTotal might be £20 and total £10.

chargeAmount should be whatever is provided by the point of sale and is the amount that LOKE will use to deduct credit, discounts, and payments from the user. Typically you would pass the same value for chargeAmount as total unless there have been cash payments already made at the point of sale.

chargedAmount is not set by the point-of-sale, but returned by LOKE to indicate the amount that the customer was charged (ie from their credit card). If a customer has no loyalty benefits then this will typically just be the same as chargeAmount. But if a customer has a 10% VIP discount with the app then a chargeAmount of £20 will result in a chargedAmount of £18.

There is also modifiedAmount which is essentially chargedAmount - chargeAmount. This will be non-zero if some form or loyalty has been used to fulfill the payment.

URLs

Production

Note: the global URL uses IP-based DNS routing to connect to the closest servers. Requests are then proxied on to the applicable servers using the access token. Under certain circumstances (eg cloud POS systems) this might not work as expected causing very slow API requests. In these situations please specify the regional URL directly. You may wish to provide a configuration field to manually enter the URL or region in use.

Global https://pos-api.loke.global/v4

Australia / New Zealand: https://pos-api.au.loke.global/v4

Singapore: https://pos-api.sg.loke.global/v4

UK: https://pos-api.uk.loke.global/v4

Development

The development environments allow you to use fake/test credit cards to develop against.

Sandbox: https://pos-api.sbox.loke.global/v4

Method Override

If your client does not support the required HTTP verbs in order to interract with this REST API it is possible to use the method override header technique.

Instead of making a PATCH or DELETE request, make a POST request and include in the X-HTTP-Method-Override HTTP header, eg: X-HTTP-Method-Override: PATCH

Authentication

Access tokens are obtained from LOKE Auth, either manually created, or created via device code authentication (OAuth 2).

To authenticate/authorize your API requests, use the bearer token in the Authorization header of all your requests:

GET /v4/customers HTTP/1.1
Host: posapi.au.loke.global
Accept: application/json
Authorization: Bearer VZGkBG39rdCfzB4XH8pXxp4H
Cache-Control: no-cache

Legacy: the API still supports the X-Api-Token header, but this is not the recommended approach.

*Note: access tokens are linked to a specific merchant account. Any requests for transactions and the like will be automatically filtered for the context of that merchant.*

For more information on device code authentication please contact LOKE support.

Status

Tests connectivity and token validity

This endpoint is used to verify the API is contactable and that the access token sent is active and valid.

Responses

Response samples

Content type
application/json
"pong"

Customers

Get available (checked-in) customers

This endpoint is used to identify the customers that are available to charge. Customers are typically available when they have "checked in" for payments at the current merchant.

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Transactions

Get existing transactions

Get the full details of existing transactions

query Parameters
from
required
string <date-time>

limit to transactions since this date-time.

Values should be specified in ISO 8601 UTC.

to
required
string <date-time>

limit to transactions up to this date-time.

Values should be specified in ISO 8601 UTC.

terminalId
string

Limit the results to transactions made by a specific terminal.

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Initiate a new transaction against a customer

Initiates a new transaction. The customer must be checked in to succeed.

Notes

  • Unless this transaction is marked as complete by a subsequent PATCH request it will be refunded.
  • The checkInId is the only required customer field on the request object.
  • Creating a transaction may take up to 60 seconds if the customer is prompted to confirm.
  • Both failed and rejected transactions return an error response.
  • You can test for error responses by creating a transaction for the amount of $2000.00 - $2077.99 (this is a feature of the Braintree sandbox)
  • The ability for a customer to accept/reject a transaction is not yet released. The only thing that needs to be done in order to support this when released is ensure any timeouts defined on the POS side for this request are greater than 60 seconds.
Request Body schema: application/json
pointsEarned
integer <int32>

Points earned on this transaction. DO NOT PROVIDE IF YOU DO NOT HAVE A USE CASE FOR THIS - if not provided will be auto-calculated. NOTE that under certain circumstances rules may prevent this from being the actual amount of points applied.

refId
string Nullable

A reference ID to attach to the transaction. Typically this should be an invoice ID or check ID from the POS system.

terminalId
string Nullable

A string ID that uniquely identifies the terminal (or station) making this transaction. Used for reporting so that transactions can be grouped per terminal.

chargeAmount
required
integer <int32>

The amount that LOKE should charge the customer for this transaction in cents. NOTE: at present LOKE only supports charging for the balance - all other payment methods (eg: cash) must take place prior to charging with LOKE. As such chargeAmount must equal balance.

itemTotal
required
integer <int32>

The sum of the totals for all items in cents inclusive of tax. NOTE: this must match the actual sum of item totals.

itemTax
integer <int32> Nullable

NOTE: not used where tax invoices are not issues from the app (recommended to not issue). The sum of the tax for all items in cents. NOTE: this must match the actual sum of item taxes.

discountTotal
integer <int32> Nullable

The sum of all discounts applied BY THE POINT OF SALE to this transaction in cents inclusive of tax and should be a negative number. If omitted it is assumed to be $0. NOTE: this should match the actual sum of discount totals to avoid unexpected behaviour.

discountTax
integer <int32> Nullable

NOTE: not used where tax invoices are not issues from the app (recommended to not issue). The sum of all discounts applied to this transaction in cents. If omitted it is assumed to be $0. NOTE: this must match the actual sum of discount taxes.

total
required
integer <int32>

The actual total (ie: itemTotal + discountTotal, where `discountTotal is a negative number) in cents inclusive of tax.

tax
integer <int32> Nullable

NOTE: not used where tax invoices are not issues from the app (recommended to not issue). The actual tax (ie: itemTax - discountTax) in cents.

balance
required
integer <int32>

The balance the user has yet to pay for, ie: total - sum(payments). NOTE: at present LOKE only supports charging for the balance - all other payment methods (eg: cash) must take place prior to charging with LOKE. As such balance must equal chargeAmount.

required
object (Customer)
required
Array of objects (TransactionItem)

A list of all items the customer is being charged for. NOTE: there must be at least 1 item provided, and the sums must match itemTotal and itemTax.

Array of objects (TransactionDiscount)

A list of all discounts applied to the transaction. If no discounts are applied this can be omitted. If discounts are applied, the sums must atch discountTotal and discountTax.

Array of objects (TransactionPayment)

A list of payments already made on this check or transaction. If no other payments have been made this can be omitted. NOTE: if omitted then balance must equal total. If included then balance should equal total minus the sum of payments.

Responses

Request samples

Content type
application/json
{
  • "pointsEarned": 500,
  • "refId": "ORDER1234",
  • "terminalId": "TERM0001",
  • "chargeAmount": 1100,
  • "itemTotal": 0,
  • "itemTax": 0,
  • "discountTotal": 0,
  • "discountTax": 0,
  • "total": 0,
  • "tax": 0,
  • "balance": 0,
  • "customer":
    {
    },
  • "items":
    [
    ],
  • "discounts":
    [
    ],
  • "payments":
    [
    ]
}

Response samples

Content type
application/json
{
  • "state": "authorized"
}

Update the state of an existing transaction

Updates the state of an existing transaction.

Completing

A transaction must be completed to finalise the charge. You can only set the state of an authorized transaction to completed.

NOTE: If attempting to complete a transaction that is already completed, the request will succeed but no additional state changes will take place.

WARNING: changing the state of a transaction cannot be undone. If you complete a transaction the customer will be charged, however it is possible to refund a completed transaction before it is processed.

Cancelling

A transaction that has been authorized but not yet set to complete can be cancelled. You can only set the state of an authorized transaction to cancel.

If a transaction is left in the authorized state for the defined interval it will automatically be cancelled, however we recommend manually doing this if possible as it ensures the customers funds and credit are returned in a timely manner.

NOTE: If attempting to cancel a transaction that is already cancelled, the request will succeed but no additional state changes will take place.

WARNING: changing the state of a transaction cannot be undone. If you cancel a transaction no further changes can be made.

Refunding

The process for refunding a transaction is identical to cancelling or completing a transaction (you simply edit the state of a transaction) except that it will only work on transactions that have been completed.

NOTE: If attempting to refund a transaction that is already refunded, the request will succeed however the customer will not be refunded twice. The transaction will only ever be refunded when the state actually changes to refunded.

WARNING: Refunding a transaction cannot be undone. If you complete a transaction the customer will be charged, however it is possible to refund a completed transaction before it is processed. If you cancel a transaction no further changes can be made.

path Parameters
transactionId
required
string

Unique ID of the transaction.

Note - current IDs are UUID, however the format of these IDs is not guaranteed. You should always use strings on the client.

Request Body schema: application/json
state
string
Enum: "canceled" "complete" "refunded"

Desired state of the transaction

Responses

Request samples

Content type
application/json
{
  • "state": "canceled"
}

Response samples

Content type
application/json
application/json
example
{
  • "refId": "ORDER1234",
  • "terminalId": "TERM0001",
  • "chargeAmount": 1100,
  • "itemTotal": 0,
  • "itemTax": 0,
  • "discountTotal": 0,
  • "discountTax": 0,
  • "total": 0,
  • "tax": 0,
  • "balance": 0,
  • "customer":
    {
    },
  • "items":
    [
    ],
  • "discounts":
    [
    ],
  • "payments":
    [
    ],
  • "state": "authorized",
  • "transactionId": "d6ad656c-6580-4303-9802-1139ee7e9201",
  • "created": "2015-03-03T00:06:14.088Z",
  • "updated": "2015-03-03T00:06:14.088Z",
  • "completed": "2015-03-03T00:06:14.088Z",
  • "tipAmount": 0,
  • "modifiedAmount": -110,
  • "chargedAmount": 0,
  • "feeAmount": 0,
  • "modifiers":
    [
    ]
}

Get the details of an existing transaction

Get the full details of an existing transaction

path Parameters
transactionId
required
string

Unique ID of the transaction.

Note - current IDs are UUID, however the format of these IDs is not guaranteed. You should always use strings on the client.

Responses

Response samples

Content type
application/json
{
  • "refId": "ORDER1234",
  • "terminalId": "TERM0001",
  • "chargeAmount": 1100,
  • "itemTotal": 0,
  • "itemTax": 0,
  • "discountTotal": 0,
  • "discountTax": 0,
  • "total": 0,
  • "tax": 0,
  • "balance": 0,
  • "customer":
    {
    },
  • "items":
    [
    ],
  • "discounts":
    [
    ],
  • "payments":
    [
    ],
  • "state": "authorized",
  • "transactionId": "d6ad656c-6580-4303-9802-1139ee7e9201",
  • "created": "2015-03-03T00:06:14.088Z",
  • "updated": "2015-03-03T00:06:14.088Z",
  • "completed": "2015-03-03T00:06:14.088Z",
  • "tipAmount": 0,
  • "modifiedAmount": -110,
  • "chargedAmount": 0,
  • "feeAmount": 0,
  • "modifiers":
    [
    ]
}

Reporting

Transaction summary/report data.

This endpoint gets transactional summary/report data for the authenticated merchant matching the query parameters.

Notes

By default this groups summary data by terminal ID and returns as an array. Use merge if you don't want this behaviour.

query Parameters
from
required
string <date-time>

limit to transactions since this date-time.

Values should be specified in ISO 8601 UTC.

to
string <date-time>

limit to transactions up to this date-time.

Values should be specified in ISO 8601 UTC.

terminalId
string

Limit the results to transactions made by a specific terminal.

merge
boolean

if true then all transactions will be merged into a single summary. Useful for generating a report for the entire venue, rather than broken down by terminals.

Note - this changes the response format to an object instead of an array.

Responses

Response samples

Content type
application/json
[
  • {
    }
]