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:

.. code-block:: json

  {
    "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-block:: json

  {
    "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-block:: json

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

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

.. code-block:: json

  {
    "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.

  .. code-block:: text

    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:

.. code-block:: json

  {
    "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.

  .. code-block:: text

    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.

.. include:: credit_token/post_parameters.rst

Example request body:

.. code-block:: json

  {
    "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.

.. include:: credit_token/post_parameters.rst

Example request body:

.. code-block:: json

  {
    "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.

.. include:: credit_token/post_parameters.rst

Example request body:

.. code-block:: json

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