Notification is a POST-request (callback). The request's body contains all relevant data of the invoice serialized as HTTP-request parameters and encoded by UTF-8 plus parameter command=bill.
Example of notification request
user@server:~$ curl "https://example.com/qiwi-notify.php"
-v -w "%{http_code}"
-X POST --header "Accept: text/xml"
--header "Content-Type: application/x-www-form-urlencoded; charset=utf-8"
--Authorization: "Basic MjA0Mjp0ZXN0Cg=="
-d "bill_id=BILL-1%26status=paid%26amount=1.00%26user=tel%3A%2B79031811737%26prv_name=TEST%26ccy=RUB%26comment=test%26command=bill"-
- Click "Create password and save" to obtain password for notification Basic authorization
-
- Authorization: Basic XXX - for login/password authorization
- X-Api-Signature: XXX - for digital signature authorization
- Accept: text/json
- Content-type: application/x-www-form-urlencoded
- Invoice parameters are in the request's body.
| Parameter | Description | Type | Required |
|---|---|---|---|
| bill_id | Merchant invoice number | String | Y |
| status | Current invoice status | String | Y |
| amount | The invoice amount. The number is rounded down with two decimal places | Number(6.2) | Y |
| user | The QIWI Wallet user’s ID, to whom the invoice is issued. It is the user’s phone number with tel: prefix |
String | Y |
| prv_name | Merchant’s site name specified on kassa.qiwi.com in "Settings" section | String | Y |
| ccy | Invoice currency identifier (Alpha-3 ISO 4217 code) | String(3) | Y |
| comment | Comment to the invoice | String(255) | Y |
| command | Always bill by default |
String | Y |
Example of XML response to notification
HTTP/1.1 200 OK
Content-Type: text/xml
<?xml version="1.0"?>
<result>
<result_code>0</result_code>
</result>Response must be in XML format.
-
- Content-type: text/xml
| XML Tag | Description |
|---|---|
| result | Grouping tag. Describes notification processing result. |
| result_code | Notification result code (positive integer). We recommend that the result codes returned by the merchant be in accordance with Notification codes table. |
Merchant's server should use basic-authorization or authorization by signature. Merchant may also use client SSL certificate verification (self-signed certificates may be used as well). QIWI Wallet server certificate should be verified in HTTPS requests.
If the client SSL-certificate is self-generated and is not issued by one of the standard certification centers, this certificate should be uploaded to the QIWI Wallet server via Certificate field in Settings - Protocols details - REST-protocol section of QIWI partners web site).
The merchant's certificate is treated as trusted after the upload. Certificate must be in one of the following formats:
- PEM (text file with .pem extension) – (Privacy-enhanced Electronic Mail) BASE64 encoded DER certificate placed between -----BEGIN CERTIFICATE----- and -----END CERTIFICATE----- strings.
- DER (binary file with .cer, .crt, .der extensions) – usually in binary DER format, though PEM certificates are also accepted with this extensions.
Example of notification with Basic auth
POST /qiwi-notify.php HTTP/1.1
Accept: text/xml
Content-type: application/x-www-form-urlencoded
Authorization: Basic ***
Host: example.com
command=bill&bill_id=BILL-1&status=paid&error=0&amount=1.00&user=tel%3A%2B79031811737&prv_name=Retail_Store&ccy=RUB&comment=testThe login is taken from Shop ID parameter. To obtain password, click on Change notification password button in Protocols details - REST-protocol section of QIWI partners web site.
Example of notification with Signature
POST /qiwi-notify.php HTTP/1.1
Accept: text/xml
Content-type: application/x-www-form-urlencoded
X-Api-Signature: J4WNfNZd***V5mv2w=
Host: example.com
command=bill&bill_id=LocalTest17&status=paid&error=0&amount=0.01&user=tel%3A%2B78000005122&prv_name=Test&ccy=RUB&comment=Some+DescriptorExample of notification processing with signature check
<?php
function hexToStr($hex){
$string='';
for ($i=0; $i < strlen($hex)-1; $i+=2){
$string .= chr(hexdec($hex[$i].$hex[$i+1]));
}
return $string;
}
//Signature generation by key and string
function checkSign($key, $req){
$sign_hash = hash_hmac("sha1", $req, $key);
$sign_tr = hexToStr($sign_hash);
$sign = base64_encode($sign_tr);
return $sign;
}
//Sort POST-request parameters and return values
function getReqParams(){
$reqparams = "";
ksort($_POST);
foreach ($_POST as $param => $valuep) {
$reqparams = "$reqparams|$valuep";
}
return substr($reqparams,1);
}
//Take signature from the request
function getSign(){
$HEADERS = getallheaders();
foreach ($HEADERS as $header => $value) {
if ($header == 'X-Api-Signature') {
$SIGN_REQ = $value;
}
}
return $SIGN_REQ;
}
// Sort parameters
$Request = getReqParams();
// Notification password
$NOTIFY_PWD = "***";
// Get sign
$reqres = checkSign($NOTIFY_PWD, $Request);
// Get sign from the request
$SIGN_REQ = getSign();
if ($reqres == $SIGN_REQ) {
$error = 0;
}
else $error = 151;
//Response
header('Content-Type: text/xml');
$xmlres = <<<XML
<?xml version="1.0"?>
<result>
<result_code>$error</result_code>
</result>
XML;
echo $xmlres;
?>The HTTP header X-Api-Signature with signature is added to the POST-request. Signature is calculated as HMAC algorithm with SHA1-hash function.
- Parameters' separator is
|. - Signed are all the parameters in the original invoice request.
- Parameters are in alphabetical order and UTF-8 byte-encoded.
- Secret key for signature is the password for notification basic-authorization.
Signature verification algorithm is as follows:
-
Prepare a string of all parameters values from the notification POST-request sorted in alphabetical order and separated by
|:{parameter1}|{parameter2}|…where
{parameter1}is the value of the notification parameter. All values should be treated as strings. -
Transform obtained string and password for the notification basic-authorization into bytes encoded in UTF-8.
-
Apply HMAC-SHA1 function:
hash = HMAС(SHA1, Notification_password_bytes, Invoice_parameters_bytes)Where:Notification_password_bytes– secret key (bytecoded notification password);Invoice_parameters_bytes– bytecoded POST-request body;hash– hash-function result.
-
Transform HMAC-hash value into bytes with UTF-8 and Base64-encode it.
-
Compare
X-Api-Signatureheader's value with the result of step 4.
The given PHP example implements notification authorization by signature verification. Open the PHP tab on the right.
| Code | Description |
|---|---|
| 0 | Success |
| 5 | The format of the request parameters is incorrect |
| 13 | Database connection error |
| 150 | Incorrect password |
| 151 | Signature authorization failed |
| 300 | Server connection error |