At the beginning, each sale point receives a security key from Billon. The shared key is then used to secure every cashier management request.

A one-time code request (‘pinondemand’) is secured in the same way, but with the use of cashier password instead of sale point security key.

Every cashier management and ‘pinondemand’ request should contain a ‘Hash’ parameter, which is calculated as follows:

1. Concatenate all parameters of the request (other than the ‘Hash’ parameter) into one string. Sequence of parameters must be identical to the sequence described in this documentation.
2. Add sale point shared key to the end of the string (or cashier password in the case of a ‘pinondemand’ request).
3. Encode the string using the SHA-256 algorithm. The result must be a hex string.

Example 1.: creating a new cashier

Our sale point ID is 10023. We have recived the following shared key from Billon: 702465405e335d7b32716d325d

We send a request to http://devme.billon.tv:3600/request/moneykey/createCashier, in order to create a new cashier account:

All parameters are then concatenated in the correct sequence. Result:

2016061020103010023jannowak+48508088808AVZ5800000ul. Szeroka 587-100Toruń

The shared key is then added to the end of the above string:

2016061020103010023jannowak+48508088808AVZ5800000ul. Szeroka 587-100Toruń702465405e335d7b32716d325d

This results in the following SHA-256 hash:

b64b7083f788c408f298c4315a31c4ea3bd255de71ba1e719fa2f00c502fd194

The PC application then send a request complete with the ‘Hash’ parameter:

In case the ‘Hash’ parameter is incorrect, Billon API will return error 10.

If the request is correct, cashier account will be created and the new cashier will receive his or her password via SMS. (in test environment, every cashier password is set as 12345678)

Example 2.: one-time code request

Our sale point ID is 10023. Cashier password: Password123

Cashier would like to request a code for 40PLN. The PC application send the following request to http://devme.billon.tv:3600/request/moneykey/pinondemand

All parameters are then concatenated in the correct sequence. Result:

2016061020103010023jannowak1002340.00PLN

Cashier password is added to the end of the above string:

2016061020103010023jannowak1002340.00PLNPassword123

This results in the following SHA-256 hash:

1f5a884c282a6d1d6f3e66ae1d69efaa85863ea13cb7cf27e1595461d2098785

After adding the ‘Hash’ parameter, the request is ready to be sent to billon API:

In case a cashier with that login already exists, API will output error 11. If the ‘Hash’ parameter is incorrect, API will output error 12. 

API Billon responses

All responses from API Billon (excluding responses containing an error code) also have a ‘Hash’ parameter, calculated with the same shared key or cashier password. For security reason, our partners have the obligation to verify the ‘Hash’ parameter for every API Billon response that does not contain an error code.