NAV
http php

Прием платежей

Последнее обновление: 2017-05-31 | Редактировать на GitHub

QIWI Wallet Pull API открывает доступ к операциям со счетами в системе QIWI Wallet из вашего приложения. Поддерживаются следующие операции:

Способы оплаты

Для использования API пройдите регистрацию и подключение.

Способы интеграции

Для работы с QIWI Wallet Pull API доступны следующие способы:

Pull REST API

Последнее обновление: 2017-11-14 | Редактировать на GitHub

Последовательность операций

Operation Flow

Средства для разработки

Авторизация

Все запросы мерчанта к Pull REST API авторизуются посредством HTTP basic-авторизации. Для авторизации используются API ID и API password. Заголовок представляет собой параметр Authorization, значение которого представлено как: Basic Base64(API_ID:API_PASSWORD)

user@server:~$ curl "адрес сервера"
  --header "Authorization: Basic MjMyNDQxMjM6NDUzRmRnZDQ0Mw=="
Параметр Описание Тип Обяз.
API_ID Идентификатор для авторизации провайдера в API Integer +
API_PASSWORD Пароль для авторизации в API String +
ID проекта Числовой идентификатор сервиса провайдера Integer +

Выставление счета за покупку

Запрос выставляет новый счет на указанный номер телефона (номер кошелька QIWI Wallet).

<?php
//Пример реализации запроса на PHP
//Идентификатор магазина из вкладки "Данные магазина"
//https://ishop.qiwi.com/options/http.action
$SHOP_ID = "21379721";
//API ID из вкладки "Данные магазина"
//https://ishop.qiwi.com/options/rest.action
$REST_ID = "62573819";
//API пароль из вкладки "Данные магазина"
//https://ishop.qiwi.com/options/rest.action
$PWD = "**********";
//ID счета
$BILL_ID = "99111-ABCD-1-2-1";
$PHONE = "79191234567";

$data = array(
    "user" => "tel:+" . $PHONE,
    "amount" => "1000.00",
    "ccy" => "RUB",
    "comment" => "Все очень хорошо",
    "lifetime" => "2015-01-30T15:35:00",
    "pay_source" => "qw",
    "prv_name" => "Хороший магазин"
);

$ch = curl_init('https://api.qiwi.com/api/v2/prv/'.$SHOP_ID.'/bills/'.$BILL_ID);
curl_setopt($ch, CURLOPT_SSL_VERIFYPEER, FALSE);
curl_setopt($ch, CURLOPT_CUSTOMREQUEST, 'PUT');
curl_setopt($ch, CURLOPT_POSTFIELDS, http_build_query($data));
curl_setopt($ch, CURLOPT_POST, 1);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, TRUE);
curl_setopt($ch, CURLOPT_HTTPAUTH, CURLAUTH_BASIC);
curl_setopt($ch, CURLOPT_USERPWD, $REST_ID.":".$PWD);
curl_setopt($ch, CURLOPT_HTTPHEADER,array (
    "Accept: application/json"
));
$results = curl_exec ($ch) or die(curl_error($ch));
echo $results;
echo curl_error($ch);
curl_close ($ch);
//Необязательный редирект пользователя
$url = 'https://bill.qiwi.com/order/external/main.action?shop='.$SHOP_ID.'&
transaction='.$BILL_ID.'&successUrl=http%3A%2F%2Fieast.ru%2Findex.php%3Froute%3D
payment%2Fqiwi%2Fsuccess&failUrl=http%3A%2F%2Fieast.ru%2Findex.php%3Froute%3D
payment%2Fqiwi%2Ffail&pay_source=card';
echo '<br><br><b><a href="'.$url.'">Ссылка переадресации для оплаты счета</a></b>';
?>

Запрос → PUT

  user@server:~$ curl "https://api.qiwi.com/api/v2/prv/373712/bills/BILL-1"
    -X PUT --header "Accept: text/json"
    --header "Authorization: Basic ***"
    -d "user=tel%3A%2B79031234567&amount=10.00&ccy=RUB&comment=test&lifetime=2016-09-25T15:00:00"
Параметр Описание Тип Обяз.
user Идентификатор номера QIWI Wallet, на который выставляется счет (в международном формате), с префиксом tel: String(20) +
amount Сумма, на которую выставляется счет. Округляется в меньшую сторону до двух десятичных знаков Number(6.2) +
ccy Идентификатор валюты (Alpha-3 ISO 4217 код). Может использоваться любая валюта, предусмотренная договором с КИВИ String(3) +
comment Комментарий к счету String(255) +
lifetime Дата, до которой счет будет доступен для оплаты. Если счет не будет оплачен до этой даты, ему присваивается финальный статус и последующая оплата станет невозможна.
Внимание! По истечении 45 суток от даты выставления счет автоматически будет переведен в финальный статус.
dateTime +
pay_source mobile - оплата счета будет выполнена с баланса мобильного телефона пользователя,
qw – оплата любым способом через интерфейс QIWI Кошелька.
По умолчанию qw
String -
prv_name Название провайдера. String(100) -

Для просмотра примера PHP-скрипта выставления счета и перенаправления на Платежную форму QIWI откройте вкладку PHP справа.

Данный пример иллюстрирует, когда и где в запросах к системе QIWI Wallet используются авторизационные данные провайдера, а именно, идентификатор магазина, API ID и пароль к API.

Ответ ←

HTTP/1.1 200 OK
Content-Type: text/json
{
  "response": {
     "result_code": 0,
     "bill": {
        "bill_id": "BILL-1",
        "amount": "10.00",
        "ccy": "RUB",
        "status": "waiting",
        "error": 0,
        "user": "tel:+79031234567",
        "comment": "test"
     }
  }
}
HTTP/1.1 401 Unauthorized
Content-Type: text/json
{
 "response": {
  "result_code": 150,
  "description": "Authorization failed"
  }
}

Формат ответа зависит от заголовка “Accept” в исходном запросе:

Параметр Тип Описание
result_code Integer Код результата
description String Описание ошибки. Передается в случае ошибки (ненулевой result_code)
bill Object Данные о счете. Передается в случае успешного результата (result_code = 0). Параметры:
bill.bill_id String Уникальный идентификатор счета в системе провайдера
bill.amount String Сумма, на которую выставлен счет. Округляется в меньшую сторону до двух десятичных знаков.
bill.ccy String Идентификатор валюты (Alpha-3 ISO 4217 код)
bill.status String Текущий статус счета
bill.error Integer Константа, всегда 0
bill.user String Идентификатор кошелька пользователя, которому выставлен счет (номер телефона в международном формате с префиксом tel:)
bill.comment String Комментарий к счету

Проверка статуса оплаты счета

Метод для проверки текущего статуса счета.

Запрос → GET

user@server:~$ curl "https://api.qiwi.com/api/v2/prv/373712/bills/BILL-1"
  --header "Authorization: Basic ***"
  --header "Accept: text/json"

Ответ ←

HTTP/1.1 200 OK
Content-Type: text/json
{
  "response": {
     "result_code": 0,
     "bill": {
        "bill_id": "BILL-1",
        "amount": "10.00",
        "ccy": "RUB",
        "status": "waiting",
        "error": 0,
        "user": "tel:+79031234567",
        "comment": "test"
     }
  }
}
HTTP/1.1 401 Unauthorized
Content-Type: text/json
{
 "response": {
  "result_code": 150,
  "description": "Authorization failed"
  }
}
Параметр Тип Описание
result_code Integer Код результата
description String Описание ошибки. Передается в случае ошибки (ненулевой result_code)
bill Object Данные о счете. Передается в случае успешного результата (result_code = 0). Параметры:
bill.bill_id String Уникальный идентификатор счета в системе провайдера
bill.amount String Сумма, на которую выставлен счет. Округляется в меньшую сторону до двух десятичных знаков.
bill.originAmount String Сумма счета в валюте баланса, с которого оплачивался счета (см. параметр originCcy). Округляется в меньшую сторону до двух десятичных знаков. Возвращается только для счетов, по которым пользователь инициировал оплату.
bill.ccy String Идентификатор валюты, в которой выставлен счет (Alpha-3 ISO 4217 код)
bill.originCcy String Идентификатор валюты баланса, с которого оплачивался счет (Alpha-3 ISO 4217 код). Возвращается только для счетов, по которым пользователь инициировал оплату.
bill.status String Текущий статус счета
bill.error Integer Константа, всегда 0
bill.user String Идентификатор кошелька пользователя, которому выставлен счет (номер телефона в международном формате с префиксом tel:)
bill.comment String Комментарий к счету

Отмена неоплаченного счета

Метод для отмены неоплаченного клиентом счета до наступления предельной даты оплаты счета (см. параметр lifetime).

Запрос → PATCH

user@server:~$ curl "https://api.qiwi.com/api/v2/prv/373712/bills/BILL-1"
  -X PATCH
  --header "Authorization: Basic ***"
  --header "Accept: text/json"
  --header "Content-type: application/x-www-form-urlencoded; charset=utf-8"
  -d "status=rejected"

Ответ ←

HTTP/1.1 200 OK
Content-Type: text/json
{
   "response": {
      "result_code": 0,
      "bill": {
         "bill_id": "BILL-1",
         "amount": "10.00",
         "ccy": "RUB",
         "status": "rejected",
         "error": 0,
         "user": "tel:+79031234567",
         "comment": "test"
      }
   }
}
HTTP/1.1 401 Unauthorized
Content-Type: text/json
{
 "response": {
  "result_code": 150,
  "description": "Authorization failed"
  }
}
Параметр Тип Описание
result_code Integer Код результата
description String Описание ошибки. Передается в случае ошибки (ненулевой result_code)
bill Object Данные об отмененном счете. Передается в случае успешного результата (result_code = 0). Параметры:
bill.bill_id String Уникальный идентификатор счета в системе провайдера
bill.amount String Сумма, на которую выставлен счет. Округляется в меньшую сторону до двух десятичных знаков.
bill.ccy String Идентификатор валюты, в которой выставлен счет (Alpha-3 ISO 4217 код)
bill.status String Текущий статус счета
bill.error Integer Константа, всегда 0
bill.user String Идентификатор кошелька пользователя, которому выставлен счет (номер телефона в международном формате с префиксом tel:)
bill.comment String Комментарий к счету

Возврат оплаченного счета

Метод выполняет полный или частичный возврат средств по счету, оплаченному клиентом, на его QIWI Кошелек. При этом создается платеж, обратный платежу на оплату счета. Валюта платежа совпадает с валютой исходного счета.

По одному и тому же счету можно выполнять несколько операций возврата, при условии что:

Последовательность операций

Refund Operation Flow

Запрос → PUT

user@server:~$ curl "https://api.qiwi.com/api/v2/prv/373712/bills/BILL-1/refund/REF1"
  -v -w "%{http_code}"
  -X PUT
  --header "Accept: text/json"
  --header "Authorization: Basic ***"
  --header "Content-type: application/x-www-form-urlencoded; charset=utf-8"
  -d "amount=5.0"

Ответ ←

HTTP/1.1 200 OK
Content-Type: text/json
{
   "response": {
      "result_code": 0,
      "refund": {
         "refund_id": "br1",
         "amount": "5.00",
         "status": "success",
         "error": 0
      }
   }
}
HTTP/1.1 401 Unauthorized
Content-Type: text/json
{
 "response": {
  "result_code": 150,
  "description": "Authorization failed"
  }
}
Параметр Тип Описание
result_code Integer Код результата
description String Описание ошибки. Передается в случае ошибки (ненулевой result_code)
refund Object Данные об операции возврата. Передается в случае успешного результата (result_code = 0). Параметры:
refund.refund_id String Уникальный идентификатор операции возврата счета в системе провайдера
refund.amount String Сумма к возврату. Положительное число, округляется в меньшую сторону до двух десятичных знаков.
refund.status String Текущий статус операции возврата
refund.error Integer Код ошибки при проведении возврата платежа. В случае если сумма, переданная в запросе, превышает сумму самого счета либо сумму счета, оставшуюся после предыдущих возвратов, в ответе будет возвращен код ошибки 242.

Проверка статуса возврата

Метод для проверки текущего статуса операции возврата средств по оплаченному счету.

Запрос → GET

user@server:~$ curl "https://api.qiwi.com/api/v2/prv/373712/bills/BILL-1/refund/REF1"
  -v -w "%{http_code}"
  --header "Accept: text/json"
  --header "Authorization: Basic ***"

Ответ ←

HTTP/1.1 200 OK
Content-Type: text/json
{
   "response": {
      "result_code": 0,
      "refund": {
         "refund_id": "REF1",
         "amount": "5.00",
         "status": "success",
         "error": 0
      }
   }
}
HTTP/1.1 401 Unauthorized
Content-Type: text/json
{
 "response": {
  "result_code": 150,
  "description": "Authorization failed"
  }
}
Параметр Тип Описание
result_code Integer Код результата
description String Описание ошибки. Передается в случае ошибки (ненулевой result_code)
refund Object Данные об операции возврата. Передается в случае успешного результата (result_code = 0). Параметры:
refund.refund_id String Уникальный идентификатор операции возврата счета в системе провайдера
refund.amount String Сумма к возврату. Положительное число, округляется в меньшую сторону до двух десятичных знаков.
refund.status String Текущий статус операции возврата
refund.error Integer Код ошибки при проведении возврата платежа. В случае если сумма, переданная в запросе, превышает сумму самого счета либо сумму счета, оставшуюся после предыдущих возвратов, в ответе будет возвращен код ошибки 242.

Статусы операций

Последнее обновление: 2017-07-11 | Редактировать на GitHub

Статусы оплаты счетов

Статус Описание Финальный
waiting Счет выставлен, ожидает оплаты или оплачивается -
paid Счет оплачен +
rejected Счет отклонен +
unpaid Ошибка при проведении оплаты. Счет не оплачен +
expired Время жизни счета истекло. Счет не оплачен +

Статусы операции возврата

Статус Описание Финальный
processing Платеж в проведении -
success Платеж проведен +
fail Платеж неуспешен +

Список ошибок

Последнее обновление: 2017-07-11 | Редактировать на GitHub
Код Описание Fatal*
0 Успех  
5 Неверные данные в параметрах запроса +
13 Сервер занят, повторите запрос позже -
78 Недопустимая операция +
150 Ошибка авторизации +
152 Не подключен или отключен протокол -
155 Данный идентификатор провайдера (API ID) заблокирован +
210 Счет не найден +
215 Счет с таким bill_id уже существует +
241 Сумма слишком мала +
242 Сумма слишком велика, или сумма, переданная в запросе возврата средств, превышает сумму самого счета либо сумму счета, оставшуюся после предыдущих возвратов +
298 Кошелек с таким номером не зарегистрирован +
300 Техническая ошибка -
303 Неверный номер телефона +
316 Попытка авторизации заблокированным провайдером -
319 Нет прав на данную операцию -
339 Ваш IP-адрес или массив адресов заблокирован +
341 Обязательный параметр указан неверно или отсутствует в запросе +
700 Превышен месячный лимит на операции +
774 Кошелек временно заблокирован -
1001 Запрещенная валюта для провайдера +
1003 Не удалось получить курс конвертации для данной пары валют -
1019 Не удалось определить сотового оператора для мобильной коммерции +
1419 Нельзя изменить данные счета – он уже оплачивается или оплачен +

Форма выставления счета

Последнее обновление: 2017-11-15 | Редактировать на GitHub

Клиенту отображается платежная форма с выбором способа оплаты выставленного счета.

Вызов веб-формы выполняется без авторизации провайдера. Номер телефона и сумму счета клиент может указать непосредственно на веб-форме.

Последовательность операций

Запрос → REDIRECT

GET /order/external/create.action?txn_id=10000&from=11223&summ=1.11&successUrl=http%3A%2F%2Ftest.ru%3Fcurrency=643 HTTP/1.1
Host: bill.qiwi.com
Параметр Описание Тип Обяз.
from Идентификатор провайдера. Идентификатор указан в настройках HTTP-протокола в личном кабинете провайдера на сайте ishop.qiwi.com Integer +
currency Идентификатор валюты (Alpha-3 ISO 4217 код). Может использоваться любая валюта, предусмотренная договором с КИВИ String(3) +
to Идентификатор номера QIWI Wallet, на который выставляется счет (в международном формате). Если не указан, то пользователю на веб-форме отображается поле ввода номера телефона. Счет выставляется только после заполнения номера String(20) -
summ Сумма, на которую выставляется счет. Если параметр не указан, то на веб-форме отображается поле ввода суммы и счет выставляется только после заполнения суммы. Number(6.2) -
txn_id Уникальный идентификатор счета в системе провайдера (например, номер заказа в интернет-магазине). Используется для идентификации конкретного счета. String(30) -
comm Комментарий к счету. Если не указаны данный параметр и параметр to, то на веб-форме пользователю отображается поля ввода номера телефона и комментария. Счет выставляется только после заполнения номера String(255) -
lifetime Время действия счета (в минутах) от момента создания. По истечении этого времени оплата станет невозможна (счет будет отменен). Внимание! Если параметр отсутствует, по истечении 28 суток от даты выставления счет автоматически будет отменен. Integer -
successUrl URL для переадресации в случае успешного создания транзакции в QIWI Wallet. Ссылка должна вести на сайт провайдера. Если пользователь выбрал на платежной форме способ оплаты, отличный от оплаты с баланса QIWI Кошелька, то переадресация на сайт провайдера не выполняется. URL-закодированная строка -
failUrl URL для переадресации в случае неуспеха при создании транзакции в QIWI Wallet. Ссылка должна вести на сайт провайдера. Если пользователь выбрал на платежной форме способ оплаты, отличный от оплаты с баланса QIWI Кошелька, то переадресация на сайт провайдера не выполняется. URL-закодированная строка -
target Флаг, показывающий, что ссылки в параметрах
successUrl / failUrl открываются в iframe. Если отсутствует, то считается выключенным
Строка (только iframe) -
pay_source Способ оплаты по умолчанию, который необходимо отобразить пользователю при открытии платежной формы. Возможные значения:
qw – оплата с баланса QIWI Кошелька;
mobile – оплата с баланса мобильного телефона;
card – оплата банковской картой;
wm – оплата с привязанного кошелька WebMoney;
ssk – оплата наличными в терминале QIWI.
Если способ оплаты не доступен, пользователю отображается предупреждение, при этом на странице можно выбрать другие способы оплаты.
String -

Форма оплаты

Последнее обновление: 2017-11-14 | Редактировать на GitHub

Провайдер может предложить пользователю немедленно оплатить счет с помощью переадресации на платежную форму.

Вызов формы оплаты
GET /order/external/main.action?shop=2042&transaction=1234567&successUrl=http%3A%2F%2Fmystore.com%2Fsuccess%3Fa%3D1%26b%3D2&failUrl=http%3A%2F%2Fmystore.com%2Ffail%3Fa%3D1%26b%3D2&pay_source=qw HTTP/1.1
Host: bill.qiwi.com

Запрос → REDIRECT

Параметр Тип Описание Обяз.
shop Строка Идентификатор провайдера. Соответствует параметру prv_id из запроса на выставление счета. +
transaction Строка Идентификатор счета в информационной системе провайдера. Соответствует параметру bill_id из запроса на выставление счета. +
iframe Логический, true/false Признак отображения страницы в iframe (более компактный вид, удобный для встраивания ее в сайт провайдера). По умолчанию false -
successUrl URL-закодированная строка URL для переадресации в случае успешного создания транзакции в QIWI Wallet. Ссылка должна вести на сайт провайдера. Если пользователь выбрал на платежной форме способ оплаты, отличный от оплаты с баланса QIWI Кошелька, то переадресация на сайт провайдера не выполняется. -
failUrl URL-закодированная строка URL для переадресации в случае неуспеха при создании транзакции в QIWI Wallet. Ссылка должна вести на сайт провайдера. Если пользователь выбрал на платежной форме способ оплаты, отличный от оплаты с баланса QIWI Кошелька, то переадресация на сайт провайдера не выполняется. -
target Строка “iframe” Флаг, показывающий, что ссылки в параметрах
successUrl / failUrl открываются в iframe. Если отсутствует, то считается выключенным
-
pay_source Строка Способ оплаты по умолчанию, который необходимо отобразить пользователю при открытии платежной формы. Возможные значения:
qw – оплата с баланса QIWI Кошелька;
mobile – оплата с баланса мобильного телефона;
card – оплата банковской картой;
wm – оплата с привязанного кошелька WebMoney;
ssk – оплата наличными в терминале QIWI.
Если способ оплаты не доступен, пользователю отображается предупреждение, при этом на странице можно выбрать другие способы оплаты.
-

Возврат на сайт провайдера

Возврат клиента после успешного создания транзакции
GET /success?a=1&b=2&order=1234567 HTTP/1.1
Host: mystore.com
Возврат клиента в случае неуспеха при создании транзакции
GET /fail?a=1&b=2&order=1234567 HTTP/1.1
Host: mystore.com

При переадресации в ссылку добавляется параметр order, в котором будет передан исходный идентификатор счета у провайдера. Используя этот параметр, провайдер может отобразить необходимую информацию на своей стороне.

Уведомления об оплате счетов

Последнее обновление: 2017-11-14 | Редактировать на GitHub

Уведомление представляет собой POST-запрос. Тело запроса содержит сериализованные данные счета в теле запроса (кодировка UTF-8), и параметр command=bill.

Запрос → POST

Пример

user@server:~$ curl "https://service.ru/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%26pay_date=2016%3A11%3A16T11%3A00%3A15%26amount=1.00%26user=tel%3A%2B79031811737%26prv_name=TEST%26ccy=RUB%26comment=test%26command=bill"
Параметр Описание Тип Обяз.
status Текущий статус счета String +
amount Сумма, на которую выставлялся счет, округленная до двух десятичных знаков Number(6.2) +
user Номер QIWI Кошелька, на который был выставлен счет String +
pay_date Дата оплаты счета (заполняется, если счет оплачен) DateTime (YYYY-MM-DDThh:mm:ss) +
prv_name Наименование проекта, указанное на сайте ishop.qiwi.com в разделе:”Настройки”->”Данные проекта”->”Короткое наименование” String +
ccy Идентификатор валюты (Alpha-3 ISO 4217 код) String(3) +
comment Комментарий к счету String(255) +
command bill - всегда по умолчанию String +

Ответ ←

HTTP/1.1 200 OK
Content-Type: text/xml

<?xml version="1.0"?>
<result>
<result_code>0</result_code>
</result>

Ответ на запрос должен быть в формате XML.

Авторизация уведомлений

Для авторизации можно использовать basic-авторизацию или авторизацию подписи. При запросах уведомлений на сервер провайдера также можно использовать SSL (в том числе самоподписанный сертификат). В HTTPS-запросах необходимо проверять серверный сертификат QIWI Wallet.

Basic-авторизация

POST /qiwi-notify.php HTTP/1.1
Accept: text/xml
Content-type: application/x-www-form-urlencoded
Authorization: Basic ***
Host: service.ru

command=bill&bill_id=BILL-1&status=paid&error=0&amount=1.00&user=tel%3A%2B79031811737&prv_name=Retail_Store&ccy=RUB&comment=test

Логин равен ID магазина. Для получения пароля нажмите кнопку “Сменить пароль оповещения” в Личном кабинете мерчантав разделе “Настройки”->”REST-Протокол”.

Авторизация по подписи

<?php

function hexToStr($hex){
    $string='';
    for ($i=0; $i < strlen($hex)-1; $i+=2){
        $string .= chr(hexdec($hex[$i].$hex[$i+1]));
    }
    return $string;
}

//функция генерации подписи по ключу и строке параметров
function checkSign($key, $req){
    $sign_hash = hash_hmac("sha1", $req, $key);
    $sign_tr = hexToStr($sign_hash);
    $sign = base64_encode($sign_tr);
    return $sign;
}

//Функция возвращает упорядоченную строку значений параметров POST-запроса
function getReqParams(){
    $reqparams = "";
    ksort($_POST);
    foreach ($_POST as $param => $valuep) {
        $reqparams = "$reqparams|$valuep";
    }
    return substr($reqparams,1);
}

//Извлечение цифровой подписи из заголовков запроса
function getSign(){
    $HEADERS = getallheaders();
    foreach ($HEADERS as $header => $value) {
       if ($header == 'X-Api-Signature') {
            $SIGN_REQ = $value;
       }
    }
    return $SIGN_REQ;
}

// Сортировка параметров
$Request = getReqParams();
// Пароль ishop для уведомлений магазина
$NOTIFY_PWD = "***";
// Вычисляем подпись
$reqres = checkSign($NOTIFY_PWD, $Request);

// Подпись из запроса
$SIGN_REQ = getSign();

if ($reqres == $SIGN_REQ) {
    $error = 0;
}
else $error = 151;

//Ответ
header('Content-Type: text/xml');
$xmlres = <<<XML
<?xml version="1.0"?>
<result>
<result_code>$error</result_code>
</result>
XML;
echo $xmlres;
?>
POST /qiwi-notify.php HTTP/1.1
Accept: text/xml
Content-type: application/x-www-form-urlencoded
X-Api-Signature: J4WNfNZd***V5mv2w=
Host: service.ru

command=bill&bill_id=LocalTest17&status=paid&error=0&amount=0.01&user=tel%3A%2B78000005122&prv_name=Test&ccy=RUB&comment=Some+Descriptor

Подпись уведомления отправляется в заголовке X-Api-Signature. Для формирования подписи используется механизм проверки целостности HMAC с хэш-функцией SHA1.

Алгоритм проверки подписи:

  1. Получить строку, содержащую значения всех параметров POST-запроса в алфавитном порядке перечисления параметров, разделенных символами |:

    {parameter1}|{parameter2}|…

    где {parameter1} – значение параметра уведомления. Все значения при проверке подписи должны трактоваться как строки.

  2. Cтроку и пароль для basic-авторизации уведомления преобразовать в байты с UTF-8.
  3. Вычислить HMAC-хэш c шифрованием SHA1:

    hash = HMAС(SHA1, Notification_password_bytes, Invoice_parameters_bytes) где:

    • Notification_password_bytes – ключ функции (байт-представление basic-пароля для уведомлений);
    • Invoice_parameters_bytes – байт-представление тела POST-запроса;
    • hash – результат хэш-функции.
  4. HMAC-хэш преобразовать из строк в байты с использованием кодировки UTF-8 и base64-преобразовать.
  5. Сравнить значение заголовка X-Api-Signature с результатом 4.

Пример реализации

Пример на языке PHP реализует авторизацию уведомлений системы QIWI Wallet с проверкой цифровой подписи. Откройте вкладку PHP справа.

Коды уведомлений

Код завершения Описание
0 Успех
5 Ошибка формата параметров запроса
13 Ошибка соединения с базой данных
150 Ошибка проверки пароля
151 Ошибка проверки подписи
300 Ошибка связи с сервером