JSON notifications

When connecting via the HTTP+JSON scheme, the merchant determines in advance the URL on which JSON notifications from the «Invoicebox» system will be received.

Security

There are several options for secure interaction between the merchant and the «Invoicebox» system:

• MD5 - default option;
• SSL/keys - higher security option.

Please read additional security notes at Information security rules page.

Interaction

Requests are sent using the HTTP 1.1 POST protocol.

The format for passing parameters to the query:

• all parameter are passed in JSON encoded string in a body of POST-request;
• MIME-type: application/json;
• charset: UTF-8.

Parameters

Parameter	Description
participantId	Merchant ID
participantOrderId	Order ID
ucode	Unique bill number
timetype	Time value format
time	Payment time in ATOM format
amount	Payment amount
agentName	Payment instrument
agentPointName	Payment point
sign	Security sign

Response parameters

Parameter	Description
resultCode	Result code number
resultMessage	Result code description

In case of successful processing of payment information, merchant should return resultCode=0. In the event of an error, merchant should return non-zero resultCode and error description in resultMessage parameter.

Check of received parameters

Request sign

When using the default security option with MD5, the «Invoicebox» system adds a parameter with the name sign (security sign). The value of the parameter is MD5 hash from the string collected from the parameter values of query along with API security key.

Upon receipt of a request, it is necessary to verify that the request was sent by the «Invoicebox» system and the data in the request came completely. For this, the merchant checks the value of the sign parameter. If the value does not match the calculation result of the MD5 hash function from the passed parameters, the request must be denied and the error returned.

MD5-hashing is applied to text, which is formed as a sequence of values of query parameters without delimiters. The result of hashing is reduced to the lower case.

The order of the parameters:

Example:

Source string	Hashing result
131order112345-12345-12345-12345unixtime1231323231000.00Alfa-ClickPassword	446d57eb1d1f2f8fd0221f474a6db785

Request integrity

The merchant must verify the payment amount in the request with the order amount in the accounting system. If the payment amount does not match the order amount, merchant must refuse the request and return the error.

Request source

It is recommended to additionally check the IP address of the sender of the request. The list of «Invoicebox» IP addresses can be found on the page information security rules.