.. _balance_checker:

===============
Balance Checker
===============

.. contents::
   :local:
   :depth: 3

Overview
--------

This web service allows the app to check account credit balance and display it to the user. Balance is shown on the
keypad screen.

Parameters
----------

Parameter templates for Balance Checker can use any variables from :ref:`global-params` and :ref:`account-params`
scopes. There are no service-specific parameters defined for balance checker.

Configuration
-------------

The following :ref:`account-xml` keys are relevant for balance checker configuration:

``genericBalanceCheckUrl``
~~~~~~~~~~~~~~~~~~~~~~~~~~

    Contains the URL, including URL scheme, of the web service, possibly also with query string.

    Example (with query-string):

    .. code-block:: xml

        <genericBalanceCheckUrl>https://example.com/balance/?username=%account[username]%</genericBalanceCheckUrl>

    Example (without query-string):

    .. code-block:: xml

        <genericBalanceCheckUrl>https://example.com/balance/%account[username]%</genericBalanceCheckUrl>

``genericBalanceCheckPostData``
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

    If filled in, the app will use POST request to check the balance.

    Example ( for  application/x-www-form-urlencoded):

    .. code-block:: xml

        username=%account[username]%

    Example ( for  application/json ):

    .. code-block:: json

        { "username" : "%account[username]%" }

``genericBalanceCheckContentType``
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

    Specifies the value of Content-Type header to be sent in the request. If not specified, the app will default to
    ``application/x-www-form-urlencoded``


``balanceCheckIntervalInSeconds``
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

    Specifies how often will the app check for balance updates. The default value is 300 (every 5 minutes).

    Example:

    .. code-block:: xml

        <balanceCheckIntervalInSeconds>180</balanceCheckIntervalInSeconds>

``balanceCheckDelayInSeconds``
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

    The app also checks for new balance when the call ends, because it's expected that the balance changes at that time
    and it's desired to refresh it asap.

    Some providers may need to delay this check, because the new balance needs some time to propagate through their
    backend. The default is 5 seconds.

    Example:

    .. code-block:: xml

        <balanceCheckDelayInSeconds>0</balanceCheckDelayInSeconds>

Response
--------

    The response will be considered successful if the HTTP response code is 2xx. Any responses which have other
    response code, or whose body can't be parsed, are silently ignored.

    ``Content-type`` header of the response specifies the format of the body. The following Content-Types are supported:

        - application/xml  (**default**)
        - application/json
        - application/x-www-form-urlencoded

    The following fields in the response are recognized:

``balanceString``
~~~~~~~~~~~~~~~~~
    This is the string which will be displayed as-is as a balance. The server needs to format this string to make it
    look pretty and follow the conventions for the given country and currency. It's recommended to keep the balance
    string short (under 10 characters)

    This field is mandatory.

``balance``
~~~~~~~~~~~
    Numerical representation of the balance. Parsed as a floating-point number.

    Optional and currently not used in the app

``currency``
~~~~~~~~~~~~
    Code of the currency in which the balance is expressed.

    Optional and currently not used in the app

Examples
--------

GET method, XML
~~~~~~~~~~~~~~~

request:

 .. code-block:: http

    GET /balance/?username=johndow&password=12345678 HTTP/1.1
    Host: example.com
    Connection: close
    Cache-Control: max-age=0
    User-Agent: CloudSoftphone/1.5.6


response:

 .. code-block:: http

    HTTP/1.1 200 OK
    Date: Sun, 15 Mar 2015 00:46:17 GMT
    Server: Apache/2.4.7 (Ubuntu)
    Vary: Accept-Encoding
    Content-Encoding: gzip
    Content-Length: 183
    Keep-Alive: timeout=5, max=100
    Connection: Keep-Alive
    Content-Type: text/xml

    <response>
        <balanceString>CHF 13.44</balanceString>
        <balance>13.44</balance>
        <currency>CHF</currency>
    </response>


GET method, JSON
~~~~~~~~~~~~~~~~

request:

 .. code-block:: http

    GET /balance/johndow/12345678 HTTP/1.1
    Host: example.com
    Connection: close
    Cache-Control: max-age=0
    User-Agent: CloudSoftphone/1.5.6


response:

 .. code-block:: http

    HTTP/1.1 200 OK
    Date: Sun, 15 Mar 2015 00:46:17 GMT
    Server: Apache/2.4.7 (Ubuntu)
    Vary: Accept-Encoding
    Content-Encoding: gzip
    Content-Length: 183
    Keep-Alive: timeout=5, max=100
    Connection: Keep-Alive
    Content-Type: application/json

    {
        "balanceString" : "CHF 13.44",
        "balance" : 13.44,
        "currency" : "CHF"
    }