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


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:

  1. The outlet tell Corporate Node transfer funds from application of service billon.io, providing the unique identifier in the comment
  2. When the transaction is successfully finished, the outlet sends query about the purchase of one-time code to Billon API (query purchaseCode)
  3. 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

ParameterData typeDescription
TimestampStringGMT 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_IDStringID of given sale point
Unique_IDStringUnique ID from the comment of the transaction
MethodString(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.
PhoneString(optionaly) Phone number to which the one-time code is to be sent, if SMS method is chosen
Alert_AddressString(optionally) Address (which starts with http:// or https://) to which immediate HTTP notification about one-time code to top up user’s application
HashStringSee the article ‘Security’ for a description of method that calculates this amount.


Response: the one-time code

ParameterData typeDescription
CodeStringThe 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_NoStringA serial number of the one-time code
AmountStringA amount of the transaction of the purchase. Format: 10.00
CurrencyStringA three-letter currency code of the one-time code, eg. PLN
Expiry_DateStringAn expiry date of the one-time code
Unique_IDStringThe unique identifier from the comment of the transaction
Unique_Response_IDStringA unique serial number of the response
ERR_CodeStringThe error code (the parameter is blank in the event of success)
ERR_DescriptionStringA description of the error (the parameter is blank in the event of success)
HashStringSee the article ‘Security’ for a description of method that verifies correctness of this value
Was this article helpful to you? Yes No

How can we help?