1. Home
  2. Web services
  3. One-time codes
  4. Security

Security

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. 

Was this article helpful to you? Yes No

How can we help?