NAV Navbar
cURL
  • Introduction
  • URLs
  • Method Override
  • Authentication
  • Ping
  • Customers
  • Transactions
  • Reports
  • Types
  • Errors
  • Introduction

    Welcome to the LOKE POS API! You can use our API to enable your POS (or similar) system to accept in-store mobile payments.

    URLs

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

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

    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

    To authorize add the X-Api-Token or Authorization: Bearer header:

    # With shell, you can just pass the correct header with each request
    curl "http://api_endpoint_here"
      -H "Authorization: Bearer mytoken"
    
    curl "http://api_endpoint_here"
      -H "X-Api-Token: mytoken"
    

    Make sure to replace mytoken with your API key.

    The LOKE POS API uses tokens to allow access to the API. Soon you will be able to create tokens at our partner portal. In the meantime please request tokens from the LOKE team.

    The POS API expects for the token to be included in all API requests to the server in a header that looks like the following:

    X-Api-Token: mytoken

    This token is linked to a specific merchant account. Any requests for transactions and the like will be automatically filtered for that merchant.

    Ping

    Check Connectivity/Token

    curl "https://pos-api.au.loke.global/v4/ping"
      -H "X-Api-Token: mytoken"
    

    The above command returns JSON structured like this:

    "pong"
    

    You can check validity of a token, and/or connectivity to the API by making a GET request to the ping endpoint.

    HTTP Request

    GET https://pos-api.au.loke.global/v4/ping

    Returns: pong.

    Response Codes:

    Customers

    Get Available Customers

    curl "https://pos-api.au.loke.global/v4/customers"
      -H "X-Api-Token: mytoken"
    

    The above command returns JSON structured like this:

    [
      {
        "customerId": "507f1f77bcf86cd799439011",
        "firstName": "John",
        "lastName": "Smith",
        "gender": "male",
        "dob": "1980-03-03T00:06:14.088Z",
        "memberLevel": "Silver",
        "memberNo": "M1234",
        "photo": "http://someurl/photo.jpg",
        "checkInId": "507f191e810c19729de860ea",
        "checkInNumber": "123",
        "checkInDate": "2015-03-03T00:06:14.088Z"
      }
    ]
    

    Returns all available customers for the merchant.

    HTTP Request

    GET https://pos-api.au.loke.global/v4/customers

    Returns: an array of type Customer.

    Response Codes:

    Transactions

    Creating a Transaction

    NOTE: creating a transaction may take up to 30 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.

    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 30 seconds.

    curl "https://pos-api.au.loke.global/v4/transactions"
      -H "X-Api-Token: mytoken"
      -H "Content-Type: application/json"
      -x POST
      --data '{"refId":"INV0001", "terminalId":"TERM15", "customer":{"checkInId":"507f1f77bcf86cd799439011"}, "chargeAmount":1100, "itemTotal":1100, "itemTax":100, "total":1100, "tax":100, "balance":1100, "items":[{"name":"Beer","quantity":1,"amount":1100,"tax":100}]}'
    

    The above command returns JSON structured like this:

    {
      "transactionId": "d6ad656c-6580-4303-9802-1139ee7e9201",
      "refId": "INV0001",
      "terminalId": "TERM15",
      "customer": {
        "customerId": "507f1f77bcf86cd799439011",
        "firstName": "John",
        "lastName": "Smith",
        "gender": "male",
        "memberLevel": "Silver",
        "memberNo": "M1234",
        "photo": "http://someurl/photo.jpg",
        "checkInId": "507f191e810c19729de860ea",
        "checkInNumber": "AC123"
      },
      "state": "authorized",
      "itemTotal": 1100,
      "itemTax": 100,
      "discountTotal": 0,
      "discountTax": 0,
      "total": 1100,
      "tax": 100,
      "tipAmount": 0,
      "balance": 1100,
      "modifiedAmount": 0,
      "chargeAmount": 1100,
      "chargedAmount": 0,
      "feeAmount": 17,
      "created": "2015-03-03T00:06:14.088Z",
      "updated": "2015-03-03T00:06:14.088Z",
      "completed": null,
      "items": [
        {"name":"Beer", "quantity":1, "amount":1100, "tax":100}
      ],
      "discounts": [],
      "adjustments": [],
      "payments": [],
      "modifiers": []
    }
    

    This endpoint starts a new transaction.

    HTTP Request

    POST https://pos-api.au.loke.global/v4/transactions

    Accepts: application/json containing an object of type TransactionRequest

    Returns: the full details of the transaction as a Transaction

    Response Codes:

    Getting A Transaction

    curl "https://pos-api.au.loke.global/v4/transactions/d6ad656c-6580-4303-9802-1139ee7e9201"
      -H "X-Api-Token: mytoken"
    

    The above command returns JSON structured like this:

    {
      "transactionId": "d6ad656c-6580-4303-9802-1139ee7e9201",
      "refId": "INV0001",
      "terminalId": "TERM15",
      "customer": {
        "customerId": "507f1f77bcf86cd799439011",
        "firstName": "John",
        "lastName": "Smith",
        "gender": "male",
        "memberLevel": "Silver",
        "memberNo": "M1234",
        "photo": "http://someurl/photo.jpg",
        "checkInId": "507f191e810c19729de860ea",
        "checkInNumber": "AC123"
      },
      "state": "canceled",
      "itemTotal": 1100,
      "itemTax": 100,
      "discountTotal": 0,
      "discountTax": 0,
      "total": 1100,
      "tax": 100,
      "tipAmount": 0,
      "balance": 1100,
      "modifiedAmount": 0,
      "chargeAmount": 1100,
      "chargedAmount": 0,
      "feeAmount": 17,
      "created": "2015-03-03T00:06:14.088Z",
      "updated": "2015-03-03T00:06:14.088Z",
      "completed": null,
      "items": [
        {"name":"Beer", "quantity":1, "amount":1100, "tax":100}
      ],
      "discounts": [],
      "payments": [],
      "modifiers": []
    }
    

    This endpoint gets past transactions.

    HTTP Request

    GET https://pos-api.au.loke.global/v4/transactions?from={from}&to={to}

    Returns: the full details of the transaction as a Transaction type.

    Query Parameters:

    Parameter Description
    from The timestamp to search from (>=)
    to The timestamp to search to (<)
    terminalId Limits to transactions at this terminal

    Response Codes:

    This endpoint gets an existing transaction.

    HTTP Request

    GET https://pos-api.au.loke.global/v4/transactions/{id}

    URL Parameters:

    Parameter Description
    id The ID of the transaction to change

    Returns: the full details of the transaction as a Transaction type.

    Response Codes:

    Complete or Cancel A Transaction

    NOTE: if attempting to complete or cancel a transaction that is already completed/canceled 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. If you cancel a transaction no further changes can be made.

    curl "https://pos-api.au.loke.global/v4/transactions/d6ad656c-6580-4303-9802-1139ee7e9201"
      -X PATCH
      -H "X-Api-Token: mytoken"
      -H "Content-Type: application/json"
      --data '{"state":"canceled"}'
    

    The above command returns JSON structured like this:

    {
      "transactionId": "d6ad656c-6580-4303-9802-1139ee7e9201",
      "refId": "INV0001",
      "terminalId": "TERM15",
      "customer": {
        "customerId": "507f1f77bcf86cd799439011",
        "firstName": "John",
        "lastName": "Smith",
        "gender": "male",
        "memberLevel": "Silver",
        "memberNo": "M1234",
        "photo": "http://someurl/photo.jpg",
        "checkInId": "507f191e810c19729de860ea",
        "checkInNumber": "AC123"
      },
      "state": "canceled",
      "itemTotal": 1100,
      "itemTax": 100,
      "discountTotal": 0,
      "discountTax": 0,
      "total": 1100,
      "tax": 100,
      "tipAmount": 0,
      "balance": 1100,
      "modifiedAmount": 0,
      "chargeAmount": 1100,
      "chargedAmount": 0,
      "feeAmount": 17,
      "created": "2015-03-03T00:06:14.088Z",
      "updated": "2015-03-03T00:06:14.088Z",
      "completed": null,
      "items": [
        {"name":"Beer", "quantity":1, "amount":1100, "tax":100}
      ],
      "discounts": [],
      "payments": [],
      "modifiers": []
    }
    

    This endpoint changes the state of an existing transaction.

    HTTP Request

    PATCH https://pos-api.au.loke.global/v4/transactions/{id}

    URL Parameters:

    Parameter Description
    id The ID of the transaction to change

    Accepts: application/json containing the changed details of the transaction as a TransactionPatch

    Returns: the updated details of the transaction as a Transaction type.

    Response Codes:

    Refunding a Transaction

    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.

    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.

    Reports

    Getting Reports

    curl "https://pos-api.au.loke.global/v4/reports?from=2015-03-02T00:06:14Z"
      -H "X-Api-Token: mytoken"
    

    The above command returns JSON structured like this:

    [
      {
        "terminalId": "TERM001",
        "total": 143060,
        "fees": 2154,
        "payout": 140906,
        "tips": 12000,
        "count": 50,
        "from": "2015-03-02T00:06:14Z",
        "to": "2015-03-03T00:06:14Z"
      }
    ]
    

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

    HTTP Request

    GET https://pos-api.au.loke.global/v4/reports?from={from}&to={to}&terminalId={terminalId}?merge={merge}

    Query Parameters:

    Parameter Type Description
    from Date limit to transactions since this date-time. Values should be specified in ISO 1601 UTC.
    to Date [optional] limit to transactions up to this date-time. Values should be specified in ISO 1601 UTC.
    terminalId String [optional] limit the ID of the transaction
    merge Boolean [optional] 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.

    Returns: an array of summary Report (typically one for each registered terminal, unless merge is specified)

    Response Codes:

    Types

    Error

    Example JSON

    {
      "error": true,
      "code": 123,
      "message": "An application error occurred",
      "type": "ApplicationError"
    }
    

    Fields

    Field Type Notes
    error Boolean always true
    code Integer application error code. NOTE: this can be different from the HTTP status code.
    message String Description of the error
    type String The error type name

    Customer

    Example JSON

    {
      "customerId": "507f1f77bcf86cd799439011 ",
      "firstName": "John",
      "lastName": "Smith",
      "gender": "male",
      "memberLevel": "Silver",
      "memberNo": "M1234",
      "photo": "http://someurl/photo.jpg",
      "checkInId": "507f191e810c19729de860ea",
      "checkInNumber": "AC123",
      "checkInDate": "2015-03-03T00:06:14.088Z"
    }
    

    Fields

    Field Type Notes
    customerId String The customer's unique ID
    firstName String the customer's given name or first name
    lastName String the customer's surname or last name
    gender String enum of male,female,unknown
    dob Date The customer's date of birth
    memberLevel String(50) the Aston Club member level (silver, gold, platinum). Should be displayed to the operator.
    memberNo String(50) if this customer is linked to a loyalty provider, this will be the loyalty member number, else undefined.
    photo String(512) contains URL to profile photo.
    checkInId String This ID is unique for all customer checkins in the system, but is not displayed on the customer's phone.
    checkInNumber String(6) This ID is unique for all currently active customers at a merchant, and is displayed on the customers phone and can be used for verification. The format can be customised per merchant, but is typically a 3 digit number, can also have a letter prefix.
    checkInDate Date Timestamp for when this customer checked in
    notes String(100) notes on this customer

    TransactionRequest

    Example JSON

    {
      "refId": "INV0001",
      "terminalId": "TERM15",
      "customer": { "checkInId": "507f1f77bcf86cd799439011" },
      "chargeAmount": 1100,
      "itemTotal": 1100,
      "itemTax": 100,
      "total": 1100,
      "tax": 100,
      "balance": 1100,
      "items": [
        {"name":"Beer", "quantity":1, "amount":1100, "tax":100}
      ]
    }
    

    Fields

    Field Type Notes
    refId String A reference ID to attach to the transaction. Typically this should be an invoice ID or check ID from the POS system.
    terminalId String A string ID that uniquely identifies the terminal (or station) making this transaction. Used for reporting so that transactions can be grouped per terminal.
    customer Customer The customer to be charged. NOTE: the only field that must be provided is checkInId. All other fields can be either supplied or omitted, but will be ignored.
    chargeAmount Integer The amount that Aston Club should charge the customer for this transaction in cents. NOTE: at present Aston Club only supports charging for the balance - all other payment methods (eg: cash) must take place prior to charging with Aston Club. As such chargeAmount must equal balance.
    itemTotal Integer 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 The sum of the tax for all items in cents. NOTE: this must match the actual sum of item taxes.
    itemTax Integer The sum of the tax for all items in cents. NOTE: this must match the actual sum of item taxes.
    discountTotal Integer The sum of all discounts applied to this transaction in cents inclusive of tax. If omitted it is assumed to be $0. NOTE: this must match the actual sum of discount totals.
    discountTax Integer 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 Integer The actual total (ie: itemTotal - discountTotal) in cents inclusive of tax.
    tax Integer The actual tax (ie: itemTax - discountTax) in cents.
    balance Integer The balance the user has yet to pay for, ie: total - sum(payments). NOTE: at present Aston Club only supports charging for the balance - all other payment methods (eg: cash) must take place prior to charging with Aston Club. As such balance must equal chargeAmount.
    items Array<Item> 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.
    discounts Array<Discount> 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.
    payments Array<Payment> 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.

    Transaction

    Example JSON

    
    {
      "transactionId": "d6ad656c-6580-4303-9802-1139ee7e9201",
      "refId": "INV0001",
      "terminalId": "TERM15",
      "customer": {
        "customerId": "507f1f77bcf86cd799439011",
        "firstName": "John",
        "lastName": "Smith",
        "gender": "male",
        "memberLevel": "Silver",
        "photo": "http://someurl/photo.jpg",
        "checkInId": "507f191e810c19729de860ea",
        "checkInNumber": "AC123"
      },
      "state": "authorized",
      "itemTotal": 1100,
      "itemTax": 100,
      "discountTotal": 0,
      "discountTax": 0,
      "total": 1100,
      "tax": 100,
      "tipAmount": 0,
      "balance": 1100,
      "modifiedAmount": 0,
      "chargeAmount": 1100,
      "chargedAmount": 0,
      "feeAmount": 17,
      "created": "2015-03-03T00:06:14.088Z",
      "updated": "2015-03-03T00:06:14.088Z",
      "completed": null,
      "items": [
        {"id": "123", name":"Beer", "quantity":1, "amount":1100, "tax":100}
      ],
      "discounts": [],
      "adjustments": [],
      "payments": [],
      "modifiers": []
    }
    

    Fields

    All currency filds are provided in cents as Integers.

    Field Type Notes
    transactionId String A unique ID for the transaction
    refId String A reference ID supplied by the POS system. Typically this should be an invoice ID or check ID.
    terminalId String A string ID that uniquely identifies the terminal that made this transaction making this transaction. Supplied by the POS system.
    customer Customer The customer being charged.
    state String enum of authorized,complete,canceled,refunded,rejected
    created Date Timestamp for when this transaction was created.
    updated Date Timestamp for when this transaction was last updated.
    completed Date will be null if the transaction state is authorized. For tranasctions that have been refunded this will be the timestamp of when the transaction was completed. updated will be changed when the transaction is refunded.
    itemTotal Integer The sum of all item amounts (inclusive of taxes).
    itemTax Integer The sum of all item taxes.
    discountTotal Integer The sum of all discounts supplied by the POS system (incusive of taxes).
    discountTax Integer The sum of all discount taxes supplied by the POS system.
    total Integer itemTotal - discountTotal.
    tax Integer itemTax - discountTax.
    tipAmount Integer Any tip amount provided by the customer.
    chargeAmount Integer The amount the POS has requested Aston Club to charge the customer.
    balance Integer Will be 0 if state is complete (ie: fully paid), otherwise the remainder to be paid on this invoice.
    modifiedAmount Integer If the customer has available perks (eg: member discount) then this will be non-zero to indicate the variance, eg: a customer has a 10% member discount, when chargeAmount:1000 is requested, modifiedAmount will be -100. If the transaction is completed then the customer will be charged chargeAmount + modifiedAmount. The details of any modifiers applied will be available in the modifiers field.
    chargedAmount Integer Will be 0 unless the transaction is complete. If complete then this will equal the amount the customer was actually charged. See modifiedAmount and tipAmount above.
    feeAmount Integer The fee charged by Aston Club for this transaction. Aston Club will fund the merchant chargedAmount - feeAmount for this transaction.
    items Array<Item> 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.
    discounts Array A list of all discounts applied to the transaction as provided by the POS system.
    adjustments Array A list of all adjustments applied to the transaction as provided by the POS system. Adjustments are items that do not fit into discounts or other items such as surcharges.
    payments Array list of payments made on this transaction. Contains any pre-payments supplied by the POS system. If complete then it will also contain the Aston Club payment.
    modifiers Array the details of any modifiers applied by Aston Club. Typically these represent things such as member discounts, but can also be promotions or other targeted discounts.

    TransactionPatch

    Example JSON

    {
      "state": "canceled"
    }
    

    Fields

    Field Type Notes
    state String enum of canceled,complete,refunded

    Item

    Example JSON for 2xBeers with a unit price of $11.00

    {
      "id": "123",
      "name": "Beer",
      "quantity": 2,
      "amount": 2200,
      "tax": 200
    }
    

    Fields

    Field Type Notes
    id String (Optional/preferred) Unique ID of the product
    name String Descriptive name for this item line
    quantity Integer The quantity of items included in this line. NOTE: if this is >1 then it will be prefixed to the item list on the customer's phone. eg: name:"Beer", quantity:2 will be represented as "2x Beer"
    amount Integer The total amount (inclusive of tax) of this line item in cents. This should be the total amount for all items, not the per-item price, eg: name:"Beer", quantity:2, amount:2000 would represent the purchase of 2 beers @ $10 per beer. This would be displayed to the customer as "2x Beer -- $20.00"
    tax Integer The total tax included in amount for this line item in cents. As per amount, this should be the total amount for all items.

    Discount

    Example JSON

    {
      "id": "D0023"
      "name": "10% Off",
      "amount": -220,
      "tax": -20
    }
    

    Fields

    Field Type Notes
    id String (Optional) Unique ID of the discount
    name String Descriptive name for this discount
    amount Integer The total amount (inclusive of tax) of this discount. If the discount is a percentage discount then this should contain the resulting variance. Should always be negative.
    tax Integer The total tax included in amount. Should always be negative.

    Payment

    Example JSON

    {
      "method": "Cash",
      "amount": 1000
    }
    
    {
      "method": "AstonClub",
      "amount": 5000
    }
    

    Fields

    Field Type Notes
    method String Name for this payment method. NOTE: AstonClub is reserved and payments of this type cannot be added from the POS system.
    amount Integer The total amount paid using this method. Number should always be positive. Negative payment amounts are not supported.

    Modifier

    Example JSON

    {
      "name": "Member Discount",
      "id": "507c7f79bcf86cd7994f6c0e",
      "amount": -110,
      "tax": -10
    }
    

    Modifiers are similar to discounts, except that they are applied on by Aston Club, whereas discounts are applied by the POS.

    Fields

    Field Type Notes
    name String Descriptive name for this modifier
    amount Integer The total amount (inclusive of tax) of this modifer. Modifiers are Aston Club specific discounts, and will be negative.
    tax Integer The total tax included in amount.

    Report

    Example JSON

    {
      "terminalId": "TERM001",
      "total": 143060,
      "fees": 2154,
      "payout": 140906,
      "tips": 12000,
      "credits": 56,
      "count": 50,
      "from": "2015-03-02T00:06:14Z",
      "to": "2015-03-03T00:06:14Z"
    }
    

    TODO: needs to be reviewed

    Fields

    All currency amounts are represented in cents as Integers.

    Field Type Notes
    terminalId String The ID of the terminal this report data applies to
    total Integer The total amount processed (inclusive of tips and tax)
    fees Integer The total fees that will be deducted
    payout Integer total - fees is the amount that the merchant will be paid out
    tips Integer The amount of tips that were included in total
    count Integer The number of transactions that are included in this report set
    from Date The ISO date-time that transactions are included from
    to Date The ISO date-time that transactions are included to

    Errors

    In the event of an API error (4xx or 5xx status code), the body of the response will contain the details of the error in an Error type.

    The API uses the following error codes:

    Error Code Meaning
    400 Bad Request -- Could not process your request, probably due to a validation error
    401 Unauthorized -- Your API key is wrong
    403 Forbidden -- You cannot access this resource
    404 Not Found -- The specified entity or resource could not be found
    406 Not Acceptable -- Check your "Accept" headers - we only accept JSON at the moment
    410 Gone -- The resource has been deleted
    429 Too Many Requests -- You're making too many requests! Slown down!
    500 Internal Server Error -- We had a problem with our server. Try again later or contact our support.
    503 Service Unavailable -- We're temporarially offline for maintanance. Please try again later.