Credit Token¶

Credit tokens are expendable units that delegates can use to get goods and services at a live event. Every delegate can have multiple accounts against them. Adding and subtracting tokens from a delegate’s account will work only after an account has been initialised.

The default account name is default, unless you are required to use a different account.

Each account can handle a specific token type. A token type specifies some basic information like:

the actual type of the tokens, can be either token or currency
upper and lower bounds for each account, if reached the API will return an error
symbol, name and description
if that particular token type is active or inactive (unused at the moment)

The default token type is default, unless you are required to use a different type.

Successful Response¶

The response will always look like the example below. Only the request to get the history of transactions will add another property called history to the payload.

The HTTP status code will always be 200 OK for GET requests or 201 Created for POST requests, unless an error occurs.

Example response:

{
  "balance": -20,
  "delegate": {
    "data": [],
    "flags": [],
    "barcode": "130102568017",
    "id": 1,
    "sources": [
      "admin"
    ],
    "createdAt": "2017-12-05T04:27:18+00:00",
    "updatedAt": "2017-12-05T04:27:18+00:00"
  },
  "transaction": {
    "createdAt": "2017-12-05T20:29:38+00:00",
    "operation": "subtract",
    "amount": 5,
    "balance": -20,
    "source": "Insomnia Test",
    "description": "A test",
    "accountName": "default",
    "tokenType": {
      "name": "default"
    }
  }
}

Error Responses¶

If there’s any issue while logging or retrieving transactions the server will return a 409 Conflict response. A specific error code will be returned as follow:

Error	Code	Thrown when…
ACCOUNT_ALREADY_INITIALISED	1051	Trying to initialise an already initialised account.
BALANCE_MISMATCH	1052	The balance could not be calculated correctly.
BALANCE_OUT_OF_BOUND	1053	The balance is out of bounds but it cannot be determined if too low or high.
BALANCE_OUT_OF_UPPER_BOUND	1054	Registering the transaction will cause the balance to become too high.
BALANCE_OUT_OF_LOWER_BOUND	1055	Registering the transaction will cause the balance to become too low.
DUPLICATE_TRANSACTION	1056	The transaction looks like a duplicate of an already recorded one.
ACCOUNT_NOT_AVAILABLE	1057	The account you are trying to manipulate has not been initialised yet.
TRANSACTION_REJECTED	1058	The transaction gets rejected for an unknown reason.

Example of a 409 Conflict response:

{
  "code": 409,
  "message": "Account already initialised",
  "errorCode": 1051
}

Other common response errors could be:

400 Bad Request if something is wrong with your request, like a required field is missing or a valus is invalid
401 Unauthorized if your token has expired or you did not provide one
404 Not Found if a delegate, account, token type is not found

Example of a 404 Not Found response:

{
  "code": 404,
  "message": "Not Found",
  "errorCode": 0
}

Example of a 400 Bad Request response (the amount has not been sent):

{
  "code": 400,
  "message": "Validation Failed",
  "errors": {
    "children": {
      "delegate_id": {},
      "delegate_rfid": {},
      "delegate_barcode": {},
      "delegate_externalId": {},
      "device_id": {},
      "device_code": {},
      "operation": {},
      "amount": {
        "errors": [
          "This value should not be blank."
        ]
      },
      "source": {},
      "description": {},
      "recordedAt": {},
      "accountName": {},
      "tokenType": {},
      "rounding": {},
      "balanceExpected": {}
    }
  }
}

GET /credit-token/balance/{accountName}/{idType}:{id}¶

Gets a delegate balance for a specific account. The response will also show the last transaction recorded by that delegate.

Note

If more than one account exists against different token type you can pass the token type name as a query parameter in your request like shown below. Note that the requests in the example target two completely different accounts.

GET /credit-token/balance/default/id:123.json?tokenType=default
GET /credit-token/balance/default/id:123.json?tokenType=another

GET /credit-token/history/{accountName}/{idType}:{id}¶

Gets the delegate’s history of transactions for a specific account.

Example response:

{
  "delegate": {
    "data": [],
    "flags": [],
    "barcode": "130102568017",
    "id": 1,
    "sources": [
      "admin"
    ],
    "createdAt": "2017-12-05T04:27:18+00:00",
    "updatedAt": "2017-12-05T04:27:18+00:00"
  },
  "transaction": {
    "createdAt": "2017-12-05T20:25:45+00:00",
    "operation": "add",
    "amount": 5,
    "balance": 15,
    "source": "Insomnia Test",
    "description": "A test",
    "accountName": "default",
    "tokenType": {
      "name": "default"
    }
  },
  "history": [
    {
      "createdAt": "2017-12-05T20:25:45+00:00",
      "operation": "add",
      "amount": 5,
      "balance": 15,
      "source": "Insomnia Test",
      "description": "A test",
      "accountName": "default",
      "tokenType": {
        "name": "default"
      }
    },
    {
      "createdAt": "2017-12-05T20:18:21+00:00",
      "operation": "add",
      "amount": 5,
      "balance": 10,
      "source": "Insomnia Test",
      "description": "A test",
      "accountName": "default",
      "tokenType": {
        "name": "default"
      }
    },
    {
      "createdAt": "2017-12-05T20:15:36+00:00",
      "operation": "init",
      "amount": 5,
      "balance": 5,
      "source": "Insomnia Test",
      "description": "A test",
      "accountName": "default",
      "tokenType": {
        "name": "default"
      }
    }
  ],
  "balance": 15
}

Note

This method does not implement pagination yet, don’t use it as a replacement to get just the delegate’s balance.

Note

If more than one account exists against different token type you can pass the token type name as a query parameter in your request like shown below. Note that the requests in the example target two completely different accounts.

GET /credit-token/history/default/id:123.json?tokenType=default
GET /credit-token/history/default/id:123.json?tokenType=another

POST /credit-token/transaction/init¶

Initialises a delegate’s account by setting an initial balance.

Request Parameter	Req.	Type	Description
delegate_{idType}	Yes	string	A delegate’s identifier, can be id, rfid, barcode or externalId.
amount	Yes	float	The amount of tokens.
source	Yes	string	The source of the transaction, should be client/device specific.
description	Yes	string	The complete description of the transaction, can be up to 8KB.
recordedAt	Yes	int	The Unix timestamp of when the transaction happened on the client.
accountName	No	string	The account name, defaults to “default”.
tokenType	No	string	The token type name, defaults to “default”.
rounding	No	string	The rounding to apply if needed, can be “round” (default), “floor” or “ceil”.
balanceExpected	No	float	The client calculated balance if the transaction gets recorded.
device_{idType}	No	string	If the transaction is related to a device (session, sponsor, others) this should be set. You can use id or code to identify the device.

Example request body:

{
  "delegate_id": 1,
  "amount": 5,
  "source": "Insomnia Test",
  "description": "User account initialisation: balance=5",
  "recordedAt": 1512516382
}

POST /credit-token/transaction/add¶

Adds tokens to a delegate’s account.

Request Parameter	Req.	Type	Description
delegate_{idType}	Yes	string	A delegate’s identifier, can be id, rfid, barcode or externalId.
amount	Yes	float	The amount of tokens.
source	Yes	string	The source of the transaction, should be client/device specific.
description	Yes	string	The complete description of the transaction, can be up to 8KB.
recordedAt	Yes	int	The Unix timestamp of when the transaction happened on the client.
accountName	No	string	The account name, defaults to “default”.
tokenType	No	string	The token type name, defaults to “default”.
rounding	No	string	The rounding to apply if needed, can be “round” (default), “floor” or “ceil”.
balanceExpected	No	float	The client calculated balance if the transaction gets recorded.
device_{idType}	No	string	If the transaction is related to a device (session, sponsor, others) this should be set. You can use id or code to identify the device.

Example request body:

{
  "delegate_id": 1,
  "amount": 5,
  "source": "Insomnia Test",
  "description": "User competition win: Competition#123, Pick a winner, prize=5",
  "recordedAt": 1512516382
}

POST /credit-token/transaction/subtract¶

Subtracts tokens from a delegate’s account.

Request Parameter	Req.	Type	Description
delegate_{idType}	Yes	string	A delegate’s identifier, can be id, rfid, barcode or externalId.
amount	Yes	float	The amount of tokens.
source	Yes	string	The source of the transaction, should be client/device specific.
description	Yes	string	The complete description of the transaction, can be up to 8KB.
recordedAt	Yes	int	The Unix timestamp of when the transaction happened on the client.
accountName	No	string	The account name, defaults to “default”.
tokenType	No	string	The token type name, defaults to “default”.
rounding	No	string	The rounding to apply if needed, can be “round” (default), “floor” or “ceil”.
balanceExpected	No	float	The client calculated balance if the transaction gets recorded.
device_{idType}	No	string	If the transaction is related to a device (session, sponsor, others) this should be set. You can use id or code to identify the device.

Example request body:

{
  "delegate_id": 1,
  "amount": 5,
  "source": "Insomnia Test",
  "description": "User direct redemption: Product#123, Laptop fan, cost=5",
  "recordedAt": 1512516382
}