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:

 

Parameter	Data type	Value
Timestamp	String	20160610201030
Sale_Point_ID	String	10023
Cashier_First_Name	String	jan
Cashier_Last_Name	String	nowak
Cashier_Telephone_No	String	+48508088808
Cashier_Document_ID	String	AVZ5800000
Cashier_Address_1	String	ul. Szeroka 5
Cashier_Address_2	String
Postal_Code	String	87-100
City	String	Toruń

 

 

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:

Parameter	Data type	Value
Timestamp	String	20160610201030
Sale_Point_ID	String	10023
Cashier_First_Name	String	jan
Cashier_Last_Name	String	nowak
Cashier_Telephone_No	String	+48508088808
Cashier_Document_ID	String	AVZ5800000
Cashier_Address_1	String	ul. Szeroka 5
Cashier_Address_2	String
Postal_Code	String	87-100
City	String	Toruń
Hash	String	b64b7083f788c408f298c4315a31c4ea3bd255de71ba1e719fa2f00c502fd194

 

 

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

 

Parameter	Data type	Value
Timestamp	String	20160610201030
Sale_Point_ID	String	10023
Cashier_Login	String	jannowak10023
Amount	String	40.00
Currency	String	PLN

 

 

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:

Parameter	Data type	Value
Timestamp	String	20160610201030
Sale_Point_ID	String	10023
Cashier_Login	String	jannowak10023
Amount	String	40.00
Currency	String	PLN
Hash	String	1f5a884c282a6d1d6f3e66ae1d69efaa85863ea13cb7cf27e1595461d2098785

 

 

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.