A query purchaseCode serves to purchase the one-time code through transfer from buyer’s Corporate Node to an Corporate Node of service billon.io. Each transaction has to contain a comment with an unique identifier created using the following convention:
- beginning of identifier is ID of the outlet
- next character is separator: &
- the outlet add the unique identifier of transaction not longer than 24 characters after separator. The identifier must not include character &. A duty of the outlet is use of identifier, which has not been used in the past, in each query.
For example, an identifier for an outlet 1023 can look like this: 10023&A5C34E1FA44C12388B
The process of the purchase of the one-time code:
- The outlet tell Corporate Node transfer funds from application of service billon.io, providing the unique identifier in the comment
- When the transaction is successfully finished, the outlet sends query about the purchase of one-time code to Billon API (query purchaseCode)
- Billon API returns a one-time code or error code
HTTP request must be send by POST method to https://billon.io/moneykey/pinondemand
The query purchaseCode – the query about the one-time code
| Parameter | Data type | Description |
| Timestamp | String | GMT time of the request in YYYYMMDDhhmmss format – for example 20171031104530. API returns 13 in the event that given Timestamp has been already used. |
| Sale_Point_ID | String | ID of given sale point |
| Unique_ID | String | Unique ID from the comment of the transaction |
| Method | String | (optionally) HTTP or SMS. Choosing SMS method will make the one-time code sent via SMS to phone number given in a parameter Phone, and the one-time code will not be passed in HTTP response. |
| Phone | String | (optionaly) Phone number to which the one-time code is to be sent, if SMS method is chosen |
| Alert_Address | String | (optionally) Address (which starts with http:// or https://) to which immediate HTTP notification about one-time code to top up user’s application |
| Hash | String | See the article ‘Security’ for a description of method that calculates this amount. |
Response: the one-time code
| Parameter | Data type | Description |
| Code | String | The one-time code designed to top-up. The parameter is blank in the event of error. The parameter will have value ‘SMS’ in the event that SMS method was chosen. |
| Serial_No | String | A serial number of the one-time code |
| Amount | String | A amount of the transaction of the purchase. Format: 10.00 |
| Currency | String | A three-letter currency code of the one-time code, eg. PLN |
| Expiry_Date | String | An expiry date of the one-time code |
| Unique_ID | String | The unique identifier from the comment of the transaction |
| Unique_Response_ID | String | A unique serial number of the response |
| ERR_Code | String | The error code (the parameter is blank in the event of success) |
| ERR_Description | String | A description of the error (the parameter is blank in the event of success) |
| Hash | String | See the article ‘Security’ for a description of method that verifies correctness of this value |