Вопросы
api_help@qiwi.com
NAV

Универсальный платежный API

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

QIWI Универсальный платежный API открывает доступ к операциям со счетами на оплату из вашего приложения. Счет - универсальная заявка на оплату. Пользователь может оплатить его с помощью любого из доступных способов оплат.

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

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

Operation Flow

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

Авторизация

Запросы мерчанта авторизуются посредством секретного ключа API (SECRET_KEY).

--header "Authorization: Bearer MjMyNDQxMjM6NDUzRmRnZDQ0Mw=="
Параметр Описание Тип
SECRET_KEY Секретный ключ для авторизации в API предоставляет доступ к операциям на оплату услуг товаров из вашего приложения. String
PUBLIC_KEY Публичный ключ идентификации провайдера. Может быть предоставлен третьим лицам String

1. Платежная форма

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

REDIRECT →


GET /form/create?public_key=08hvq08yw4fqw&amount=100.0&success_url=http%3A%2F%2Ftest.ru%3F&email=m@ya.ru HTTP/1.1
Host: oplata.qiwi.com
Параметр Описание Тип С подписью Простой Обяз.
public_key Ключ идентификации провайдера, полученный в QIWI Кассе String + + +
bill_id Уникальный идентификатор счета в системе провайдера String(30) + + С подписью
amount Сумма, на которую выставляется счет, округленная в меньшую сторону до 2 десятичных знаков Number(6.2) + + С подписью
phone Идентификатор QIWI Кошелька, на который выставляется счет (в международном формате). String(20) + + -
email E-mail пользователя, куда будет отправлена ссылка для оплаты счета. String + + -
user_id Идентификатор пользователя в системе провайдера. String + + -
comment Комментарий к счету. String(255) + + -
extra_* Дополнительные данные счета. String(255) + + -
lifetime Дата, до которой счет будет доступен для оплаты. Если счет не будет оплачен до этой даты, ему присваивается финальный статус expired и последующая оплата станет невозможна.
Внимание! По истечении 45 суток от даты выставления счет автоматически будет переведен в финальный статус.
URL-закодированная строка
ГГГГ-ММ-ДДTччмм
+ + -
success_url URL для переадресации в случае успешного создания транзакции в QIWI Wallet. Ссылка должна вести на сайт провайдера. Если пользователь выбрал на платежной форме способ оплаты, отличный от оплаты с баланса QIWI Кошелька, то переадресация на сайт провайдера не выполняется. URL-закодированная строка + + -
fail_url URL для переадресации в случае неуспеха при создании транзакции в QIWI Wallet. Ссылка должна вести на сайт провайдера. Если пользователь выбрал на платежной форме способ оплаты, отличный от оплаты с баланса QIWI Кошелька, то переадресация на сайт провайдера не выполняется. URL-закодированная строка + + -
pay_source Способ оплаты по умолчанию, который необходимо отобразить пользователю при открытии платежной формы. Форма сама определяет наиболее удобный способ оплаты для клиента, поэтому не советуем указывать этот параметр.
Возможные значения:
qw – оплата с баланса QIWI Кошелька;
mobile – оплата с баланса мобильного телефона;
card – оплата банковской картой;
Если способ оплаты не доступен, пользователю отображается предупреждение, при этом на странице можно выбрать другие способы оплаты.
String - + -

2. Redirect на страницу партнера

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

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

Запрос → POST

POST /qiwi-notify.php HTTP/1.1
Accept: application/json
Content-type: application/json
X-Api-Signature-SHA256: J4WNfNZd***V5mv2w=
Host: server.ru

{
  "bill": {
    "bill_id": "a475c739-0561-4a23-9d18-a96934a7d690",
    "site_id":270304,
    "amount": 1,
    "currency": "RUB",
    "status":  {
      "value" : "PAID",
      "update_datetime" : "2017-12-27T16:01:00Z" },
    "user": {
      "phone": "79261234567",
      "user_id" : "dsfc2recd123sdadx3dscfewcr234esdcf23",
      "email" : "example@gmail.com"
    },
    "creation_datetime": "2017-08-17T09:56:02.241Z",
    "expiration_datetime": "2017-12-27T16:01:00Z",
    "version" : "3.0"
  }
}
HTTP/1.1 200 OK
Content-Type: application/json
{
 "error": 0
}
Параметр Описание Тип
bill_id Уникальный идентификатор счета в системе провайдера String(30)
site_id Идентификатор сайта провайдера в QIWI Кассе Number
amount Сумма счета, округленная до двух десятичных знаков в меньшую сторону Number(6.2)
currency Идентификатор валюты счета (Alpha-3 ISO 4217 код) String(3)
status Данные о статусе счета Object
status.value Строковое значение статуса String
status.update_datetime Дата обновления статуса URL-закодированная строка
ГГГГ-ММ-ДДTЧЧ:ММ:ССZ
user Данные о пользователе, на которого был выставлен счет Object
user.phone Номер телефона, на который был выставлен счет (если был указан при выставлении счета) String
user.email E-mail пользователя (если был указан при выставлении счета) String
user.user_id Идентификатор пользователя в системе провайдера (если был указан при выставлении счета) String
creation_datetime Дата создания счета URL-закодированная строка
ГГГГ-ММ-ДДTЧЧ:ММ:ССZ
expiration_datetime Срок оплаты счета URL-закодированная строка
ГГГГ-ММ-ДДTЧЧ:ММ:ССZ
comment Комментарий к счету String(255)
extras Дополнительные данные счета (если были указаны при выставлении счета). Object
version Версия уведомлений String

Ответ → POST

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

Заголовки

HTTP/1.1 200 OK
Content-Type: application/json

{
 "error": 0
}

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

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

HMAC sha256 от части полей, с разделителем | + secret_key

Пример:

X-Api-Signature-SHA256: J4WNfNZd***V5mv2w=

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

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

    {parameter1}|{parameter2}|…

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

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

    hash = HMAС(SHA256, secret_key_bytes, invoice_parameters_bytes) Где:

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

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

Код завершения Описание
0 Успех

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

Данный метод предназначен для получения текущего статуса оплаты счета клиентом.

Запрос → GET

GET /api/v3/bills/BILL-1 HTTP/1.1
Accept: application/json
Authorization: Bearer eyJ2ZXJzaW9uIjoicmVzdF92MyIsImRhdGEiOnsibWVyY2hhbnRfaWQiOjIwNDIsImFwaV91c2VyX2lkIjo1NjYwMzk3Miwic2VjcmV0IjoiQjIwODlDNkI5Q0NDNTdCNDQzNGHJK43JFJDK595FJFJMjlCRkFFRDM5OEZBOTBENDBEMiJ9fQ==
Host: api.qiwi.com

Ответ ←

HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8
{
  "bill": {
    "amount": "42.24",
    "site_id": 23044,
    "bill_id": "30192832",
    "comment": "Text comment",
    "creation_datetime": "2017-08-13T14:30:00.000Z",
    "currency": "RUB",
    "extras": {},
    "expiration_datetime": "2017-10-13T14:30:00.000Z",
    "pay_url": "https://oplata.qiwi.com/form/?invoice_uid=755ac889-6f94-4f82-a0b8-3dffc24afa60",
    "status": "WAITING",
    "status_update_datetime": "2017-09-03T14:30:00.000Z",
    "user": {
             "email": "test@qiwi.com",
             "phone": "79191234567",
             "user_id": "shop_user_id"
    }
  },
  "result_code": "SUCCESS"
}
HTTP/1.1 401 Unauthorized
Content-Type: application/json;charset=UTF-8
{
  "result_code": "AUTH_FAILED",
  "error_code": "CORE__150",
  "description": "Authorization failed",
  "datetime":"2017-06-28T21:57:45.540Z"
}
Параметр Тип Описание
result_code String Результат запроса
error_code String Если ответ содержит ошибку: Код ошибки
description String Если ответ содержит ошибку: Описание ошибки
datetime String Если ответ содержит ошибку: Системная дата обработки запроса
bill Object Данные о счете
bill.bill_id String Уникальный идентификатор счета в системе провайдера
bill.site_id Number Идентификатор сайта провайдера в QIWI Кассе
bill.amount String Сумма счета, округленная до 2 знаков после запятой в меньшую сторону.
bill.currency String Идентификатор валюты счета (Alpha-3 ISO 4217 код)
bill.status String Текущий статус счета
bill.status_update_datetime String Дата последнего изменения статуса счета
bill.extras Object Объект строковых дополнительных параметров, переданных партнером
bill.user Object Идентификаторы пользователя. Возможные опции: email, phone, user_id
bill.comment String Комментарий к счету
bill.creation_datetime Date Системная дата создания счета. Формат даты:
ГГГГ-ММ-ДДTчч:мм:ссTMZ
bill.pay_url String Ссылка для переадресации пользователя на созданную платежную форму
bill.expiration_datetime Date Срок действия созданной формы для оплаты. Формат даты:
ГГГГ-ММ-ДДTчч:мм:ссTMZ

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

Метод позволяет отменить неоплаченный клиентом счет.

Запрос → POST

POST /api/v3/bills/BILL-1/reject HTTP/1.1
Accept: application/json
Authorization: Bearer eyJ2ZXJzaW9uIjoicmVzdF92MyIsImRhdGEiOnsibWVyY2hhbnRfaWQiOjIwNDIsImFwaV91c2VyX2lkIjo1NjYwMzk3Miwic2VjcmV0IjoiQjIwODlDNkI5Q0NDNTdCNDQzNGHJK43JFJDK595FJFJMjlCRkFFRDM5OEZBOTBENDBEMiJ9fQ==
Host: api.qiwi.com
Content-Type: application/json; charset=utf-8
Accept: application/json

Ответ ←

HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8
{
  "bill": {
    "amount": "42.24",
    "site_id": 23044,
    "bill_id": "30192832",
    "comment": "Text comment",
    "creation_datetime": "2017-08-13T14:30:00.000Z",
    "currency": "RUB",
    "extras": {},
    "expiration_datetime": "2017-10-13T14:30:00.000Z",
    "pay_url": "https://oplata.qiwi.com/form/?invoice_uid=755ac889-6f94-4f82-a0b8-3dffc24afa60",
    "status": "WAITING",
    "status_update_datetime": "2017-09-03T14:30:00.000Z",
    "user": {
             "email": "test@qiwi.com",
             "phone": "79191234567",
             "user_id": "shop_user_id"
    }
  },
  "result_code": "SUCCESS"
}

HTTP/1.1 401 Unauthorized
Content-Type: application/json;charset=UTF-8
{
  "result_code": "AUTH_FAILED",
  "error_code": "error.code.auth.unauthorized",
  "description": "Authorization failed",
  "datetime":"2017-06-28T21:57:45.540Z"
}
Параметр Тип Описание
result_code String Результат запроса
error_code String Если ответ содержит ошибку: Код ошибки
description String Если ответ содержит ошибку: Описание ошибки
datetime String Если ответ содержит ошибку: Системная дата обработки запроса
bill Object Данные о счете
bill.bill_id String Уникальный идентификатор счета в системе провайдера
bill.site_id Number Идентификатор сайта провайдера в QIWI Кассе
bill.amount String Сумма счета, округленная до 2 знаков после запятой в меньшую сторону
bill.currency String Идентификатор валюты счета (Alpha-3 ISO 4217 код)
bill.status String Текущий статус счета
bill.status_update_datetime String Дата последнего изменения статуса счета
bill.extras Object Объект строковых дополнительных параметров, переданных партнером
bill.user Object Идентификаторы пользователя. Возможные опции: email, phone, user_id
bill.comment String Комментарий к счету
bill.creation_datetime Date Системная дата создания счета. Формат даты:
ГГГГ-ММ-ДДTчч:мм:ссTMZ
bill.pay_url String Ссылка на созданную платежную форму
bill.expiration_datetime Date Срок действия созданной формы для оплаты. Формат даты:
ГГГГ-ММ-ДДTчч:мм:ссTMZ

Результаты обработки запросов

Код Описание
AUTH_FAILED Ошибка авторизации запроса
BAD_REQUEST Ошибка в синтаксисе запроса
GENERAL_ERROR Техническая ошибка
RETRYABLE_ERROR Временная ошибка, запрос следует повторить еще раз
SUCCESS Успешное выполнение запроса

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

Статус Описание Финальный
WAITING Счет выставлен, ожидает оплаты -
PAID Счет оплачен +
REJECTED Счет отклонен +
UNPAID Ошибка при проведении оплаты. Счет не оплачен +
EXPIRED Время жизни счета истекло. Счет не оплачен +

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

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

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

Код Описание
error.code.internal.invoicing.core.error Ошибка получения данных от сервиса invoicing, попробуйте позже
error.code.internal.invoicing.api.error Внутренняя ошибка, попробуйте позже
error.code.api.invoice.not.found Счёт не найден
error.code.auth.unauthorized Неверные аутентификационные данные
error.code.default Произошла ошибка, попробуйте позже
error.code.internal.error Внутренняя ошибка
error.code.http.argument.type.mismatch Неверный запрос
error.code.http.code.conversion.failed Неверные параметры, измените запрос согласно документации API
error.code.http.media.type.not.acceptable Неверный тип данных
error.code.http.media.type.not.supported Неподдерживаемый тип данных
error.code.http.message.conversion.failed Неверный запрос
error.code.http.method.not.supported HTTP метод не поддерживается
error.code.http.missing.request.parameter Неверный запрос: отсутствуют необходимые параметры
error.code.http.url.not.found Ресурс не найден
error.code.validation.error Неверные параметры, измените запрос согласно документации API