Pull REST API {#pull-payments-api_ru}

Редактировать на GitHub

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

Пользователь формирует заказ на сайте провайдера.
Сервис провайдера выставляет счет.
Для повышения конверсии оплаты счетов рекомендуется перенаправлять пользователя на платежную форму QIWI Wallet. Также пользователь может оплатить счет через любой другой интерфейс QIWI Кошелька (сайт qiwi.com, платежный терминал QIWI, мобильное приложение Android или iOS).
Если сервис провайдера использует уведомления, то после проведения платежа система QIWI Wallet высылает уведомление на сервер провайдера об оплате данного счета, либо, если пользователь отклонил счет, о неоплате. Уведомления об оплате счета содержат параметры авторизации, которые необходимо проверять на сервере провайдера.
В любом случае, провайдер может:
- запросить текущий статус оплаты счета,
- отменить счет (если пользователь еще не инициировал оплату).
После подтверждения оплаты счета провайдер исполняет заказ пользователя.

Средства для разработки {#node_sdk}

NODE JS SDK - Пакет готовых решений для разработки server2server интеграций для приема платежей на вашем сайте c помощью Node.js.

Авторизация {#auth_param}

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

const prv_id = 21379721;
const api_id = 62573819;
const api_password = '**********';

const qiwiRestApi = new QiwiPullAPI(prv_id, api_id, api_password);

user@server:~$ curl "адрес сервера"

Авторизация и работа с формами
Данные могут быть получены на сайте QIWI Кассы

Параметр	Описание	Тип	Обяз.
API_ID	Идентификатор для авторизации провайдера в API	Integer	+
API_PASSWORD	Пароль для авторизации в API	String	+
ID проекта	Числовой идентификатор сервиса провайдера	Integer	+

Получить служебные данные можно на сайте QIWI Кассы в разделе "Настройки протокола - Аутентификационные данные", "Создать новый API ID".

Подробнее

Если у вас нет учетной записи в QIWI Кассе, то получить служебные данные можно на партнерском сайте kassa.qiwi.com в разделе "Настройки", "Сгенерировать новый ID".

Подробнее

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

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

Запрос → PUT

<?php
//Пример реализации запроса на PHP
//Идентификатор магазина из вкладки "Данные магазина"
$SHOP_ID = "21379721";
//API ID из вкладки "Данные магазина"
$REST_ID = "62573819";
//API пароль из вкладки "Данные магазина"
$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://oplata.qiwi.com/order/external/main.action?shop='.$SHOP_ID.'&
transaction='.$BILL_ID.'&successUrl=http%3A%2F%2Fexample.com%2Findex.php%3Froute%3D
payment%2Fqiwi%2Fsuccess&failUrl=http%3A%2F%2Fexample.com%2Findex.php%3Froute%3D
payment%2Fqiwi%2Ffail&pay_source=card';
echo '<br><br><b><a href="'.$url.'">Ссылка переадресации для оплаты счета</a></b>';
?>

const bill_id = '99111-ABCD-1-2-1';

const fields = {
    amount: 1000.00,
    ccy: 'RUB',
    comment: 'Все очень хорошо',
    lifetime: '2015-01-30T15:35:00',
    user: 'tel:+79191234567',
    pay_source: 'qw',
    prv_name: 'Хороший магазин'
};

qiwiRestApi.createBill( bill_id, fields ).then( data => {
    //do with data
});

  user@server:~$ curl "https://api.qiwi.com/api/v2/prv/373712/bills/99111-ABCD-1-2-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"

URL https://api.qiwi.com/api/v2/prv/prv_id/bills/bill_id
- prv_id - числовой идентификатор провайдера (идентификатор, который отображается в пункте "ID проекта" на партнерском сайте kassa.qiwi.com)
- bill_id - уникальный идентификатор счета в системе провайдера. Уникальность означает, что идентификатор должен отличаться от идентификаторов всех ранее выставленных счетов провайдера.

HEADERS
- Accept: text/json или Accept: application/json - формат ответа JSON
- Accept: text/xml или Accept: application/xml - формат ответа XML
- Content-type: application/x-www-form-urlencoded; charset=utf-8
- Authorization: Basic ***

Параметры
Параметры передаются в теле запроса как formdata

Параметр	Описание	Тип	Обяз.
user	Идентификатор номера QIWI Wallet, на который выставляется счет (в международном формате), с префиксом `tel:`	String(20)	+
amount	Сумма, на которую выставляется счет. Округляется в меньшую сторону до двух десятичных знаков	Number(6.2)	+
ccy	Идентификатор валюты (Alpha-3 ISO 4217 код). Может использоваться любая валюта, предусмотренная договором с КИВИ	String(3)	+
comment	Комментарий к счету	String(255)	+
lifetime	Дата/время с точностью до секунд в формате ISO 8601 (`ГГГГ-ММ-ДДTчч:мм:сс`). Указывается московское время. Если счет не будет оплачен до этого времени, ему присваивается финальный статус и последующая оплата станет невозможна. Внимание! По истечении 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": "99111-ABCD-1-2-1",
        "amount": "1000.00",
        "ccy": "RUB",
        "status": "waiting",
        "error": 0,
        "user": "tel:+79191234567",
        "comment": "Счет от магазина"
     }
  }
}

HTTP/1.1 401 Unauthorized
Content-Type: text/json
{
 "response": {
  "result_code": 150,
  "description": "Authorization failed"
  }
}

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

HEADERS
- Accept: text/json или Accept: application/json - формат ответа JSON
- Accept: text/xml или Accept: application/xml - формат ответа XML

Параметры

Параметр	Тип	Описание
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	Комментарий к счету

Проверка статуса оплаты счета {#invoice-status}

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

const bill_id = '99111-ABCD-1-2-1';

qiwiRestApi.getStatus(bill_id).then( data => {
    //do with data
});

Запрос → GET

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

URL https://api.qiwi.com/api/v2/prv/prv_id/bills/bill_id
- prv_id - числовой идентификатор провайдера (идентификатор, который отображается в пункте "ID проекта" на партнерском сайте kassa.qiwi.com)
- bill_id - уникальный идентификатор счета в системе провайдера.

HEADERS
- Authorization: Basic ***
- Accept: text/json или Accept: application/json - формат ответа JSON
- Accept: text/xml или Accept: application/xml - формат ответа XML

Ответ ←

HTTP/1.1 200 OK
Content-Type: text/json
{
  "response": {
     "result_code": 0,
     "bill": {
        "bill_id": "99111-ABCD-1-2-1",
        "amount": "1000.00",
        "ccy": "RUB",
        "status": "waiting",
        "error": 0,
        "user": "tel:+79031234567",
        "comment": "Счет от магазина"
     }
  }
}

HTTP/1.1 401 Unauthorized
Content-Type: text/json
{
 "response": {
  "result_code": 150,
  "description": "Authorization failed"
  }
}

HEADERS
- Accept: text/json или Accept: application/json - формат ответа JSON
- Accept: text/xml или Accept: application/xml - формат ответа XML

Параметры

Параметр	Тип	Описание
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	Комментарий к счету

Отмена неоплаченного счета {#cancel}

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

const bill_id = '99111-ABCD-1-2-1';

qiwiRestApi.cancel(bill_id).then( data => {
    //do with data
});

Запрос → PATCH

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

URL https://api.qiwi.com/api/v2/prv/prv_id/bills/bill_id
- prv_id - числовой идентификатор провайдера (идентификатор, который отображается в пункте "ID проекта" на партнерском сайте kassa.qiwi.com)
- bill_id - уникальный идентификатор счета в системе провайдера.
- status - строка "rejected" (статус для отмены).

HEADERS
- Authorization: Basic ***
- Accept: text/json или Accept: application/json - формат ответа JSON
- Accept: text/xml или Accept: application/xml - формат ответа XML
- Content-type: application/x-www-form-urlencoded; charset=utf-8

Ответ ←

HTTP/1.1 200 OK
Content-Type: text/json
{
   "response": {
      "result_code": 0,
      "bill": {
         "bill_id": "99111-ABCD-1-2-1",
         "amount": "1000.00",
         "ccy": "RUB",
         "status": "rejected",
         "error": 0,
         "user": "tel:+79031234567",
         "comment": "Счет от магазина"
      }
   }
}

HTTP/1.1 401 Unauthorized
Content-Type: text/json
{
 "response": {
  "result_code": 150,
  "description": "Authorization failed"
  }
}

HEADERS
- Accept: text/json или Accept: application/json - формат ответа JSON
- Accept: text/xml или Accept: application/xml - формат ответа XML

Параметры

Параметр	Тип	Описание
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	Комментарий к счету

Возврат оплаченного счета {#refund}

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

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

сумма всех операций возврата не превышает суммы исходного счета;
для разных операций возврата одного счета используются разные идентификаторы.

Если сумма, переданная в запросе, превышает сумму самого счета либо сумму счета, оставшуюся после предыдущих возвратов, в ответе будет возвращен код ошибки 242.

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

Провайдер отправляет запрос на осуществление возврата.
Если финальный статус возврата не получен в ответе, провайдер периодически опрашивает систему QIWI Wallet о текущем статусе возврата до получения финального статуса.
Данный сценарий можно повторять несколько раз до тех пор, пока счет не будет полностью отменен (возвращена вся сумма).

const bill_id = '893794793973';
const refund_id = '899343443';
const amount = 5.0;

qiwiRestApi.refund(bill_id, refund_id, amount).then( data => {
    //do with data
});

Запрос → PUT

user@server:~$ curl "https://api.qiwi.com/api/v2/prv/373712/bills/893794793973/refund/899343443"
  -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"

URL https://api.qiwi.com/api/v2/prv/prv_id/bills/bill_id/refund/refund_id

Параметры передаются в pathname.

prv_id - числовой идентификатор провайдера (идентификатор, который отображается в пункте "ID проекта" на партнерском сайте kassa.qiwi.com)
bill_id - уникальный идентификатор счета в системе провайдера.
refund_id - идентификатор операции, уникальный в рамках операций возврата счета bill_id. Формат идентификатора: строка от 1 до 9 символов, содержащая только прописные или строчные латинские буквы (a-z, A-Z) и цифры от 0 до 9.

Параметр передается в body запроса.

         <li><strong>amount</strong> - сумма возврата. Должна быть меньше либо равна сумме счета <i>{bill_id}</i>, по которому производится возврат. Округляется в меньшую сторону до двух десятичных знаков.</li>
    </ul>
</li>

HEADERS
- Authorization: Basic ***
- Accept: text/json или Accept: application/json - формат ответа JSON
- Accept: text/xml или Accept: application/xml - формат ответа XML
- Content-Type: application/x-www-form-urlencoded; charset=utf-8

Ответ ←

HTTP/1.1 200 OK
Content-Type: text/json
{
   "response": {
      "result_code": 0,
      "refund": {
         "refund_id": "899343443",
         "amount": "5.00",
         "status": "success",
         "error": 0
      }
   }
}

HTTP/1.1 401 Unauthorized
Content-Type: text/json
{
 "response": {
  "result_code": 150,
  "description": "Authorization failed"
  }
}

HEADERS
- Accept: text/json или Accept: application/json - формат ответа JSON
- Accept: text/xml или Accept: application/xml - формат ответа XML

Параметры

Параметр	Тип	Описание
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`.

Проверка статуса возврата {#refund_status}

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

const bill_id = '893794793973';
const refund_id = '899343443';

qiwiApi.getRefundStatus(bill_id, refund_id).then( data => {
    //do with data
});

Запрос → GET

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

URL https://api.qiwi.com/api/v2/prv/prv_id/bills/bill_id/refund/refund_id
- prv_id - числовой идентификатор провайдера (идентификатор, который отображается на партнерском сайте kassa.qiwi.com)
- bill_id - уникальный идентификатор счета в системе провайдера.
- refund_id - идентификатор операции, уникальный в рамках операций возврата счета bill_id. Формат идентификатора: строка от 1 до 9 символов, содержащая только прописные или строчные латинские буквы (a-z, A-Z) и цифры от 0 до 9

HEADERS
- Authorization: Basic ***
- Accept: text/json или Accept: application/json - формат ответа JSON
- Accept: text/xml или Accept: application/xml - формат ответа XML

Ответ ←

HTTP/1.1 200 OK
Content-Type: text/json
{
   "response": {
      "result_code": 0,
      "refund": {
         "refund_id": "899343443",
         "amount": "5.00",
         "status": "success",
         "error": 0
      }
   }
}

HTTP/1.1 401 Unauthorized
Content-Type: text/json
{
 "response": {
  "result_code": 150,
  "description": "Authorization failed"
  }
}

HEADERS
- Accept: text/json или Accept: application/json - формат ответа JSON
- Accept: text/xml или Accept: application/xml - формат ответа XML

Параметры

Параметр	Тип	Описание
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.

Статусы операций {#status}

Статусы оплаты счетов {#status_bills}

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

Статусы операции возврата {#status_refund}

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

Список ошибок {#errors}

Код	Описание	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	Кошелек временно заблокирован	-
934	Регион не поддерживается	+
1001	Запрещенная валюта для провайдера	+
1003	Не удалось получить курс конвертации для данной пары валют	-
1018	Страна не поддерживается	+
1019	Не удалось определить сотового оператора для мобильной коммерции	+
1419	Нельзя изменить данные счета – он уже оплачивается или оплачен	+

Признак означает, что при повторном запросе результат не изменится (ошибка не временная, проанализируйте данные запроса или обратитесь в Support).

FilesExpand file tree

_pull-payments-api_ru.html.md

Latest commit

History

_pull-payments-api_ru.html.md

File metadata and controls

Pull REST API {#pull-payments-api_ru}

Редактировать на GitHub

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

Средства для разработки {#node_sdk}

Авторизация {#auth_param}

Авторизация и работа с формами

Подробнее

Подробнее

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

Запрос → PUT

URL https://api.qiwi.com/api/v2/prv/prv_id/bills/bill_id

HEADERS

Параметры

Ответ ←

HEADERS

Параметры

Проверка статуса оплаты счета {#invoice-status}

Запрос → GET

URL https://api.qiwi.com/api/v2/prv/prv_id/bills/bill_id

HEADERS

Ответ ←

HEADERS

Параметры

Отмена неоплаченного счета {#cancel}

Запрос → PATCH

URL https://api.qiwi.com/api/v2/prv/prv_id/bills/bill_id

HEADERS

Ответ ←

HEADERS

Параметры

Возврат оплаченного счета {#refund}

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

Запрос → PUT

URL https://api.qiwi.com/api/v2/prv/prv_id/bills/bill_id/refund/refund_id

HEADERS

Ответ ←

HEADERS

Параметры

Проверка статуса возврата {#refund_status}

Запрос → GET

URL https://api.qiwi.com/api/v2/prv/prv_id/bills/bill_id/refund/refund_id

HEADERS

Ответ ←

HEADERS

Параметры

Статусы операций {#status}

Статусы оплаты счетов {#status_bills}

Статусы операции возврата {#status_refund}

Список ошибок {#errors}