Вопросы
bss@qiwi.com
NAV Navbar
Примеры

Обзор протокола

Последнее обновление: 2022-04-18| Версия 1.8 | Редактировать на GitHub

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

Термины и сокращения

Ключ доступа к API — Символьная строка для авторизации мерчанта в API согласно стандарту OAuth 2.0 RFC 6749 RFC 6750.

Платежный токен — Символьная строка, созданная по данным карты для безакцептных платежей.

API: Application Programming Interface — набор готовых методов, предоставляемых приложением (системой) для использования во внешних программных продуктах.

REST: Representational State Transfer — архитектурный стиль взаимодействия компонентов распределённого приложения в сети.

JSON: JavaScript Object Notation — текстовый формат обмена данными, основанный на JavaScript RFC 7159.

3DS: 3-D Secure — протокол защиты карточных данных, используемый для аутентификации держателя банковской карты во время совершения платежной операции через интернет. QIWI поддерживает как версию 3DS 1.0, так и версию 3DS 2.0 протокола.

ТСП, Мерчант — Торгово-сервисное предприятие.

MPI: Merchant Plug-In — модуль, выполняющий 3DS аутентификацию покупателя.

PCI DSS: Payment Card Industry Data Security Standard — стандарт безопасности данных индустрии платёжных карт, учреждённым международными платёжными системами Visa, MasterCard, American Express, JCB и Discover.

Начало работы

Чтобы начать работу с Протоколом, выполните следующие шаги.

Шаг 1. Оставьте заявку на подключение b2b.qiwi.com

После обработки заявки менеджер поддержки обсудит с вами возможные варианты подключения, соберет необходимые документы и запустит процесс интеграции.

Шаг 2. Получите доступ к личному кабинету

При подключении к Протоколу приема платежей вы получаете уникальный идентификатор siteId и доступ в Личный кабинет. Параметры доступа отправляются на указанный при регистрации email.

Шаг 3. Выпустите ключ доступа к API

Ключ доступа к API используется для взаимодействия с API. Выпустите ключ API в Личном кабинете в разделе Настройки.

Шаг 4. Протестируйте взаимодействие

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

Когда интеграция на вашей стороне закончена, мы переводим ваш идентификатор siteId в производственный режим. В производственном режиме выполняются реальные списания средств с карт.

Способы подключения

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

Доступные методы оплаты

Метод Платежная форма QIWI Платежная форма мерчанта
Банковская карта* ✓ ✓
Оплата платежным токеном ✓ ✓
Apple Pay ✓ ✓
Google Pay ✓ ✓
Yandex Pay × ✓
Оплата через СБП × ✓
Оплата с баланса КИВИ Кошелька ✓ ✓**

* — метод оплаты доступен по умолчанию, другие методы оплаты подключаются по запросу.

** — посредством выпуска платежного токена для КИВИ кошелька.

Типы операций

В Протоколе доступны следующие операции:

Общая схема проведения платежа и взаиморасчетов

sequenceDiagram participant customer as Покупатель participant store as Магазин мерчанта participant ipsstore as Кредитная организация
мерчанта participant qb as QIWI participant ips as Платежная система participant ipscust as Кредитная организация
Покупателя
Эмитент или банк-отправитель customer->>store:Старт оплаты store->>qb:Платеж qb->>ips:Авторизация платежа ips->>ipscust:Авторизация платежа rect rgb(237, 243, 255) Note over ipsstore, ipscust:Взаиморасчеты ipscust->>ips:₽₽₽ ips->>qb:₽₽₽ qb->>ipsstore:₽₽₽ end

Формат взаимодействия

API Протокола приема платежей основано на принципах REST-архитектуры.

API в качестве основного протокола использует HTTP-запросы.

API endpoint:

https://api.qiwi.com/partner/

Параметры API помещаются в JSON-тело запроса. В GET-запросах параметры помещаются в URL запроса.

API всегда возвращает ответ в формате JSON.

Авторизация

Пример запроса с авторизацией

curl -X PUT https://api.qiwi.com/partner/v1/sites/{site_id}/payments/{payment_id} \
     --oauth2-bearer <Ключ API>

Пример заголовка авторизации

Authorization: Bearer 5c4b25xx93aa435d9cb8cd17480356f9

Для авторизации запросов к API используется стандарт OAuth 2.0 согласно RFC 6750. Указывайте значение ключа доступа к API в HTTP-заголовке Authorization как

Bearer <Ключ API>

Тестовый режим

При подключении ваш идентификатор siteId находится в тестовом режиме. В этом режиме вы можете проводить операции без списания средств с банковской карты. Также можно запросить переключение в режим тестирования любого своего siteId, либо добавление нового siteId в режиме тестирования через вашего сопровождающего менеджера.

Для тестирования операций оплаты используются URL протокола.

Тестовый режим для метода оплаты с баланса КИВИ Кошелька не предусмотрен.

Когда интеграция на вашей стороне закончена, мы переводим siteId в производственный режим. В этом режиме выполняются реальные списания средств с карт.

При переходе в производственный режим перевыпускать ключ доступа к API не нужно.

При необходимости измените постоянный URL для обработки уведомлений с тестового (например, https://your-shop-test.ru/callbacks) на производственный (например, https://your-shop-prod.ru/callbacks) в Личном кабинете.

Оплата картой в тестовом режиме

В тестовом режиме можно использовать любой номер карты, удовлетворяющий алгоритму Luhn.

Тестовые номера карт

В тестовом режиме из валют (параметр currency) разрешен только рубль РФ (643).

CVV в тестовом режиме может быть любым (произвольные 3 цифры).

Для тестирования различных вариантов оплаты и ответов необходимо использовать различные сроки действия карты:

В тестовой среде установлено ограничение на сумму и количество тестовых операций. По умолчанию максимальная сумма тестовых транзакций — 10 рублей. Максимум — 100 транзакций в сутки (учитываются операции за текущие сутки, время по МСК). Учитываются операции с суммой не более установленного лимита.

Для проведения операции с 3DS необходимо использовать строку unknown name в имени держателя карты. Прохождение 3DS в режиме тестирования можно проверить только при вводе номера реальной карты.

Оплата через СБП в тестовом режиме

Для тестирования различных вариантов оплаты и ответов указывайте разные суммы платежа (поле amount):

Платеж через форму QIWI

При подключении платежей через форму QIWI покупателю доступен только способ оплаты банковскими картами. Другие способы оплаты доступны по запросу:

Чтобы выполнить платеж через форму QIWI, выставите счет покупателю. Воспользуйтесь выставлением счета через API или перенаправьте покупателя на форму QIWI по прямой ссылке с параметрами счета.

Процесс платежа

sequenceDiagram participant customer as Покупатель participant store as Магазин participant qb as QIWI (эквайер) participant ips as Эмитент customer->>store:Выбор товаров, Старт оплаты activate store store->>qb:Выставление счета
Одношаговый платеж — все способы оплаты
Двухшаговый платеж — только карты activate qb qb->>store:Ссылка на платежную форму QIWI (payUrl) store->>customer:Переадресация покупателя на payUrl customer->>qb:Открытие платежной формы,
выбор способа оплаты,
указание платежных данных для выбранного способа qb->>customer:Аутентификация покупателя:
Для карт — 3-D Secure customer->>qb:Аутентификация qb->>ips:Запрос списания денежных средств activate ips ips->>qb:Статус операции qb->>store:Уведомление о статусе операции qb->>customer: Переадресация на страницу статуса платежа (successUrl) rect rgb(237, 243, 255) Note over store, ips:Двухшаговый платеж store->>qb:Подтверждение операции (capture) qb->>ips:Подтверждение списания deactivate ips qb->>store:Уведомление о подтверждении платежа end deactivate qb deactivate store

Интеграция c Платежной формой QIWI без использования API

Это простой способ интеграции с Платежной формой QIWI. При открытии формы покупателю автоматически выставляется счет. Параметры счета передаются в открытом виде в ссылке на форму. Покупателю отображается платежная форма с выбором способов оплаты.

Для вызова формы в ссылке необходимо указывать ключ PUBLIC_KEY. Для каждого siteId выпускается уникальный ключ. Ключ можно посмотреть в Личном кабинете в разделе Настройки.

При оплате счета, выставленного таким способом, платеж автоматически авторизуется без участия мерчанта. Так как используется двухшаговая схема, то для завершения платежа необходимо выполнить запрос Подтверждение платежа или подтвердить платеж через Личный кабинет.

По умолчанию сервис QIWI ожидает подтверждения платежа в течение 72 часов. По истечении срока выполняется автоматическое подтверждение платежа.

REDIRECT →

Выставление счета с передачей суммы платежа

https://oplata.qiwi.com/create?publicKey=5nAq6abtyCz4tcDj89e5w7Y5i524LAFmzrsN6bQTQ3ceEvMvCq55ToeErzhvK6rVkQLaCrYUQcYF5QkS8nCrjnPsLQgsLxqrpQgJ7hg2ZHmEHXFjaG8qjvgcep&extras[cf1]=Order_123&extras[cf3]=winnie@pooh.ru&readonly_extras=cf1&comment=some%20comment&amount=100.00

Выставление счета без указания суммы платежа (сумму заполняет покупатель)

https://oplata.qiwi.com/create?publicKey=5nAq6abtyCz4tcDj89e5w7Y5i524LAFmzrsN6bQTQ3ceEvMvCq55ToeErzhvK6rVkQLaCrYUQcYF5QkS8nCrjnPsLQgsLxqrpQgJ7hg2ZHmEHXFjaG8qjvgcep&extras[cf1]=Order_123&extras[cf3]=winnie@pooh.ru&readonly_extras=cf1
Параметр Описание Тип Обяз.
publicKey Ключ идентификации мерчанта String +
billId Уникальный идентификатор счета в системе мерчанта. Он должен генерироваться на вашей стороне любым способом. Идентификатором может быть любая уникальная последовательность букв или цифр. Также разрешено использование символа подчеркивания (_) и дефиса (-). Если не указан, то при каждом переходе по ссылке будет создаваться новый счет. URL-закодированная строка String(200) -
amount Сумма покупки, округленная в меньшую сторону до 2 десятичных знаков (всегда в рублях) Number(6.2) -
phone Номер телефона покупателя (в международном формате) URL-закодированная строка -
email E-mail покупателя URL-закодированная строка -
comment Комментарий к счету URL-закодированная строка String(255) -
successUrl URL для переадресации в случае успешной оплаты. Ссылка должна вести на сайт мерчанта. URL-закодированная строка -
extras[cf1] Дополнительное поле с произвольной информацией, дополняющей данные счета URL-закодированная строка -
extras[cf2] Дополнительное поле с произвольной информацией, дополняющей данные счета URL-закодированная строка -
extras[cf3] Дополнительное поле с произвольной информацией, дополняющей данные счета URL-закодированная строка -
extras[cf4] Дополнительное поле с произвольной информацией, дополняющей данные счета URL-закодированная строка -
extras[cf5] Дополнительное поле с произвольной информацией, дополняющей данные счета URL-закодированная строка -
readonly_extras Список дополнительных полей, которые должны быть недоступны для изменения покупателем на платежной форме Строка, разделитель имен полей ,. Пример: cf1,cf3 -

По умолчанию, после оплаты счета автоматически выполняется аутентификация покупателя. Завершение аутентификации также происходит автоматически.

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

Пример выставления счета с оплатой через холдирование (двухшаговый платеж)

PUT /partner/payin/v1/sites/23044/bills/893794793973 HTTP/1.1
Accept: application/json
Authorization: Bearer 5c4b25xx93aa435d9cb8cd17480356f9
Content-type: application/json
Host: api.qiwi.com

{
   "amount": {  
     "currency": "RUB",  
     "value": 42.24
   },
   "comment": "Spasibo",
   "expirationDateTime": "2019-09-13T14:30:00+03:00",
   "customFields": {}
}

Пример выставления счета с оплатой без авторизации Покупателя (одношаговый платеж)

PUT /partner/payin/v1/sites/23044/bills/893794793973 HTTP/1.1
Accept: application/json
Authorization: Bearer 5c4b25xx93aa435d9cb8cd17480356f9
Content-type: application/json
Host: api.qiwi.com

{
   "amount": {  
     "currency": "RUB",  
     "value": 100.00
   },
   "expirationDateTime": "2018-04-13T14:30:00+03:00",
   "flags": [
     "SALE"
    ]
}

Пример уведомления об оплате счета

{
  "payment":{
    "paymentId":"804900",  <==paymentId, необходимый для подтверждения
    "type":"PAYMENT",
    "createdDateTime":"2020-11-28T12:58:49+03:00",
    "status":{
        "value":"SUCCESS",
        "changedDateTime":"2020-11-28T12:58:53+03:00"
    },
    "amount":{
      "value":100.00,
      "currency":"RUB"
    },
    "paymentMethod":"..",
    "customer":"..",
    "gatewayData":"..",
    "billId":"autogenerated-a51d0d2c-6c50-405d-9305-bf1c13a5aecd",
    "flags":[]
  },
  "type":"PAYMENT",
  "version":"1"
}

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

  1. Чтобы выставить счет для оплаты через холдирование средств на карте (двухшаговый платеж), передайте в запросе API Создание счета:

    • ключ API;
    • сумму счета (amount);
    • дату, до которой необходимо оплатить счет (expirationDateTime);
    • (опционально) другую информацию о счете — комментарий (comment), данные о покупателе (customer, address) и получателе платежа (receiverData), дополнительные данные по операции (customFields).

    Вы также можете выставить счет для оплаты без дополнительной авторизации покупателя (одношаговый платеж). Для этого добавьте в запрос API дополнительный параметр "flags":["SALE"]. Если не передать этот параметр, то будет выполнено безусловное холдирование средств для оплаты счета.

  2. Перенаправьте покупателя на Платежную форму по ссылке из параметра payUrl ответа.
  3. Дождитесь завершения платежа: вам придет уведомление, или периодически отправляйте запрос API Статус счета, чтобы получить информацию о платеже.

Подтверждение платежа

PUT /partner/payin/v1/sites/{siteId}/payments/804900/capture/bxwd8096 HTTP/1.1
Accept: application/json
Authorization: Bearer 5c4b25xx93aa435d9cb8cd17480356f9
Content-type: application/json
Host: api.qiwi.com

Для двухшагового сценария (платеж с холдированием средств) требуется выполнить подтверждение платежа. Возмещение формируется только после подтверждения.

Чтобы подтвердить платеж в двухшаговом сценарии:

  1. Получите идентификатор платежа paymentId:
  2. Отправьте запрос API Подтверждение платежа с полученным paymentId.

Платежный токен

Выставление счета с оплатой платежным токеном

PUT /partner/payin/v1/sites/test-02/bills/1815 HTTP/1.1
Accept: application/json
Authorization: Bearer 7uc4b25xx93xxx5d9cb8cd17480356f9
Content-type: application/json
Host: api.qiwi.com

{
   "amount": {  
     "currency": "RUB",  
     "value": 100.00
   },
   "comment": "Text comment",
   "expirationDateTime": "2018-04-13T14:30:00+03:00",
   "customer": {
     "account": "token234"
   },
   "customFields": {
    "cf1": "Some data",
    "FROM_MERCHANT_CONTRACT_ID": "1234"
   }  
   }
}

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

О выпуске платежного токена читайте в разделе по ссылке.

Чтобы выставить счет для оплаты платежным токеном:

  1. Передайте в запросе API Создание счета следующие данные:
    • ключ API;
    • сумму счета (amount);
    • дату, до которой необходимо оплатить счет (expirationDateTime);
    • идентификатор покупателя, для которого был выпущен платежный токен, в параметре customer.account. Без этого параметра оплата платежным токеном невозможна.
    • (опционально) другую информацию о счете.
  2. Перенаправьте покупателя на Платежную форму по ссылке из параметра payUrl ответа.

  3. Если для покупателя был выпущен один или несколько платежных токенов, то на Платежной форме отобразится список его привязанных карт.

    qiwi-form-tokens

    Для оплаты покупателю достаточно выбрать одну из своих привязанных карт. При этом не понадобится указывать карточные данные и проходить проверку 3-D Secure.

Для списания средств по платежному токену без участия Покупателя воспользуйтесь методом API Платеж. См. подробнее описание использования платежного токена на Платежной форме мерчанта.

Перенаправление на форму QIWI

Пример ответа с payUrl

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

{
    "siteId": "test-01",
    "billId": "gg",
    "amount": {
        "currency": "RUB",
        "value": 42.24
    },
    "status": {
        "value": "WAITING",
        "changedDateTime": "2019-08-28T16:26:36.835+03:00"
    },
    "customFields": {},
    "comment": "Spasibo",
    "creationDateTime": "2019-08-28T16:26:36.835+03:00",
    "expirationDateTime": "2019-09-13T14:30:00+03:00",
    "payUrl": "https://oplata.qiwi.com/form/?invoice_uid=78d60ca9-7c99-481f-8e51-0100c9012087"
}

Чтобы покупатель смог оплатить выставленный счет, перенаправьте его на Платежную форму по ссылке из поля payUrl ответа на запрос выставления счета.

По умолчанию, на Платежной форме QIWI 3-D Secure покупателя обязателен.

Пример ссылки с successUrl

https://oplata.qiwi.com/form?invoiceUid=606a5f75-4f8e-4ce2-b400-967179502275&successUrl=https://example.com/payments/#introduction

К ссылке можно добавить следующий параметр:

Параметр Описание Тип
successUrl URL для переадресации в случае успешной оплаты. Переадресация произойдет после успешной 3DS аутентификации. Ссылку необходимо зашифровать в utf-8 формат. URL-закодированная строка

Пример обработчика событий iframe

window.addEventListener('message', function (event) {
    switch (event.data) {
        case 'INITIALIZED':
            // Форма загружена
            break;
        case 'PAYMENT_ATTEMPT':
            // Попытка платежа
            break;
        case 'PAYMENT_SUCCEEDED':
            // Платеж прошел успешно
            break;
        case 'PAYMENT_FAILED':
            // Платеж не прошел
            break;
    }
}, false)

При открытии ссылки в <iframe>:

<iframe src="<ссылка payUrl> ..." />

вы можете использовать метод postMessage для отслеживания состояния формы. Возможные значения состояния:

Чтобы покупателю на Платежной форме были доступны методы Apple Pay/Google Pay при открытии ссылки в <iframe>, рекомендуем использовать параметр allow:

<iframe allow="payment" src="<ссылка payUrl> ..." />

Настройка Платежной формы

Внешний вид Платежной формы можно настроить в соответствии с вашим стилем, включая лого, фон и цвет кнопок. Для этого обратитесь в Службу поддержки payin@qiwi.com и предоставьте следующие данные:

Необязательные данные для настройки:

Пример передачи параметра стиля при выставлении счета

PUT /partner/payin/v1/sites/23044/bills/893794793973 HTTP/1.1
Accept: application/json
Authorization: Bearer 5c4b25xx93aa435d9cb8cd17480356f9
Content-type: application/json
Host: api.qiwi.com

{
   "amount": {
     "currency": "RUB",
     "value": 100.00
   },
   "comment": "Text comment",
   "expirationDateTime": "2018-04-13T14:30:00+03:00",
   "customer": {},
   "customFields": {
     "themeCode":"merchant01-theme01"
   }
}

Чтобы применить ваш стиль на Платежной форме, передайте при выставлении счета в поле "themeCode" JSON-объекта customFields псевдоним стиля, который вы указали при настройке. Например:

"themeCode":"merchant01-theme01".

Название псевдонима стиля регистрозависимое.

Customer form

Платеж через форму мерчанта

При подключении платежей через собственную платежную форму по умолчанию сразу доступен способ оплаты Банковские карты. Другие способы оплаты доступны по запросу:

Процесс платежа

sequenceDiagram participant customer as Покупатель participant store as Магазин participant qb as QIWI (эквайер) participant ips as Эмитент customer->>store:Выбор товаров, Старт оплаты,
ввод платежных данных activate store store->>qb:Платеж
Одношаговый платеж — все способы оплаты
Двухшаговый платеж — только карты, Apple Pay, Google Pay activate qb qb->>store:Статус операции, данные для 3DS или QR-код СБП rect rgb(237, 243, 255) Note over customer, ips:3-D Secure store->>customer:Переадресация покупателя на acsUrl или в приложение банка activate ips ips->>customer:Аутентификация покупателя:
3DS — карты,
СБП — подтверждение операции в интерфейсе эмитента карты customer->>ips:Аутентификация ips->>store:Результат аутентификации (PaRes) store->>qb:Завершение аутентификации (complete) end qb->>ips:Запрос списания денежных средств activate ips ips->>qb:Статус операции qb->>store:Уведомление о статусе операции rect rgb(237, 243, 255) Note over store, ips:Двухшаговый платеж store->>qb:Подтверждение операции (capture) qb->>ips:Подтверждение списания deactivate ips qb->>store:Уведомление о подтверждении платежа end deactivate qb deactivate store

Чтобы создать платеж, передайте в запросе API Платеж:

Банковская карта

Протокол приема платежей поддерживает как двухшаговый платеж с холдированием средств на карте покупателя, так и одношаговый платеж без авторизации покупателя.

Создание платежа

Пример платежа с холдированием (двухшаговый платеж)

PUT /partner/payin/v1/sites/test-01/payments/1811 HTTP/1.1
Accept: application/json
Authorization: Bearer 5c4b25xx93aa435d9cb8cd17480356f9
Content-type: application/json
Host: api.qiwi.com

{
  "amount": {
    "currency": "RUB",
    "value": 1.00
  },
  "paymentMethod" : {
    "type" : "CARD",
    "pan" : "4444443616621049",
    "expiryDate" : "12/19",
    "cvv2" : "123",
    "holderName" : "unknown cardholder"
  }
}

Пример платежа с немедленной оплатой (одношаговый платеж)

PUT /partner/payin/v1/sites/test-01/payments/1811 HTTP/1.1
Accept: application/json
Authorization: Bearer 5c4b25xx93aa435d9cb8cd17480356f9
Content-type: application/json
Host: api.qiwi.com

{
  "amount": {
    "currency": "RUB",
    "value": 1.00
  },
  "paymentMethod" : {
    "type" : "CARD",
    "pan" : "4444443616621049",
    "expiryDate" : "12/19",
    "cvv2" : "123",
    "holderName" : "unknown cardholder"
  },
  "flags": [ "SALE" ]
}

Чтобы инициировать платеж с предварительным холдированием средств на карте (двухшаговый платеж), передайте в запросе API Платеж:

В двухшаговом платеже возмещение формируется только после подтверждения платежа.

Для платежа без авторизации (одношаговый платеж) укажите в запросе API Платеж параметр "flags":["SALE"]. Если не передать этот параметр, то будет выполнено безусловное холдирование средств для выполнения платежа.

Ожидание аутентификации покупателя (3-D Secure)

Пример ответа с требованием аутентификации покупателя

{
    "paymentId": "1811",
    "billId": "autogenerated-a29ea8c9-f9d9-4a60-87c2-c0c4be9affbc",
    "createdDateTime": "2019-08-15T13:28:26+03:00",
    "amount": {
        "currency": "RUB",
        "value": 1.00
    },
    "capturedAmount": {
        "currency": "RUB",
        "value": 0.00
    },
    "refundedAmount": {
        "currency": "RUB",
        "value": 0.00
    },
    "paymentMethod": {
        "type": "CARD",
        "maskedPan": "444444******1049",
        "rrn": "123",
        "authCode": "181218",
        "type": "CARD"
    },
    "status": {
        "value": "WAITING",
        "changedDateTime": "2019-08-15T13:28:26+03:00"
    },
    "requirements" : {
        "threeDS" : {
          "pareq" : "eJyrrgUAAXUA+Q==",
          "acsUrl" : "https://test.paymentgate.ru/acs/auth/start.do"
        }
    }
}

Перенаправление для аутентификации 3-D Secure

<form name="form" action="{ACSUrl}" method="post" >
        <input type="hidden" name="TermUrl" value="{TermUrl}" >
        <input type="hidden" name="MD" value="{MD}" >
        <input type="hidden" name="PaReq" value="{PaReq}" >
</form>

Завершение аутентификации покупателя

POST /partner/payin/v1/sites/test-01/payments/1811/complete HTTP/1.1
Accept: application/json
Authorization: Bearer 5c4b25xx93aa435d9cb8cd17480356f9
Content-type: application/json
Host: api.qiwi.com

{
  "threeDS": {
    "pares": "eJzVWFevo9iyfu9fMZrzaM0QjWHk3tIiGptgooE3cgabYMKvv3jvTurTc3XOfbkaJMuL...."
  }
}

Если требуется 3DS аутентификация покупателя, понадобится пройти дополнительную проверку у эмитента. В этом случае в ответе на запрос платежа добавляется объект requirements.threeDS с полями:

Чтобы получить результат проверки (PaReS), сделайте POST-запрос на URL сервера аутентификации 3-D Secure с параметрами:

Чтобы сохранять обратную совместимость, использование протокола 3-D Secure 1.0 или 3-D Secure 2.0 не влияет на вашу интеграцию с API.

Информация о покупателе передаётся в платежную систему карты. Банк-эмитент либо предоставляет разрешение на списание средств без аутентификации (frictionless flow), либо принимает решение о необходимости аутентификации с помощью одноразового пароля (challenge flow). После прохождения проверки покупатель перенаправляется по адресу TermUrl с зашифрованным результатом проверки в параметре PaRes.

Чтобы завершить аутентификацию покупателя, передайте в запросе API Завершение аутентификации клиента:

Подтверждение платежа

Пример уведомления

{
  "payment":{
    "paymentId":"804900",  <==paymentId, необходимый для подтверждения
    "type":"PAYMENT",
    "createdDateTime":"2020-11-28T12:58:49+03:00",
    "status":{
        "value":"SUCCESS",
        "changedDateTime":"2020-11-28T12:58:53+03:00"
    },
    "amount":{
      "value":100.00,
      "currency":"RUB"
    },
    "paymentMethod":{
      "type":"CARD",
      "maskedPan":"444444XXXXXX4444",
      "rrn":null,
      "authCode":null,
      "type":"CARD"
    },
    "customer":{
      "phone":"75167693659"
    },
    "gatewayData":{
      "type":"ACQUIRING",
      "eci":"6",
      "authCode":"181218"
    },
    "billId":"autogenerated-a51d0d2c-6c50-405d-9305-bf1c13a5aecd",
    "flags":[]
  },
  "type":"PAYMENT",
  "version":"1"
}

Подтверждение платежа

PUT /partner/payin/v1/sites/{siteId}/payments/804900/capture/bxwd8096 HTTP/1.1
Accept: application/json
Authorization: Bearer 5c4b25xx93aa435d9cb8cd17480356f9
Content-type: application/json
Host: api.qiwi.com

Это действие требуется только для двухшагового платежа с холдированием.

Чтобы подтвердить платеж:

Платежный токен

Использование платежного токена в запросе платежа

PUT /partner/payin/v1/sites/test-02/payments/1815 HTTP/1.1
Accept: application/json
Authorization: Bearer 7uc4b25xx93xxx5d9cb8cd17480356f9
Content-type: application/json
Host: api.qiwi.com

{
  "amount": {
    "currency": "RUB",
    "value": 2000.00
  },
  "paymentMethod" : {
    "type": "TOKEN",
    "paymentToken" : "66aebf5f-098e-4e36-922a-a4107b349a96"
  },
  "customer": {
        "account": "token324"
  }
}

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

О выпуске платежного токена читайте в разделе по ссылке.

Чтобы оплатить покупку платежным токеном, передайте в запросе API Платеж:

Параметр Тип Описание
paymentMethod.type String Тип операции. Только TOKEN
paymentMethod.paymentToken String Строка платежного токена
customer.account String Уникальный идентификатор Покупателя в системе ТСП, для которого выпущен платежный токен. Без данного параметра оплата платежным токеном невозможна.

Покупатель не будет указывать свои карточные данные и проходить проверку 3-D Secure.

Apple Pay

Оплата покупок с Apple Pay происходит без ввода данных карты. Технология работает в мобильных приложениях и браузере Safari на iPhone, iPad, Apple Watch и MacBook.

Для включения способа оплаты Apple Pay обратитесь к вашему сопровождающему менеджеру.

Для интеграции Apple Pay на Платежную страницу мерчанта понадобится выполнить интеграцию с Apple. Это позволит верифицировать сайт мерчанта и получать платежные данные покупателя. Требования для интеграции Apple Pay на веб-странице:

Подробнее об интеграции см. на сайте Apple.

Процесс платежа

Процесс выполнения платежа Apple Pay в API:

  1. Создание платежной сессии Apple Pay.
  2. Валидация ТСП в Apple Pay.
  3. Получение зашифрованных платежных данных от Apple Pay.
  4. Расшифровка платежных данных (опционально).
  5. Отправка запроса на списание средств в QIWI:

Как отправлять платеж с зашифрованными данными

Пример JSON-объекта 'paymentMethod' для платежа Apple Pay

"paymentMethod": {
  "type": "APPLE_PAY_TOKEN",
  "paymentData": {
    "version":"EC_v1",
    "data":"IaD7LKDbJsOrGTlNGkKUC95Y+4an2YuN0swstaCaoovlj8dbgf16FmO5j4AX80L0xsRQYKLUpgUHbGoYF26PbraIdZUDtPtja4HdqDOXGESQGsAKCcRIyujAJpFv95+5xkNldDKK2WTe28lHUDTA9bykIgrvasYaN9VWnS92i2CZPpsI7yu13Kk3PrUceuA3Fb6wFgJ0l7HXL1RGhrA7V5JKReo/EwikMsK8AfChK7pvWaB51SsMvbMJF28JnincfVX39vYHdzEwpjSPngNiszGqZGeLdqNE3ngkoEK1AW2ymbYkIoy9KFdXayekELR6hQWnL4MCutLesLjKhyTN26fxBamPHzAf/IczAdWBDq2P/59jheIGrnK30slJJcr1Bocb8rqojyaVZIY+Xk24Nc6dvSdJhfDDyhX56pn5YtWOxWuVOT0tZSJvxBN/HeIuYcNG6R9u7CHpcelsi4I8O+1gruKKZQHweERG2DyCmoUO9zlajOSm",
    "header": {
       "ephemeralPublicKey":"MFkwEwYHKoZIzj0CAQYIKoZIzj0DAQcDQgAEzLx7FJhw1Z1PmxOLMTQBs1LgKEUT6 hcxLlT8wGrzwyY8tKeG+VPSjryVkTFYECrj+5r28PJWtmvn/unYhbYDaQ==",
       "publicKeyHash":"OrWgjRGkqEWjdkRdUrXfiLGD0he/zpEu512FJWrGYFo=",
       "transactionId":"1234567890ABCDEF"
     },
    "signature":"ZmFrZSBzaWduYXR1cmU="
  }
}

Для отправки платежных данных в QIWI передайте в запросе API Платеж объект paymentMethod с параметрами:

Как отправлять платеж с расшифрованными данными

Пример отправки расшифрованных платежных данных Apple Pay

"paymentMethod": {
  "type": "CARD",
  "pan": "4444443616621049",
  "expiryDate": "12/19",
  "holderName": "Apple Pay",
  "external3dSec": {
    "type": "APPLE_PAY",
    "onlinePaymentCryptogram": "AOLqt9wP++/WAzN+is7YAoABFA==",
    "eciIndicator": "05"
  }
}

Используйте этот способ, если платежный токен Apple расшифрован на вашей стороне.

Для отправки платежных данных в QIWI передайте в запросе API Платеж параметры в объекте paymentMethod:

Google Pay

В способе оплаты Google Pay™ поддерживаются платежи с карт Visa и MasterCard.

Для включения способа оплаты Google Pay™ обратитесь к вашему сопровождающему менеджеру.

Процесс интеграции Google Pay™ на платежную страницу мерчанта:

  1. Выполните требования Google Pay™ WEB для приема шифрованных платежных данных. В том числе, проверьте контрольный список интеграции Google Pay™ для веб-сайтов и правила фирменного оформления Google Pay™ для веб-сайтов.
  2. Для интеграции необходимо выполнить требования к отправке данных:
  3. Подайте заявку на доступ к рабочей версии. В заявке на доступ укажите следующие данные:
    • Tokenization Method — Gateway;
    • Payment Processor or Gateway — qiwi;
    • Merchant Name — выдается технической поддержкой компании QIWI.
  4. Google проверит работу вашей платежной формы в рабочей среде и даст одобрение на запуск.

Как отправлять платеж с зашифрованными данными

Пример объекта paymentMethod

"paymentMethod": {
    "type": "GOOGLE_PAY_TOKEN",
    "paymentToken": "eJxVUtuK2zAQfd+vCHGShS9mS0hb8YChjabx……"
    }

Пример шифрования/проверки токена для Google Pay

import zlib
import base64

token = 'Hello world'

token_bytes = token.encode('utf-8')
token_deflated = zlib.compress(token_bytes)
token_base64 = base64.b64encode(token_deflated)
token_result = token_base64.decode('utf-8')

resp_base64 = token_result.encode('utf-8')
resp_deflated = base64.b64decode(resp_base64)
resp_bytes = zlib.decompress(resp_deflated)
resp_token = resp_bytes.decode('utf-8')

print('resp_token: ', resp_token)

>> resp_token: 'Hello world'

Отправьте платежные данные в QIWI. Для этого передайте в запросе API Платеж параметры в объекте paymentMethod:

Полученная в результате закодированная строка является значением поля paymentToken.

Как отправлять платеж с расшифрованными данными

Пример платежа с данными расшифрованного платежного токена Google Pay (метод CRYPTOGRAM_3DS)

{
  "paymentMethod": {
    "type": "CARD",
    "pan": "4444443616621049",
    "expiryDate": "12/19",
    "holderName": "Google Pay",
    "external3dSec": {
      "type": "GOOGLE_PAY",
      "cryptogram": "AOLqt9wP++YAoABFA==",
      "eciIndicator": "05"
    }
  },
  "amount": {
    "value": 5900.00,
    "currency": "RUB"
  },
  "flags": [
    "SALE"
  ],
  "customer": {
    "account": "79111111111",
    "email": "test@qiwi.com",
    "phone": "79111111111"
  }
}

Пример платежа с данными расшифрованного платежного токена Google Pay (метод PAN_ONLY)

{
  "paymentMethod": {
    "type": "CARD",
    "pan": "4444443616621049",
    "expiryDate": "12/19",
    "holderName": "Google Pay",
    "external3dSec": {
      "type": "GOOGLE_PAY"
    }
  },
  "amount": {
    "value": 760.00,
    "currency": "RUB"
  },
  "flags": [
    "SALE"
  ],
  "customer": {
    "account": "11111",
    "email": "test@qiwi.com",
    "phone": "79111111111"
  }
}

При отправке платежа с расшифрованным платежным токеном Google, формат платежных данных зависит от способа аутентификации, указанного в поле authMethod токена:

Yandex Pay

Оплата покупок с Yandex Pay происходит без ввода данных карты.

Для включения способа оплаты Yandex Pay обратитесь к вашему сопровождающему менеджеру.

Как отправлять платеж

Пример платежа с данными расшифрованного платежного токена Yandex Pay (метод CLOUD_TOKEN)

{
  "paymentMethod": {
    "type": "CARD",
    "pan": "4444443616621049",
    "expiryDate": "12/19",
    "holderName": "Yandex Pay",
    "external3dSec": {
      "type": "YANDEX_PAY",
      "cryptogram": "AOLqt9wP++YAoABFA==",
      "eciIndicator": "05"
    }
  },
  "amount": {
    "value": 5900.00,
    "currency": "RUB"
  },
  "flags": [
    "SALE"
  ],
  "customer": {
    "account": "79111111111",
    "email": "test@qiwi.com",
    "phone": "79111111111"
  }
}

Пример платежа с данными расшифрованного платежного токена Yandex Pay (метод PAN_ONLY)

{
  "paymentMethod": {
    "type": "CARD",
    "pan": "4444443616621049",
    "expiryDate": "12/19",
    "holderName": "Yandex Pay",
    "external3dSec": {
      "type": "YANDEX_PAY"
    }
  },
  "amount": {
    "value": 760.00,
    "currency": "RUB"
  },
  "flags": [
    "SALE"
  ],
  "customer": {
    "account": "11111",
    "email": "test@qiwi.com",
    "phone": "79111111111"
  }
}

При отправке платежа, формат платежных данных зависит от способа аутентификации, указанного в поле authMethod расшифрованного платежного токена Yandex Pay:

Оплата через СБП

Протокол приема платежей поддерживает списание средств с покупателя через Систему быстрых платежей (СБП). Через СБП можно выполнять платежи в пользу юридических лиц, в том числе с использованием QR-кодов.

По умолчанию прием оплаты через СБП отключен. Чтобы подключить этот способ оплаты, обратитесь к вашему сопровождающему менеджеру.

Получение QR-кода

Пример тела запроса для платежа через СБП

{
  "amount": {
    "value": 100.00,
    "currency": "RUB"
  },
  "qrCode": {
    "type": "DYNAMIC",
    "ttl": 999,
    "image": {
      "mediaType": "image/png",
      "width": "300",
      "height": "300"
    }
  },
  "paymentPurpose": "Flower for my girlfriend",
  "redirectUrl": "http://someurl.com"
}

Пример ответа c QR-кодом

{
  "qrCodeUid": "adghj17d1g8",
  "amount": {
    "value": 100.00,
    "currency": "RUB"
  },
  "paymentPurpose": "Flower for my girlfriend",
  "redirectUrl": "http://someurl.com",
  "qrCode": {
    "type": "DYNAMIC",
    "ttl": 999,
    "status": "CREATED",
    "payload": "https://qr.nspk.ru/AD10006B89A9QD8FLUT1HEMP1?type=02&sum=405&cur=RUB&crc=5C01D",
    "image": {
      "content": "iVBORw0KgAAA5fY51AAAR+..",
      "mediaType": "image/png",
      "width": "300",
      "height": "300"
    }
  },
  "payment": {
    "paymentUid": "12s1s21",
    "paymentStatus": "WAITING"
  }
}

Чтобы покупатель смог произвести оплату через СБП, выпустите QR-код. Для этого отправьте запрос API Получение QR-кода СБП. В запросе укажите:

В ответе на запрос в объекте qrCode содержатся данные QR-кода:

Статус платежа через СБП

После оплаты платеж перейдет в финальный статус. Актуальный статус платежа по идентификатору paymentUid можно получить через API.

Статус QR-кода

Пример ответа на запрос статуса QR-кода

{
  "qrCodeUid": "adghj17d1g8",
  "amount": {
    "value": 1.00,
    "currency": "RUB"
  },
  "paymentPurpose": "Flower for my girlfriend",
  "redirectUrl": "http://someurl.com",
  "qrCode": {
    "type": "DYNAMIC",
    "ttl": 999,
    "status": "CREATED",
    "payload": "",
    "image": {
      "content": "Base64 string",
      "mediaType": "image/png",
      "width": "300",
      "height": "300"
    }
  },
  "payment": {
    "paymentUid": "12s1s21",
    "paymentStatus": "WAITING"
  }
}

Используйте запрос Статус QR-кода СБП. В ответе возвращается информация о QR-коде, в том числе его текущий статус. Так вы можете определить действует ли QR-код.

Выпуск токена для оплаты через СБП

Пример тела запроса выпуска токена СБП

{
  "qrCodeUid": "adghj17d1g8",
  "amount": {
    "value": 100.00,
    "currency": "RUB"
  },
  "qrCode": {
    "type": "TOKEN",
    "image": {
        "mediaType": "image/png",
        "width": "300",
        "height": "300"
      }
  },
  "tokenizationPurpose": "",
  "tokenizationAccount": "3e2322",
  "flags": ["CREATE_TOKEN"]
}

Вы можете выпустить платежный токен СБП для привязки карты покупателя и последующих оплат через СБП.

Чтобы выпустить платежный токен, воспользуйтесь запросом Получение QR-кода СБП. В запросе укажите:

Необходимо использовать разные параметры tokenizationAccount для разных покупателей, чтобы гарантировать безопасность привязанных карточных данных покупателей.

Вы получите информацию о платежном токене СБП в объекте token ответа.

Оплата токеном через СБП

Пример тела запроса

{
  "tokenizationAccount": "customer123",
  "token": "c5ba4a05-21c9-4a36-af7a-b709b4caa4d6"
}

Чтобы оплатить покупку платежным токеном СБП, передайте в запросе API Платеж токеном СБП:

Серверные уведомления

Пример уведомления

POST /qiwi-notify.php HTTP/1.1
Accept: application/json
Content-type: application/json
Signature: J4WNfNZd***V5mv2w=
Host: example.com

{
   "payment":{
      "paymentId":"4504751",
      "tokenData":{
         "paymentToken":"4cc975be-483f-8d29-2b7de3e60c2f",
         "expiredDate":"2021-12-31T00:00:00+03:00"
      },
      "type":"PAYMENT",
      "createdDateTime":"2019-10-08T11:31:37+03:00",
      "status":{
         "value":"SUCCESS",
         "changedDateTime":"2019-10-08T11:31:37+03:00"
      },
      "amount":{
         "value":2211.24,
         "currency":"RUB"
      },
      "paymentMethod":{
         "type":"CARD",
         "maskedPan":"220024******5036",
         "rrn":"124",
         "authCode":"182211"
      },
      "paymentCardInfo": {
         "issuingCountry": "810",
         "issuingBank": "QiwiBank",
         "paymentSystem": "VISA",
         "fundingSource": "CREDIT",
         "paymentSystemProduct": "P|Visa Gold"
      },
      "customer":{
         "ip":"79.142.20.248",
         "account":"token32",
         "phone":"0"
      },
      "billId":"testing122",
      "customFields":{},
      "flags":[
         "SALE"
      ]
   },
   "type":"PAYMENT",
   "version":"1"
}

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

Протокол поддерживает следующие типы уведомлений о событиях API:

Адрес вашего сервера для обработки уведомлений указывается в Личном кабинете в разделе Настройки.

Чтобы указать URL сервера обработки уведомлений для отдельной операции, используйте:

URL для уведомлений должен начинаться с https, так как уведомления отправляются по протоколу HTTPS на порт 443. URL должен быть доступен из Интернета.

Сертификат сайта должен быть выпущен доверенным центром сертификации (например Comodo, Verisign, Thawte и т.п.).

Для дополнительной уверенности следует принимать уведомления о платежах только с указанных ниже IP-адресов компании QIWI:

Уведомление считается успешно доставленным, если ваш сервер ответил HTTP кодом состояния 200 OK. До этого момента система будет пытаться доставить уведомление через увеличивающиеся интервалы времени в течение суток с момента операции.

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

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

Цифровая подпись уведомления помещается в HTTP-заголовок Signature.

Для проверки подписи используется механизм проверки целостности HMAC с хэш-функцией SHA256 и ключом, указанным в разделе Настройки Личного кабинета мерчанта.

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

  1. Объединить значения определенных параметров в одну строку с разделителем "|". Например:

    parameters = {payment.paymentId}|{payment.createdDateTime}|{payment.amount.value}

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

    Подпись считается для следующих полей уведомления:

    • тип PAYMENT: payment.paymentId|payment.createdDateTime|payment.amount.value
    • тип REFUND: refund.refundId|refund.createdDateTime|refund.amount.value
    • тип CAPTURE: capture.captureId|capture.createdDateTime|capture.amount.value
    • тип CHECK_CARD: checkPaymentMethod.requestUid|checkPaymentMethod.checkOperationDate

  2. Вычислить HMAC-хэш c алгоритмом хэширования SHA256:

    hash = HMAС(SHA256, secret, parameters)

    Где:

    • secret — ключ хеширования (UTF-8). Совпадает с ключом серверных уведомлений, указанным в разделе Настройки Личного кабинета мерчанта.
    • parameters — строка из п.1 (UTF-8).

  3. Сравнить значение подписи из HTTP-заголовка Signature уведомления с результатом п.2.

Частота отправки уведомлений

Сервис отправки уведомлений распределяет неуспешные уведомления по очередям:

Время повторной отправки может сдвигаться в бОльшую сторону.

Формат уведомления PAYMENT

Поле Описание Тип В каких случаях используется
payment Описание платежа. Object Всегда
type Тип операции String(200) Всегда
paymentId Уникальный идентификатор платежа в системе ТСП. String(200) Всегда
createdDatetime Дата создания операции URL-закодированная строка
ГГГГ-ММ-ДДTЧЧ:ММ:ССZ		 Всегда
amount Информация о сумме операции Object Всегда
value Сумма операции, округленная до двух десятичных знаков в меньшую сторону Number(6.2) Всегда
currency Идентификатор валюты операции (Alpha-3 ISO 4217 код) String(3) Всегда
billId ID счета, соответствующего операции String(200) Всегда
status Информация о статусе операции Object Всегда
value Строковое значение статуса String Всегда
changedDatetime Дата обновления статуса URL-закодированная строка
ГГГГ-ММ-ДДTЧЧ:ММ:ССZ		 Всегда
reasonCode Код причины отклонения String(200) Всегда
reasonMessage Описание причины отклонения String(200) Всегда
errorCode Код ошибки Number Всегда
paymentMethod Информация о средстве платежа Object Всегда
type Тип метода оплаты String Всегда
paymentToken Платежный токен карты. String При оплате платежным токеном
maskedPan Маскированный PAN карты String При оплате платежным токеном или картой
rrn RRN платежа (по ISO 8583) Number При оплате платежным токеном или картой
authCode Auth-code платежа Number При оплате платежным токеном или картой
paymentCardInfo Информация о карте. Object Всегда
issuingCountry Код страны эмитента String(3) Всегда
issuingBank Банк-эмитент String Всегда
paymentSystem Тип платежной системы String Всегда
fundingSource Тип карты String Всегда
paymentSystemProduct Категория карты String Всегда
customer Информация о покупателе Object Всегда
phone Номер телефона покупателя String Всегда
email E-mail покупателя String Всегда
account Идентификатор покупателя в системе ТСП String Всегда
ip IP адрес покупателя String Всегда
country Страна адреса покупателя String Всегда
customFields Поля с произвольной информацией, дополняющей данные по операции Object Всегда
cf1 Поле с произвольной информацией, дополняющей данные по операции String(256) Всегда
cf2 Поле с произвольной информацией, дополняющей данные по операции String(256) Всегда
cf3 Поле с произвольной информацией, дополняющей данные по операции String(256) Всегда
cf4 Поле с произвольной информацией, дополняющей данные по операции String(256) Всегда
cf5 Поле с произвольной информацией, дополняющей данные по операции String(256) Всегда
FROM_MERCHANT_CONTRACT_ID Номер договора String(256) Всегда
FROM_MERCHANT_BOOKING_NUMBER Номер бронирования String(256) Всегда
FROM_MERCHANT_PHONE Мобильный телефон покупателя String(256) Всегда
FROM_MERCHANT_FULL_NAME ФИО покупателя String(256) Всегда
flags Дополнительные команды, переданные в API Массив. Возможные элементы - SALE/REVERSAL Всегда
tokenData Объект с информацией о выпущенном платежном токене Object Если в платеже был запрошен выпуск платежного токена
paymentToken Строка платежного токена String Если в платеже был запрошен выпуск платежного токена
expiredDate Дата окончания срока действия платежного токена. Формат даты соответствует стандарту ISO-8601:
YYYY-MM-DDThh:mm:ss±hh:mm		 String Если в платеже был запрошен выпуск платежного токена
paymentSplits Описание сплитованных платежей. Array(Objects) Для сплитованных платежей
type Тип передаваемых данных. Всегда строка MERCHANT_DETAILS String Для сплитованных платежей
siteUid ID поставщика String Для сплитованных платежей
splitAmount Данные о возмещении поставщику Object Для сплитованных платежей
value Сумма возмещения Number Для сплитованных платежей
currency Буквенный код валюты возмещения по ISO String(3) Для сплитованных платежей
splitCommissions Данные о комиссии Object Для сплитованных платежей
merchantCms Данные о комиссии с поставщика Object Для сплитованных платежей
value Сумма комиссии Number Для сплитованных платежей
currency Буквенный код валюты комиссии по ISO String(3) Для сплитованных платежей
orderId Номер заказа String Для сплитованных платежей
comment Комментарий к заказу String Для сплитованных платежей
type Тип уведомления String(200) Всегда
version Версия уведомлений String Всегда

Формат уведомления CAPTURE

Поле Описание Тип
capture Описание подтверждения. Object
type Тип операции String(200)
captureId Уникальный идентификатор подтверждения в системе ТСП. String(200)
createdDatetime Дата создания операции URL-закодированная строка
ГГГГ-ММ-ДДTЧЧ:ММ:ССZ
amount Информация о сумме операции Object
value Сумма операции, округленная до двух десятичных знаков в меньшую сторону Number(6.2)
currency Идентификатор валюты операции (Alpha-3 ISO 4217 код) String(3)
billId ID счета, соответствующего операции String(200)
status Информация о статусе операции Object
value Строковое значение статуса String
changedDatetime Дата обновления статуса URL-закодированная строка
ГГГГ-ММ-ДДTЧЧ:ММ:ССZ
reasonCode Код причины отклонения String(200)
reasonMessage Описание причины отклонения String(200)
errorCode Код ошибки Number
paymentMethod Информация о средстве платежа Object
type Тип метода оплаты String
maskedPan Маскированный PAN карты String
rrn RRN платежа (по ISO 8583) Number
authCode Auth-code платежа Number
customer Информация о покупателе Object
phone Номер телефона покупателя String
email E-mail покупателя String
account Идентификатор покупателя в системе ТСП String
ip IP адрес покупателя String
country Страна адреса покупателя String
customFields Поля с произвольной информацией, дополняющей данные по операции Object
cf1 Поле с произвольной информацией, дополняющей данные по операции String(256)
cf2 Поле с произвольной информацией, дополняющей данные по операции String(256)
cf3 Поле с произвольной информацией, дополняющей данные по операции String(256)
cf4 Поле с произвольной информацией, дополняющей данные по операции String(256)
cf5 Поле с произвольной информацией, дополняющей данные по операции String(256)
FROM_MERCHANT_CONTRACT_ID Номер договора String(256)
FROM_MERCHANT_BOOKING_NUMBER Номер бронирования String(256)
FROM_MERCHANT_PHONE Мобильный телефон покупателя String(256)
FROM_MERCHANT_FULL_NAME ФИО покупателя String(256)
flags Дополнительные команды, переданные в API Массив. Возможные элементы - SALE/REVERSAL
type Тип уведомления String(200)
version Версия уведомлений String

Формат уведомления REFUND

Поле Описание Тип В каких случаях используется
refund Описание возврата. Object Всегда
type Тип операции String(200) Всегда
refundId Уникальный идентификатор возврата в системе ТСП. String(200) Всегда
createdDatetime Дата создания операции URL-закодированная строка
ГГГГ-ММ-ДДTЧЧ:ММ:ССZ		 Всегда
amount Информация о сумме операции Object Всегда
value Сумма операции, округленная до двух десятичных знаков в меньшую сторону Number(6.2) Всегда
currency Идентификатор валюты операции (Alpha-3 ISO 4217 код) String(3) Всегда
billId ID счета, соответствующего операции String(200) Всегда
status Информация о статусе операции Object Всегда
value Строковое значение статуса String Всегда
changedDatetime Дата обновления статуса URL-закодированная строка
ГГГГ-ММ-ДДTЧЧ:ММ:ССZ		 Всегда
reasonCode Код причины отклонения String(200) Всегда
reasonMessage Описание причины отклонения String(200) Всегда
errorCode Код ошибки Number Всегда
paymentMethod Информация о средстве платежа Object Всегда
type Тип метода оплаты String Всегда
maskedPan Маскированный PAN карты String Всегда
rrn RRN платежа (по ISO 8583) Number Всегда
authCode Auth-code платежа Number Всегда
customer Информация о покупателе Object Всегда
phone Номер телефона покупателя String Всегда
email E-mail покупателя String Всегда
account Идентификатор покупателя в системе ТСП String Всегда
ip IP адрес покупателя String Всегда
country Страна адреса покупателя String Всегда
customFields Поля с произвольной информацией, дополняющей данные по операции Object Всегда
cf1 Поле с произвольной информацией, дополняющей данные по операции String(256) Всегда
cf2 Поле с произвольной информацией, дополняющей данные по операции String(256) Всегда
cf3 Поле с произвольной информацией, дополняющей данные по операции String(256) Всегда
cf4 Поле с произвольной информацией, дополняющей данные по операции String(256) Всегда
cf5 Поле с произвольной информацией, дополняющей данные по операции String(256) Всегда
FROM_MERCHANT_CONTRACT_ID Номер договора String(256) Всегда
FROM_MERCHANT_BOOKING_NUMBER Номер бронирования String(256) Всегда
FROM_MERCHANT_PHONE Мобильный телефон покупателя String(256) Всегда
FROM_MERCHANT_FULL_NAME ФИО покупателя String(256) Всегда
flags Дополнительные команды, переданные в API Массив. Возможные элементы - SALE/REVERSAL Всегда
refundSplits Описание возвратов по сплитованным платежам. Array(Objects) При возвратах сплитованных платежей
type Тип передаваемых данных. Всегда строка MERCHANT_DETAILS String При возвратах сплитованных платежей
siteUid ID поставщика String При возвратах сплитованных платежей
splitAmount Данные об отмене возмещения поставщику Object При возвратах сплитованных платежей
value Сумма отмены возмещения Number При возвратах сплитованных платежей
currency Буквенный код валюты отмены возмещения по ISO String(3) При возвратах сплитованных платежей
splitCommissions Данные о комиссии Object При возвратах сплитованных платежей
merchantCms Данные о комиссии с поставщика Object При возвратах сплитованных платежей
value Сумма комиссии Number При возвратах сплитованных платежей
currency Буквенный код валюты комиссии по ISO String(3) При возвратах сплитованных платежей
orderId Номер заказа String При возвратах сплитованных платежей
comment Комментарий к заказу String При возвратах сплитованных платежей
type Тип уведомления String(200) Всегда
version Версия уведомлений String Всегда

Формат уведомления CHECK_CARD

Поле Описание Тип
checkPaymentMethod Описание результата проверки карты Object
checkOperationDate Дата проверки карты URL-закодированная строка
ГГГГ-ММ-ДДTЧЧ:ММ:ССZ
requestUid Идентификатор операции проверки карты String
status Информация о статусе проверки карты String
isValidCard Признак валидности карты для платежей Bool
threeDsStatus Информация о статусе дополнительной аутентификации при проверке карты. Возможные значения — PASSED (3-D Secure пройден), NOT_PASSED (3-D Secure не пройден), WITHOUT (3-D Secure не требовалось) String
paymentMethod Информация о средстве платежа Object
type Тип метода оплаты String
maskedPan Маскированный PAN карты String
cardExpireDate Срок действия карты String
cardHolder Имя держателя карты String
cardInfo Информация о карте. Object
issuingCountry Код страны эмитента String(3)
issuingBank Банк-эмитент String
paymentSystem Тип платежной системы String
fundingSource Тип карты String
paymentSystemProduct Категория карты String
createdToken Объект с информацией о выпущенном вместе с проверкой карты платежном токене Object
token Строка платежного токена String
name Маскированный PAN карты, для которой выпущен платежный токен String
expiredDate Дата окончания срока действия платежного токена. Формат даты соответствует стандарту ISO-8601:
YYYY-MM-DDThh:mm:ss±hh:mm		 String
account Идентификатор покупателя, указанный при выпуске платежного токена String
type Тип уведомления String(200)
version Версия уведомлений String

Возвраты и отмены

Операции возврата и отмены доступны не для всех способов платежей:

При возврате платежа комиссия QIWI за проведение платежа не возвращается. Исключение — если при возврате платежа выполнена операция отмены. В этом случае финансовой операции (списания средств со счета покупателя) не происходит и комиссия не взимается.

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

Чтобы сделать возврат средств по оплаченному счету, используйте запрос API Возврат по платежу.

Возвраты по проведенным платежам

Возврат по платежу возможен только для успешно проведенного платежа. Возврат может быть как частичным, так и полным. В первом случае возвращается вся сумма принятого платежа. Во втором — только часть от суммы платежа. Перед возвратом платежа проверьте, что платеж успешно завершен и находится в статусе COMPLETED.

Чтобы выполнить возврат по платежу, используйте метод API Операция возврата.

Чтобы выполнить возврат по платежу через СБП, используйте метод API Операция возврата по платежу СБП.

Сплитование платежей

Сплитование платежей — решение, разработанное специально для маркетплейсов. Сплитование платежей позволяет рассчитываться с несколькими поставщиками услуг, производя одно списание с карты покупателя.

Чтобы подключить сплитование платежей, обратитесь к вашему сопровождающему менеджеру и запросите подключение решения.

Интеграция с Платежной формой QIWI

Чтобы отправить платеж со сплитованием, передайте в запросе API Создание счета массив
splits c данными поставщиков.

Описание данных

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

curl --location --request PUT 'https://api.qiwi.com/partner/payin/v1/sites/Obuc-02/bills/eqwptt' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer token \
--data-raw '{
    "amount": {
        "value": 3.00,
        "currency": "RUB"
    },
    "expirationDateTime": "2021-12-31T23:59:59+03:00",
    "comment": "Мой комментарий",
    "splits": [
        {
            "type": "MERCHANT_DETAILS",
            "siteUid": "Obuc-00",
            "splitAmount": {
                "value": 2.00,
                "currency": "RUB"
            },
            "orderId": "dressesforwhite",
            "comment": "Платье"
        },
        {
            "type": "MERCHANT_DETAILS",
            "siteUid": "Obuc-01",
            "splitAmount": {
                "value": 1.00,
                "currency": "RUB"
            },
            "orderId": "shoesforvalya",
            "comment": "Туфли"
        }
    ]
}
'

Пример ответа при выставлении счета со сплитованием

{
    "billId": "eqwptt",
    "invoiceUid": "44b2ef2a-edc6-4aed-87d3-01cf37ed2732",
    "amount": {
        "currency": "RUB",
        "value": "3.00"
    },
    "expirationDateTime": "2021-12-31T23:59:59+03:00",
    "status": {
        "value": "CREATED",
        "changedDateTime": "2021-02-05T10:21:17+03:00"
    },
    "comment": "Мой комментарий",
    "flags": [
        "TEST"
    ],
    "payUrl": "https://oplata.qiwi.com/form?invoiceUid=44b2ef2a-edc6-4aed-87d3-01cf37ed2732",
    "splits": [
        {
            "type": "MERCHANT_DETAILS",
            "siteUid": "Obuc-00",
            "splitAmount": {
                "currency": "RUB",
                "value": "2.00"
            },
            "orderId": "dressesforwhite",
            "comment": "Платье"
        },
        {
            "type": "MERCHANT_DETAILS",
            "siteUid": "Obuc-01",
            "splitAmount": {
                "currency": "RUB",
                "value": "1.00"
            },
            "orderId": "shoesforvalya",
            "comment": "Туфли"
        }
    ]
}

Описание массива splits:

Название Тип Описание
splits Array Массив данных о поставщиках
type String Тип передаваемых данных. Доступные значения: MERCHANT_DETAILS (данные поставщика)
siteUid String Зарегистрированный ID поставщика
splitAmount Object Возмещение поставщику
value Number Сумма возмещения
currency String(3) Буквенный код валюты возмещения по ISO. Доступен только RUB
orderId String Номер заказа (необязательный)
comment String Комментарий к заказу (необязательный)

В объекте splits ответа содержатся данные о сплитованных платежах и комиссиях:

Поле ответа Тип Описание
splits Array Массив с данными о сплитованных платежах
type String Тип передаваемых данных. Всегда возвращается строка MERCHANT_DETAILS
siteUid String Зарегистрированный ID поставщика
splitAmount Object Данные о возмещении поставщику
value String Сумма возмещения
currency String(3) Буквенный код валюты возмещения по ISO
orderId String Номер заказа
comment String Комментарий к заказу

Интеграция с Платежной формой мерчанта

Чтобы отправить платеж со сплитованием, передайте в запросе API Платеж JSON-массив paymentSplits с данными поставщиков.

Описание данных

{
 "paymentMethod": "...",
 "customer": "....",
 "deviceData": "...",
 "paymentSplits": [
   {
     "type":"MERCHANT_DETAILS",
     "siteUid":"shop_mst-01",
     "splitAmount": {
       "value":300.00,
       "currency":"RUB"
     },
     "orderId":"dasdad444ll4ll",
     "comment":"Цветы"
  },
  {
    "type":"MERCHANT_DETAILS",
    "siteUid":"shop_mst-02",
    "splitAmount": {
      "value":200.00,
      "currency":"RUB"
      },
      "orderId":"sdadada887sdDDDDd",
      "comment":"Фрукты"
    }
  ]
}

Пример ответа

{
   "paymentId": "23",
   "billId": "autogenerated-2a8fcfab-45cb-43b9-81bd-edf65e0ef874",
   "createdDateTime": "2020-10-12T15:29:12+03:00",
   "amount": {
   "currency": "RUB",
   "value": "100.00"
},
   "capturedAmount": {
   "currency": "RUB",
   "value": "100.00"
},
   "refundedAmount": {
   "currency": "RUB",
   "value": "0.00"
},
   "paymentMethod": "..",
   "status": "..",
   "paymentCardInfo": "..",
   "paymentSplits": [
       {
          "type": "MERCHANT_DETAILS",
          "siteUid": "shop_mst-01",
          "splitAmount": {
          "currency": "RUB",
          "value": "30.00"
       },
          "splitCommissions": {
          "merchantCms": {
          "currency": "RUB",
          "value": "10.00"
       }
       },
          "orderId": "313fh1f23j13k1k",
          "comment": "Товар из корзины"
       },
       {
          "type": "MERCHANT_DETAILS",
          "siteUid": "shop_mst-02",
          "splitAmount": {
             "currency": "RUB",
             "value": "20.00"
           },
          "splitCommissions": {
               "merchantCms": {
                   "currency": "RUB",
                   "value": "10.00"
                }
            },
          "orderId": "sdadada887sdDDDDd",
          "comment": "Фрукты"
       },
       {
          "type": "MERCHANT_DETAILS",
          "siteUid": "shop_mst-03",
          "splitAmount": {
            "currency": "RUB",
            "value": "50.00"
          },
          "splitCommissions": {
            "merchantCms": {
              "currency": "RUB",
              "value": "10.00"
            }
          },
          "orderId": "dasdad444ll4ll",
          "comment": "Цветы"
       }
    ]
}

Описание массива paymentSplits:

Название Тип Описание
paymentSplits Array Массив данных о поставщиках
type String Тип передаваемых данных. Доступные значения: MERCHANT_DETAILS (данные поставщика)
siteUid String Зарегистрированный ID поставщика
splitAmount Object Возмещение поставщику
value Number Сумма возмещения
currency String(3) Буквенный код валюты возмещения по ISO. Доступен только RUB
orderId String Номер заказа (необязательный)
comment String Комментарий к заказу (необязательный)

В объекте paymentSplits ответа содержатся данные о принятых платежах и комиссиях:

Поле ответа Тип Описание
paymentSplits Array Массив с данными о принятых платежах
type String Тип передаваемых данных. Всегда возвращается строка MERCHANT_DETAILS
siteUid String Зарегистрированный ID поставщика
splitAmount Object Данные о возмещении поставщику
value String Сумма возмещения
currency String(3) Буквенный код валюты возмещения по ISO
splitCommissions Object Данные о комиссии (необязательный)
merchantCms Object Данные о комиссии с поставщика
value String Сумма комиссии
currency String(3) Буквенный код валюты комиссии по ISO
orderId String Номер заказа
comment String Комментарий к заказу

Возвраты по сплитованным платежам

После успешной авторизации списания денежных средств доступен возврат средств по операции сплитованного платежа.

Пример запроса

PUT /partner/payin/v1/sites/test-01/payments/23/refunds/1 HTTP/1.1
Accept: application/json
Authorization: Bearer 5c4b25xx93aa435d9cb8cd17480356f9
Content-type: application/json
Host: api.qiwi.com

{
  "amount": {
    "value": 100.00,
    "currency": "RUB"
  },
  "refundSplits": [
  {
    "type": "MERCHANT_DETAILS",
    "siteUid": "shop_mst-01",
    "splitAmount": {
      "value": 30.00,
      "currency": "RUB"
    },
    "orderId": "sdadada887sdDDDDd",
    "comment": "Фрукты"
  },
  {
    "type": "MERCHANT_DETAILS",
    "siteUid": "shop_mst-02",
    "splitAmount": {
      "value": 20.00,
      "currency": "RUB"
    },
   
    "orderId": "313fh1f23j13k1k",
    "comment": "Товар из корзины"
  },
  {
    "type": "MERCHANT_DETAILS",
    "siteUid": "shop_mst-03",
    "splitAmount": {
      "value": 50.00,
      "currency": "RUB"
    },
    "orderId": "dasdad444ll4ll",
    "comment": "Цветы"
  }
  ]
}

Пример ответа

{
    "refundId": "1",
    "createdDateTime": "2020-10-12T15:32:29+03:00",
    "amount": {
        "currency": "RUB",
        "value": "100.00"
    },
    "status": {
        "value": "COMPLETED",
        "changedDateTime": "2020-10-12T15:32:30+03:00"
    },
    "refundSplits": [
        {
            "type": "MERCHANT_DETAILS",
            "siteUid": "shop_mst-02",
            "splitAmount": {
                "currency": "RUB",
                "value": "20.00"
            },
            "splitCommissions": {
                "merchantCms": {
                    "currency": "RUB",
                    "value": "10.00"
                }
            },
            "orderId": "sdadada887sdDDDDd",
            "comment": "Фрукты"
        },
        {
            "type": "MERCHANT_DETAILS",
            "siteUid": "shop_mst-01",
            "splitAmount": {
                "currency": "RUB",
                "value": "30.00"
            },
            "splitCommissions": {
                "merchantCms": {
                    "currency": "RUB",
                    "value": "10.00"
                }
            },
            "orderId": "313fh1f23j13k1k",
            "comment": "Товар из корзины"
        },
        {
            "type": "MERCHANT_DETAILS",
            "siteUid": "shop_mst-03",
            "splitAmount": {
                "currency": "RUB",
                "value": "50.00"
            },
            "splitCommissions": {
                "merchantCms": {
                    "currency": "RUB",
                    "value": "10.00"
                }
            },
            "orderId": "dasdad444ll4ll",
            "comment": "Цветы"
        }
    ]
}

В запросе API Операция возврата передайте JSON-массив refundSplits с данными о возвратах поставщикам. Укажите общую сумму возврата и сумму возврата для каждого поставщика. Поддерживается как частичный, так и полный возврат.

Описание массива refundSplits:

Название Тип Описание
refundSplits Array Массив данных о возвратах поставщикам
type String Тип передаваемых данных. Доступные значения: MERCHANT_DETAILS (данные поставщика)
siteUid String Зарегистрированный ID поставщика
splitAmount Object Данные об отмене возмещения поставщику
value Number Сумма отмены возмещения
currency String(3) Буквенный код валюты отмены возмещения по ISO. Доступен только RUB
orderId String Номер заказа (необязательный)
comment String Комментарий к заказу (необязательный)

В JSON-массиве refundSplits ответа содержатся данные о принятых возвратах:

Поле ответа Тип Описание
refundSplits Array Массив данных о возвратах поставщикам
type String Тип передаваемых данных. Всегда возвращается строка MERCHANT_DETAILS
siteUid String Зарегистрированный ID поставщика
splitAmount Object Данные об отмене возмещения поставщику
value String Сумма отмены возмещения
currency String(3) Буквенный код валюты по ISO
splitCommissions Object Данные о комиссии (необязательный)
merchantCms Object Данные о комиссии с поставщика
value String Сумма комиссии
currency String(3) Буквенный код валюты комиссии по ISO
orderId String Номер заказа
comment String Комментарий к заказу

Уведомления по сплитованным операциям

Пример уведомления по сплитованным платежам

{
    "payment": {
        "paymentId": "134d707d-fec4-4a84-93f3-781b4f8c24ac",
        "customFields": {
            "comment": "Мой комментарий"
        },
        "paymentCardInfo": {
            "issuingCountry": "643",
            "issuingBank": "Unknown",
            "paymentSystem": "VISA",
            "fundingSource": "UNKNOWN",
            "paymentSystemProduct": "Unknown"
        },
        "type": "PAYMENT",
        "createdDateTime": "2021-02-05T11:29:38+03:00",
        "status": {
            "value": "SUCCESS",
            "changedDateTime": "2021-02-05T11:29:39+03:00"
        },
        "amount": {
            "value": 3,
            "currency": "RUB"
        },
        "paymentMethod": {
            "type": "TOKEN",
            "paymentToken": "1620161e-d498-431b-b006-c52bb78c6bf2",
            "maskedPan": "425600******0003",
            "cardHolder": "CARD HOLDER",
            "cardExpireDate": "11/2022"
        },
        "customer": {
            "email": "glmgmmxr@qiwi123.com",
            "account": "sbderxuftsrt",
            "phone": "13387571067",
            "country": "yccsnnfjgthu",
            "city": "sqdvseezbpzo",
            "region": "shbvyjgspjvu"
        },
        "gatewayData": {
            "type": "ACQUIRING",
            "authCode": "181218",
            "rrn": "123"
        },
        "billId": "autogenerated-19cf2596-62a8-47f2-8721-b8791e9598d0",
        "flags": [],
        "paymentSplits": [
            {
                "type": "MERCHANT_DETAILS",
                "siteUid": "Obuc-00",
                "splitAmount": {
                    "value": 2,
                    "currency": "RUB"
                },
                "splitCommissions": {
                    "merchantCms": {
                        "value": 0.2,
                        "currency": "RUB"
                    },
                    "userCms": null
                },
                "orderId": "dressesforwhite",
                "comment": "Платье"
            },
            {
                "type": "MERCHANT_DETAILS",
                "siteUid": "Obuc-01",
                "splitAmount": {
                    "value": 1,
                    "currency": "RUB"
                },
                "splitCommissions": {
                    "merchantCms": {
                        "value": 0.02,
                        "currency": "RUB"
                    },
                    "userCms": null
                },
                "orderId": "shoesforvalya",
                "comment": "Туфли"
            }
        ]
    },
    "type": "PAYMENT",
    "version": "1"
}

Пример уведомления по возвратам сплитованных платежей

{
    "refund": {
        "refundId": "42f5ca91-965e-4cd0-bb30-3b64d9284048",
        "type": "REFUND",
        "createdDateTime": "2021-02-05T11:31:40+03:00",
        "status": {
            "value": "SUCCESS",
            "changedDateTime": "2021-02-05T11:31:40+03:00"
        },
        "amount": {
            "value": 3,
            "currency": "RUB"
        },
        "paymentMethod": {
            "type": "TOKEN",
            "paymentToken": "1620161e-d498-431b-b006-c52bb78c6bf2",
            "maskedPan": null,
            "cardHolder": null,
            "cardExpireDate": null
        },
        "customer": {
            "email": "glmgmmxr@qiwi123.com",
            "account": "sbderxuftsrt",
            "phone": "13387571067",
            "country": "yccsnnfjgthu",
            "city": "sqdvseezbpzo",
            "region": "shbvyjgspjvu"
        },
        "gatewayData": {
            "type": "ACQUIRING",
            "authCode": "181218",
            "rrn": "123"
        },
        "billId": "autogenerated-19cf2596-62a8-47f2-8721-b8791e9598d0",
        "flags": [
            "REVERSAL"
        ],
        "refundSplits": [
            {
                "type": "MERCHANT_DETAILS",
                "siteUid": "Obuc-00",
                "splitAmount": {
                    "value": 2,
                    "currency": "RUB"
                },
                "splitCommissions": {
                    "merchantCms": {
                        "value": 0,
                        "currency": "RUB"
                    },
                    "userCms": null
                },
                "orderId": "dressesforwhite",
                "comment": "Покупка 1"
            },
            {
                "type": "MERCHANT_DETAILS",
                "siteUid": "Obuc-01",
                "splitAmount": {
                    "value": 1,
                    "currency": "RUB"
                },
                "splitCommissions": {
                    "merchantCms": {
                        "value": 0.02,
                        "currency": "RUB"
                    },
                    "userCms": null
                },
                "orderId": "shoesforvalya",
                "comment": "Покупка 2"
            }
        ]
    },
    "type": "REFUND",
    "version": "1"
}

Уведомления по сплитованным платежам и по возвратам сплитованных платежей формируются аналогично описанным выше ответам на запросы API:

Платежный токен

В Протоколе приема платежей поддерживается генерация платежных токенов карт и QIWI Кошельков. Они могут быть использованы для последующих списаний без дополнительного ввода реквизитов карт или номера кошелька. При выпуске платежного токена карты ее реквизиты сохраняются в зашифрованном виде в QIWI.

Особенности

По умолчанию выпуск платежных токенов отключен. Чтобы подключить его, обратитесь к вашему сопровождающему менеджеру.

Выпуск платежного токена карты

Пример запроса выставления счета с выпуском платежного токена

PUT /partner/payin/v1/sites/23044/bills/893794793973 HTTP/1.1
Accept: application/json
Authorization: Bearer 5c4b25xx93aa435d9cb8cd17480356f9
Content-type: application/json
Host: api.qiwi.com

{
   "amount": {  
     "currency": "RUB",  
     "value": 10.00
   },
   "expirationDateTime": "2021-04-13T14:30:00+03:00",
    "customer": { 
      "account":"token32" 
   }, 
   "customFields": {}, 
   "flags":["BIND_PAYMENT_TOKEN"] 
}

Пример запроса платежа с выпуском платежного токена

PUT /partner/payin/v1/sites/test-01/payments/test-022 HTTP/1.1
Accept: application/json
Authorization: Bearer 5c4b25xx93aa435d9cb8cd17480356f9
Content-type: application/json
Host: api.qiwi.com

{
   "amount": {  
     "currency": "RUB",  
     "value": 2211.24
   },
   "customer": {
     "account": "token324",
     "phone": "79022222222"
   },
   "flags":["BIND_PAYMENT_TOKEN"]
}

Пример тела ответа с платежным токеном

{
    "paymentId": "test-022",
    "billId": "autogenerated-c4479bb1-c916-4fba-8445-802592fa8d51",
    "createdDateTime": "2020-03-26T12:22:12+03:00",
    "amount": {
        "currency": "RUB",
        "value": 2211.24
    },
    "capturedAmount": "..",
    "refundedAmount": "..",
    "paymentMethod": "..",
    "createdToken": {
        "token": "66aebf5f-098e-4e36-922a-a4107b349a96",
        "name": "411111******1111"
    },
    "customer": {
        "account": "token324",
        "phone": "79022222222"
    },
    "status": ".."
}

Для выпуска платежного токена карты вы можете использовать два способа:

  1. Без платежа (предпочтительный способ). Воспользуйтесь запросом Проверка карты или Создание счета с проверкой карты. В запросе укажите:
    • параметр account — уникальный идентификатор Покупателя в системе ТСП:
    • параметр "flags":["CHECK_CARD", "BIND_PAYMENT_TOKEN"] — в случае запроса Создание счета.

    Необходимо использовать разные параметры account для разных покупателей, чтобы гарантировать безопасность карточных данных покупателей.

    Вы получите информацию о платежном токене карты после успешного завершения проверки:

    Также можно запросить текущий статус проверки — в ответе вернется блок createdToken с информацией о выпущенном платежном токене.

    Подробнее см. в разделе Проверка карты покупателя.

  2. В процессе проведения платежа. Воспользуйтесь запросом Платеж или Создание счета. В запросе укажите дополнительные параметры:
    • "flags": ["BIND_PAYMENT_TOKEN"] — команда для выпуска платежного токена.
    • customer.account — уникальный идентификатор Покупателя в системе ТСП.

    Необходимо использовать разные параметры account для разных покупателей, чтобы гарантировать безопасность карточных данных покупателей.

    Вы получите информацию о платежном токене карты:

    • В синхронном ответе на запрос API Платеж в поле createdToken.
    • После успешного завершения платежа в уведомлении в поле tokenData.

Выпуск платежного токена QIWI Кошелька

Пример запроса с инициацией выпуска платежного токена QIWI Кошелька

POST /partner/payin-tokenization-api/v1/sites/test-01/token-requests HTTP/1.1
Accept: application/json
Authorization: Bearer 5c4b25xx93aa435d9cb8cd17480356f9
Content-type: application/json
Host: api.qiwi.com

{
   "requestId": "asd1232q77w1e3212",
   "phone": "79022222222",
   "accountId": "token324"
}

Ответ на запрос

{
    "requestId": "asd1232q77w1e3212",
    "status": {
        "value": "WAITING_SMS"
    }
}

Пример запроса завершения выпуска платежного токена QIWI Кошелька

PUT /partner/payin-tokenization-api/v1/sites/test-01/token-requests/complete HTTP/1.1
Accept: application/json
Authorization: Bearer 5c4b25xx93aa435d9cb8cd17480356f9
Content-type: application/json
Host: api.qiwi.com

{
   "requestId": "asd1232q77w1e3212",
   "smsCode": "1223"
}

Ответ на запрос

{
    "requestId": "asd1232q77w1e3212",
    "status": {
        "value": "CREATED"
    },
    "token": {
        "value": "589c04b5-47dd-41af-9682-b3eb91",
        "expiredDate": "2021-11-08T14:23:54+03:00"
    }
}

Чтобы выпустить платежный токен QIWI кошелька, выполните следующие запросы к API:

  1. Запрос инициации выпуска платежного токена QIWI Кошелька.

    Отправьте POST-запрос на URL:

    /payin-tokenization-api/v1/sites/{siteId}/token-requests

    где {siteId} — идентификатор siteId мерчанта.

    В JSON-теле запроса укажите параметры:

    • requestId — уникальный идентификатор запроса (от 1 до 36 символов). Уникальность означает, что идентификатор должен отличаться от идентификаторов всех ранее созданных запросов ТСП на выпуск платежного токена QIWI кошелька в рамках одного siteId.
    • phone — номер QIWI кошелька покупателя.
    • accountId — уникальный идентификатор покупателя в системе ТСП.

    Указывайте разные параметры accountId для разных покупателей, чтобы гарантировать безопасность платежных данных покупателей.

  2. После этого на телефон покупателя придет SMS с одноразовым кодом. Укажите его в запросе завершения выпуска платежного токена QIWI Кошелька.

    Отправьте POST-запрос на URL:

    /payin-tokenization-api/v1/sites/{siteId}/token-requests/complete

    где {siteId} — идентификатор siteId мерчанта.

    В JSON-теле запроса укажите параметры:

    • requestId — идентификатор из начального запроса инициации выпуска платежного токена.
    • smsCode — код из SMS, отправленный покупателю.

В ответе содержатся данные платежного токене:

Удаление платежного токена

Удаление платежного токена

DELETE /partner/payin/v1/sites/test-01/tokens HTTP/1.1
Accept: application/json
Authorization: Bearer 5c4b25xx93aa435d9cb8cd17480356f9
Content-type: application/json
Host: api.qiwi.com

{
   "token": "66aebf5f-098e-4e36-922a-a4107b349a96",
   "customerAccountId": "token324"
}

Чтобы прекратить действие платежного токена, отправьте запрос DELETE:

/partner/payin/v1/sites/{siteId}/tokens

В JSON-теле запроса укажите параметры:

Успешный ответ означает, что платежный токен для указанного покупателя больше не действует.

Этот метод действует как для платежного токена карты, так и для платежного токена QIWI Кошелька.

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

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

Если проверка пройдена успешно, для карты может быть выпущен платежный токен.

Сервис проверки карт по умолчанию отключен. Чтобы подключить его, обратитесь к вашему сопровождающему менеджеру.

Как использовать сервис через Платежную форму QIWI

Пример запроса выставления счета с проверкой карты

PUT /partner/payin/v1/sites/site-01/bills/892323232111 HTTP/1.1
Accept: application/json
Authorization: Bearer 5c4b25xx93aa435d9cb8cd1xxxx356f9
Content-type: application/json
Host: api.qiwi.com

{
    "expirationDateTime": "2023-09-14T14:30:00+03:00",
    "customer": {
        "account":"test-123"
    },
    "flags": ["CHECK_CARD","BIND_PAYMENT_TOKEN"]
}

Пример тела успешного ответа

{
    "siteId": "site-01",
    "billId": "892323232111",
    "amount": {
      "value": 0.00,
      "currency": "RUB"
    },
    "status": {
      "value": "CREATED",
      "changedDateTime": "2021-08-13T15:43:41"
    },
    "creationDateTime": "2021-08-13T15:43:41",
    "expirationDateTime": "2023-09-14T14:30:00",
    "payUrl": "https://oplata.qiwi.com/validation/card?invoiceUid=fxxxxx-854c-4e56-xxxx-eb49aef2xxxx"
}

Пример уведомления с результатом проверки карты

{
   "checkPaymentMethod":{
      "status":"SUCCESS",
      "isValidCard":true,
      "threeDsStatus":"WITHOUT",
      "cardInfo":{
         "issuingCountry":"0",
         "issuingBank":"not present",
         "paymentSystem":"VISA",
         "fundingSource":"UNKNOWN",
         "paymentSystemProduct":"UNKNOWN"
      },
      "createdToken":{
         "token":"xxxxxxx-a53a-4de1-8aa4-xxxxxxx",
         "name":"411111******1111",
         "expiredDate":"2021-11-30T00:00:00+03:00",
         "account":"some_account"
      },
      "requestUid":"892323232111",
      "paymentMethod":{
         "type":"CARD",
         "maskedPan":"411111******1111",
         "cardHolder":"",
         "cardExpireDate":"11/2021"
      },
      "checkOperationDate":"2021-08-13T15:44:01+03:00"
   },
   "type":"CHECK_CARD",
   "version":"1"
}
  1. Отправьте запрос создания счета с дополнительным параметром "flags":["CHECK_CARD", "BIND_PAYMENT_TOKEN"]. Для генерации платежного токена в запросе должен быть указан параметр customer.account — уникальный идентификатор покупателя в системе ТСП. Не указывайте сумму счета. Извлеките из ответа параметр billId — он понадобится в п.4.
  2. Перенаправьте покупателя на Платежную форму — ссылка на нее находится в параметре payUrl ответа.

  3. На Платежной форме покупатель указывает реквизиты карты и отправляет их на проверку. На форме выполняется аутентификация покупателя (3-D Secure). check card

  4. Дождитесь завершения проверки карты: вам придет уведомление CHECK_CARD с результатом, или запросите текущий статус проверки — в качестве уникального идентификатора проверки карты укажите billId из п.1. Результат проверки:

    • Информация о доступности карты для списаний — в атрибуте isValidCard (true — номер карты валиден).
    • Данные платежного токена — в объекте createdToken.

Как использовать сервис через API

Пример запроса проверки карты

PUT /partner/payin/v1/sites/site-01/validation/card/requests/acd7bf20-22e2-4cbf-a218-38d90e9f29b9 HTTP/1.1
Accept: application/json
Authorization: Bearer 5c4b25xx93aa435d9cb8cd17480356f9
Content-type: application/json
Host: api.qiwi.com

{
    "cardData": {
        "pan": "1111222233334444",
        "expiryDate": "12/34",
        "cvv2": "123",
        "holderName": "Super Man"
    },
    "tokenizationData": {
        "account": "cat_girl"
    }
}

Пример тела успешного ответа

{
    "requestUid": "acd7bf20-22e2-4cbf-a218-38d90e9f29b9",
    "status": "SUCCESS",
    "isValidCard": true,
    "threeDsStatus": "WITHOUT",
    "checkOperationDate": "2021-07-29T16:30:00+03:00",
    "cardInfo": {
        "issuingCountry": "RUS",
        "issuingBank": "Qiwi bank",
        "paymentSystem": "VISA",
        "fundingSource": "DEBIT",
        "paymentSystemProduct": "Platinum..."
    },
    "createdToken": {
        "token": "1a77343a-dd8a-11eb-ba80-0242ac130004",
        "name": "111122******4444",
        "expiredDate": "2034-12-01T00:00:00+03:00",
        "account": "cat_girl"
    }
}

Пример тела ответа с проверкой 3DS

{
    "requestUid": "acd7bf20-22e2-4cbf-a218-38d90e9f29b9",
    "status": "WAITING_3DS",
    "requirements": {
        "pareq": "Some string pareq",
        "acsUrl": "http://xxxxxxx"
    }
}

Пример тела ответа с ошибкой проверки

{
    "requestUid": "acd7bf20-22e2-4cbf-a218-38d90e9f29b9",
    "status": "ERROR"
}

Пример запроса завершения 3DS при проверке карты

POST /partner/payin/v1/sites/site-01/validation/card/requests/acd7bf20-22e2-4cbf-a218-38d90e9f29b9/complete HTTP/1.1
Accept: application/json
Authorization: Bearer 5c4b25xx93aa435d9cb8cd17480356f9
Content-type: application/json
Host: api.qiwi.com

{
    "pares": "Some string pares"
}

Пример тела ответа

{
    "requestUid": "acd7bf20-22e2-4cbf-a218-38d90e9f29b9",
    "status": "SUCCESS",
    "isValidCard": true,
    "threeDsStatus": "PASSED",
    "checkOperationDate": "2021-07-29T16:30:00+03:00",
    "cardInfo": {
        "issuingCountry": "RUS",
        "issuingBank": "Qiwi bank",
        "paymentSystem": "VISA",
        "fundingSource": "DEBIT",
        "paymentSystemProduct": "Platinum..."
    },
    "createdToken": {
        "token": "1a77343a-dd8a-11eb-ba80-0242ac130004",
        "name": "111122******4444",
        "expiredDate": "2034-12-01T00:00:00+03:00",
        "account": "cat_girl"
    }
}
  1. Отправьте запрос API "Проверка карты". В запросе укажите уникальный в рамках вашего сайта идентификатор проверки (requestUid). Для генерации платежного токена в запросе должен быть указан параметр tokenizationData.account — уникальный идентификатор покупателя в системе ТСП.
  2. В ответе информация о доступности карты для списаний содержится в атрибуте isValidCard (true — номер карты валиден). Данные платежного токена возвращаются в объекте createdToken.

Чтобы убедиться, что номер карты ввел именно держатель карты, вы можете использовать дополнительную аутентификацию покупателя 3-D Secure в сервисе проверки карты. Включение/отключение 3DS производится на стороне QIWI через поддержку. Если 3DS включен, то в ответе на запрос проверки карты вы получите объект "requirements" с ACS URL для перенаправления покупателя (в поле status будет значение "WAITING_3DS").

Сценарий проверки аналогичен операции покупки:

  1. Перенаправьте покупателя на страницу аутентификации.
  2. Завершите 3-D Secure запросом "Завершение 3DS при проверке карты". В запросе укажите тот же идентификатор проверки, что и в исходном запросе проверки карты.
  3. Если проверка 3-D Secure завершилась успешно, в ответе информация о доступности карты для списаний содержится в атрибуте isValidCard (true — номер карты валиден). Данные платежного токена возвращаются в объекте createdToken.

После завершения проверки вам придет уведомление CHECK_CARD с результатом. Также вы можете всегда запросить текущий статус проверки.

Акты

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

Скачать шаблон Акта

Акт сначала отправляется на email, указанный при регистрации в сервисе. После подтверждения со стороны партнера, уполномоченное лицо КИВИ Банка подписывает Акт в системе документооборота электронной подписью. Подписанный Акт отправляется на юридический адрес партнера.

Реестры

Реестр операций отправляется после 14:00 МСК по рабочим дням, содержит информацию только об успешных платежах, обработанных банком. Реестр полностью соответствует Акту.

Реестр отправляется на email, указанный при регистрации в сервисе, во вложенном в письме zip-архиве.

Формат реестра

Пример фрагмента реестра

BANK_DATA_DOC;BANK_VALUE_DOC;BANK_AGR_CODE;SUM_BANK;TRANS_DATE;TRANSACTION_ID;SUM;COMMISSION;USER_INFO;ID;MERCH;MERCH_SITE;PARENT_TRANSACTION_ID;BILL;PURPOSE;MERCHANT_SITE_NAME;PAYMENT_METHOD_TYPE;ММВБ;CLIENT_AMOUNT;CLIENT_CUR_CODE;SETTLEMENT_AMOUNT;PAYMENTDETAILS
27.08.2020;27.08.2020;3456144;-25676786,28;;;25676786,28;;;;;;;;SETTLEMENT;;;null;;;;
27.08.2020;27.08.2020;34562014;243767,27;26.08.2020 9:59;659720;2165,46;25;533669******4030;68860745;hthi;hthi-26;;autogenerated-67cd0dfb-ca5a-0baf-b0e0-735a880c0dac;Оплата;сайт;Bank card;null;2165,46;643;25664068,85;Перевод принятых денежных средств по Договору  от 2019-09-24 00:00:00. Комиссия  руб. НДС не облагается.
27.08.2020;27.08.2020;34562014;243767,27;26.08.2020 10:01;660540;1530;25;536809******4077;68860893;hthi;hthi-26;;autogenerated-90870507-acd9-0056-80f7-d050560fba09;Оплата;сайт;Bank card;null;1530;643;25664068,85;Перевод принятых денежных средств по Договору  от 2019-09-24 00:00:00. Комиссия  руб. НДС не облагается.
27.08.2020;27.08.2020;34562014;243767,27;26.08.2020 10:06;665760;3150;56,7;547007******4635;68861159;hthi;hthi-54;;autogenerated-8a30690b-8c0c-0808-a0bb-6c73cbfdf953;Оплата;сайт;Bank card;null;3150;643;25664068,85;Перевод принятых денежных средств по Договору  от 2019-09-24 00:00:00. Комиссия  руб. НДС не облагается.
27.08.2020;27.08.2020;34562014;243767,27;26.08.2020

Файл реестра формируется в формате CSV.

Скачать пример реестра

Поле реестра Описание
BANK_DATA_DOC Дата документа, влияющего на баланс банковского счета, по этой дате составляется Акт в конце месяца
BANK_VALUE_DOC Дата фактического изменения баланса счета в банке
BANK_AGR_CODE Банковский код, уникальный номер документа
SUM_BANK Сумма документа
TRANS_DATE Дата создания операции
TRANSACTION_ID Номер операции
SUM Сумма операции
COMMISSION Комиссия за проведение операции с мерчанта
USER_INFO Маскированный номер карты или номер телефона ( в случае оплаты КИВИ кошельком)
ID Номер операции paymentId на стороне мерчанта
MERCH ID мерчанта
MERCH_SITE siteId мерчанта
PARENT_TRANSACTION_ID Для возвратов указывается номер исходной операции платежа
BILL ID выставленного счета
PURPOSE Тип проводки CHARGEBACK/ REVERT_CHARGEBACK/ Оплата/ Возврат/ OPERATION+/ OPERATION-/ SETTLEMENT
MERCHANT_SITE_NAME URL сайта мерчанта
PAYMENT_METHOD_TYPE Метод оплаты: Bank card/ QIWI_WALLET/ SBP
ММВБ Курс ММВБ на момент оплаты для валютных операций
CLIENT_AMOUNT Сумма списания с покупателя
CLIENT_CUR_CODE Валюта списания с покупателя
SETTLEMENT_AMOUNT Сумма платежного поручения, отправленного на расчетный счет партнера
PAYMENTDETAILS Назначение платежного поручения, отправленного на расчетный счет партнера (Пример: Перевод принятых денежных средств по Договору **** от ***. *** НДС не облагается/облагается.)

Возмещение

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

КИВИ взимает комиссию за каждую подтвержденную операцию. Если отмена операции была произведена до подтверждения, комиссия не взимается. Если была произведена частичная отмена до подтверждения операции, комиссия будет пересчитана.

Статусы и типы операций, коды ошибок

Коды ошибок

Протокол приема платежей использует для запросов API следующие HTTP-коды ошибок:

Код ошибки Описание
400 Bad Request — Ваш запрос некорректен (ошибка в данных или в формате запроса).
401 Unauthorized — Неправильный ключ доступа к API.
403 Forbidden — Доступ к API запрещен.
404 Not Found — Указанный ресурс не найден.
405 Method Not Allowed — Для создания платежа использовался неправильный метод.
406 Not Acceptable — Формат данных отличается от JSON.
410 Gone — Запрашиваемый ресурс удален.
429 Too Many Requests — Слишком много запросов.
500 Internal Server Error — Внутренняя ошибка сервиса. Если тело ответа пустое, повторите запрос с теми же параметрами. Если тело ответа не пустое, выполните запрос статуса платежа или статуса счета.
502 Bad Gateway — Нет связи с сервисом
503 Service Unavailable  — Сервер временно недоступен по техническим причинам, попробуйте позже.

Типы операций

Тип операции возвращается в поле {operation}.type уведомления.

Тип операции Описание
PAYMENT Платеж. В уведомлении может присутствовать поле flag: [ "SALE" ] (обычный платеж) или flag: [ "AUTH" ] (платеж с холдированием средств).
CAPTURE Операция подтверждения.
REFUND Операция возврата. В уведомлении может присутствовать поле flag: [ "REVERSAL" ]. Это значит, что финансовой операции (списания средств со счета покупателя) не было, комиссия по операции удержана не будет.

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

Статус операции отражает ее текущее состояние.

API возвращает синхронный статус операции в поле status.value.

В уведомлениях статус помещается в поле {operation}.status.value.

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

Статус операции Тип операции Описание статуса Где возвращается
WAITING PAYMENT Ожидание 3DS авторизации Ответы API
DECLINED PAYMENT Запрос авторизации отклонен Уведомления, Ответы API
DECLINE REFUND Запрос возврата отклонен Уведомления, Ответы API
DECLINE CAPTURE Запрос подтверждения отклонен Уведомления, Ответы API
DECLINED CAPTURE Запрос подтверждения отклонен Ответ API на запрос статуса
SUCCESS PAYMENT Запрос авторизации успешно обработан Уведомления
COMPLETED PAYMENT Запрос авторизации успешно обработан Ответы API
SUCCESS REFUND Запрос возврата успешно обработан Уведомления
COMPLETED REFUND Запрос возврата успешно обработан Ответы API
SUCCESS CAPTURE Запрос подтверждения успешно обработан Уведомления
COMPLETED CAPTURE Запрос подтверждения успешно обработан Ответы API

Справочник ошибок API

Ошибки API описывают причину отклонения операции и передаются:

Ошибка API Описание
INVALID_STATE Некорректный статус транзакции
INVALID_AMOUNT Некорректная сумма
INVALID_RECEIVER_DATA Ошибка при передаче данных о получателе
DECLINED_BY_MPI Отклонено MPI
DECLINED_BY_FRAUD Отклонено fraud-мониторингом
REATTEMPT_NOT_PERMITTED Повторный запрос авторизации запрещен на основании полученного ответа от Платежной системы
GATEWAY_INTEGRATION_ERROR Ошибка взаимодействия с банком
GATEWAY_TECHNICAL_ERROR Техническая ошибка на стороне банка
ACQUIRING_MPI_TECH_ERROR Техническая ошибка при проведении 3DS аутентификации
ACQUIRING_GATEWAY_TECH_ERROR Техническая ошибка
ACQUIRING_ACQUIRER_ERROR Техническая ошибка
ACQUIRING_AUTH_TECHNICAL_ERROR Ошибка при проведении авторизации средств
ACQUIRING_ISSUER_NOT_AVAILABLE Ошибка эмитента. Банк-эмитент не доступен
ACQUIRING_SUSPECTED_FRAUD Ошибка эмитента. Подозрение на мошенничество
ACQUIRING_LIMIT_EXCEEDED Ошибка эмитента. Превышен один из лимитов
ACQUIRING_NOT_PERMITTED Ошибка эмитента. Операция не разрешена
ACQUIRING_INCORRECT_CVV Ошибка эмитента. Некорректный CVV
ACQUIRING_EXPIRED_CARD Ошибка эмитента. Неверный срок действия карты
ACQUIRING_INVALID_CARD Ошибка эмитента. Проверьте корректность введенных данных
ACQUIRING_INSUFFICIENT_FUNDS Ошибка эмитента. Недостаточно средств
ACQUIRING_UNKNOWN Неизвестная ошибка
BILL_ALREADY_PAID Счет уже оплачен
PAYIN_PROCESSING_ERROR Ошибка при проведении платежа
QW_LIMIT_ERROR Ошибка превышения лимита пользователя QIWI Кошелька
QW_IDENTIFICATION_ERROR Пользователю необходимо пройти идентификацию в QIWI Кошельке
QW_AUTH_ERROR Ошибка авторизации в QIWI Кошельке
QW_INSUFFICIENT_FUNDS Недостаточно средств в QIWI Кошельке
QW_AMOUNT_ERROR Недопустимая сумма платежа
QW_REGISTRATION_ERROR Ошибка регистрации пользователя QIWI Кошелька
QW_AGENT_ERROR Ошибка при пополнении QIWI Кошелька пользователя
QW_ACCOUNT_ERROR QIWI Кошелек заблокирован
QW_IDENTIFICATION_STATUS_ERROR Достигнут лимит платежей в QIWI Кошельке
QW_CURRENCY_ERROR Валюта QIWI Кошелька не найдена
QW_PAYMENT_ERROR Ошибка проведения платежа в QIWI Кошельке
QW_PROVIDER_ERROR Провайдер QIWI Кошелька заблокирован
QW_SMS_CONFIRM_EXPIRED Истекло время СМС-подтверждения платежа в QIWI Кошельке

Справочник методов API

Создание счета

PUT /partner/payin/v1/sites/site-01/bills/893794793973 HTTP/1.1
Accept: application/json
Authorization: Bearer 5c4b25xx93aa435d9cb8cd17480356f9
Content-type: application/json
Host: api.qiwi.com

{
   "amount": {  
     "currency": "RUB",  
     "value": 100.00
   },
   "comment": "Text comment",
   "expirationDateTime": "2022-04-13T14:30:00+03:00",
   "customer": {},
   "customFields": {
     "cf1": "Some data",
     "FROM_MERCHANT_CONTRACT_ID": "1234"
   }
}

{
    "siteId": "23044",
    "billId": "893794793973",
    "amount": {
      "value": 100.00,
      "currency": "RUB"
    },
    "status": {
      "value": "CREATED",
      "changedDateTime": "2022-04-05T11:27:41"
    },
    "comment": "Text comment",
    "customFields": {
      "cf1": "Some data",
      "FROM_MERCHANT_CONTRACT_ID": "1234"
    },
    "creationDateTime": "2022-03-05T11:27:41",
    "expirationDateTime": "2022-04-13T14:30:00",
    "payUrl": "https://oplata.qiwi.com/form/?invoice_uid=d875277b-6f0f-445d-8a83-f62c7c07be77"
}

{
  "serviceName" : "payin-core",
  "errorCode" : "validation.error",
  "description" : "Validation error",
  "userMessage" : "Validation error",
  "dateTime" : "2022-03-05T11:49:59.166+03:00",
  "traceId" : "fd0e2a08c63ace83"
}

Статус счета

GET /partner/payin/v1/sites/site-01/bills/d35cf63943e54f50badc75f49a5aac7c/details HTTP/1.1
Accept: application/json
Authorization: Bearer 5c4b25xx93aa435d9cb8cd17480356f9
Content-type: application/json
Host: api.qiwi.com

{
  "billId": "d35cf63943e54f50badc75f49a5aac7c",
  "amount": {
    "value": 100.00,
    "currency": "RUB"
  },
  "status": {
    "value": "PAID",
    "changedDateTime": "2022-03-05T11:27:41"
  },
  "comment": "Text comment",
  "customFields": {
    "cf1": "Some data",
    "FROM_MERCHANT_CONTRACT_ID": "1234"
  },
  "expirationDateTime": "2022-04-13T14:30:00",
  "payUrl": "https://oplata.qiwi.com/form/invoice_uid=d875277b-6f0f-445d-8a83-f62c7c07be77",
  "payments": [
    {
        "siteId": "site-01",
        "billId": "d35cf63943e54f50badc75f49a5aac7c",
        "createdDateTime": "2022-03-05T11:23:49+03:00",
        "amount": {
            "currency": "RUB",
            "value": 100.00
        },
        "capturedAmount": {
            "currency": "RUB",
            "value": 100.00
        },
        "refundedAmount": {
            "currency": "RUB",
            "value": 0.00
        },
        "paymentMethod": {
            "type": "CARD",
            "maskedPan": "427638******1410"
        },
        "customer": {
            "account": "1",
            "phone": "0",
            "address": {}
        },
        "requirements": {
            "threeDS": {
                "pareq": "eJxVUWFvgjAQX7gM3fq+hNqO0oI5prexilN1UDEMwl6FcHZZ19m7v63DtRY=",
                "acsUrl": "https://ds1.mirconnect.ru:443/vbv/pareq"
            }
        },
        "status": {
            "value": "DECLINE",
            "changedDateTime": "2022-03-05T11:23:09+03:00",
            "reason": "ACQUIRING_NOT_PERMITTED"
        },
        "customFields": {
            "customer_account": "1",
            "customer_phone": "0"
        }
    },
    {
        "siteId": "site-01",
        "billId": "d35cf63943e54f50badc75f49a5aac7c",
        "createdDateTime": "2022-03-05T11:23:22+03:00",
        "amount": {
            "currency": "RUB",
            "value": 100.00
        },
        "capturedAmount": {
            "currency": "RUB",
            "value": 100.00
        },
        "refundedAmount": {
            "currency": "RUB",
            "value": 0.00
        },
        "paymentMethod": {
            "type": "CARD",
            "maskedPan": "427638******1410"
        },
        "customer": {
            "account": "1",
            "phone": "0",
            "address": {}
        },
        "requirements": {
            "threeDS": {
                "pareq": "eJxVUWFvgjAQ52lBUtjD3M9++qFgCxl0i/OtJv2WT/tv8LXqG0vw==",
                "acsUrl": "https://ds1.mirconnect.ru:443/vbv/pareq"
            }
        },
        "status": {
            "value": "DECLINED",
            "changedDateTime": "2022-03-05T11:23:54+03:00",
            "reason": "ACQUIRING_NOT_PERMITTED"
        },
        "customFields": {
            "customer_account": "1",
            "customer_phone": "0"
        }
    },
    {
        "siteId": "site-01",
        "billId": "d35cf63943e54f50badc75f49a5aac7c",
        "createdDateTime": "2022-03-05T11:26:21+03:00",
        "amount": {
            "currency": "RUB",
            "value": 100.00
        },
        "capturedAmount": {
            "currency": "RUB",
            "value": 100.00
        },
        "refundedAmount": {
            "currency": "RUB",
            "value": 0.00
        },
        "paymentMethod": {
            "type": "CARD",
            "maskedPan": "427638******1410",
            "rrn": "008692274763",
            "authCode": "242847"
        },
        "customer": {
            "account": "1",
            "phone": "0",
            "address": {}
        },
        "requirements": {
            "threeDS": {
                "pareq": "eJxVUdtuwjAM7b6t/1fcku04w==",
                "acsUrl": "https://ds1.mirconnect.ru:443/vbv/pareq"
            }
        },
        "status": {
            "value": "COMPLETED",
            "changedDateTime": "2022-03-05T11:34:43+03:00"
        },
        "customFields": {
            "customer_account": "1",
            "customer_phone": "0"
        }
    }
]

{
  "serviceName" : "payin-core",
  "errorCode" : "validation.error",
  "description" : "Validation error",
  "userMessage" : "Validation error",
  "dateTime" : "2022-03-05T16:49:59.166+03:00",
  "traceId" : "fd0e2a08c63ace83"
}

Получение списка платежей по счету

GET /partner/payin/v1/sites/site-01/bills/893794793973 HTTP/1.1
Accept: application/json
Authorization: Bearer 5c4b25xx93aa435d9cb8cd17480356f9
Content-type: application/json
Host: api.qiwi.com

[
    {
        "paymentId": "12600406",
        "billId": "d35cf63943e54f50badc75f49a5aac7c",
        "createdDateTime": "2020-03-26T19:31:49+03:00",
        "amount": {
            "currency": "RUB",
            "value": 10.00
        },
        "capturedAmount": {
            "currency": "RUB",
            "value": 10.00
        },
        "refundedAmount": {
            "currency": "RUB",
            "value": 0.00
        },
        "paymentMethod": {
            "type": "CARD",
            "maskedPan": "427638******1410"
        },
        "createdToken": {
            "token": "c5ba4a05-21c9-4a36-af7a-b709b4caa4d6",
            "name": "427638******1410"
        },
        "customer": {
            "account": "1",
            "phone": "0",
            "address": {}
        },
        "requirements": {
            "threeDS": {
                "pareq": "eJxVUWFvgjAQX7gM3fq+hNqO0oI5prexilN1UDEMwl6FcHZZ19m7v63DtRY=",
                "acsUrl": "https://ds1.mirconnect.ru:443/vbv/pareq"
            }
        },
        "status": {
            "value": "DECLINE",
            "changedDateTime": "2020-03-26T19:32:09+03:00",
            "reason": "ACQUIRING_NOT_PERMITTED"
        },
        "customFields": {
            "customer_account": "1",
            "customer_phone": "0"
        }
    },
    {
        "paymentId": "12600433",
        "billId": "d35cf63943e54f50badc75f49a5aac7c",
        "createdDateTime": "2020-03-26T19:32:22+03:00",
        "amount": {
            "currency": "RUB",
            "value": 10.00
        },
        "capturedAmount": {
            "currency": "RUB",
            "value": 10.00
        },
        "refundedAmount": {
            "currency": "RUB",
            "value": 0.00
        },
        "paymentMethod": {
            "type": "CARD",
            "maskedPan": "427638******1410"
        },
        "createdToken": {
            "token": "c5ba4a05-21c9-4a36-af7a-b709b4caa4d6",
            "name": "427638******1410"
        },
        "customer": {
            "account": "1",
            "phone": "0",
            "address": {}
        },
        "requirements": {
            "threeDS": {
                "pareq": "eJxVUWFvgjAQ52lBUtjD3M9++qFgCxl0i/OtJv2WT/tv8LXqG0vw==",
                "acsUrl": "https://ds1.mirconnect.ru:443/vbv/pareq"
            }
        },
        "status": {
            "value": "DECLINED",
            "changedDateTime": "2020-03-26T19:32:54+03:00",
            "reason": "ACQUIRING_NOT_PERMITTED"
        },
        "customFields": {
            "customer_account": "1",
            "customer_phone": "0"
        }
    },
    {
        "paymentId": "12601084",
        "billId": "d35cf63943e54f50badc75f49a5aac7c",
        "createdDateTime": "2020-03-26T19:46:21+03:00",
        "amount": {
            "currency": "RUB",
            "value": 10.00
        },
        "capturedAmount": {
            "currency": "RUB",
            "value": 10.00
        },
        "refundedAmount": {
            "currency": "RUB",
            "value": 0.00
        },
        "paymentMethod": {
            "type": "CARD",
            "maskedPan": "427638******1410",
            "rrn": "008692274763",
            "authCode": "242847"
        },
        "createdToken": {
            "token": "c5ba4a05-21c9-4a36-af7a-b709b4caa4d6",
            "name": "427638******1410"
        },
        "customer": {
            "account": "1",
            "phone": "0",
            "address": {}
        },
        "requirements": {
            "threeDS": {
                "pareq": "eJxVUdtuwjAM7b6t/1fcku04w==",
                "acsUrl": "https://ds1.mirconnect.ru:443/vbv/pareq"
            }
        },
        "status": {
            "value": "COMPLETED",
            "changedDateTime": "2020-03-26T19:46:43+03:00"
        },
        "customFields": {
            "customer_account": "1",
            "customer_phone": "0"
        }
    }
]

{
  "serviceName" : "payin-core",
  "errorCode" : "validation.error",
  "description" : "Validation error",
  "userMessage" : "Validation error",
  "dateTime" : "2018-11-13T16:49:59.166+03:00",
  "traceId" : "fd0e2a08c63ace83"
}

Платеж

PUT /partner/payin/v1/sites/test-01/payments/1811 HTTP/1.1
Accept: application/json
Authorization: Bearer 5c4b25xx93aa435d9cb8cd17480356f9
Content-type: application/json
Host: api.qiwi.com

{
  "billId": "string",
  "amount": {
    "currency": "RUB",
    "value": 200.00
  },
  "paymentMethod" : {
    "type" : "CARD",
    "pan" : "4444443616621049",
    "expiryDate" : "12/19",
    "cvv2" : "123",
    "holderName" : "CARDHOLDER NAME"
  },
  "callbackUrl": "https://example.com/callbacks",
  "comment": "Example payment",
  "customer": {
    "account": "string",
    "address": {
      "city": "Moscow",
      "country": "Russian Federation",
      "details": "Severnoe chertanovo microdistrict 1a 1",
      "region": "Moscow city"
    },
    "email": "customer@example.com",
    "phone": "+79991234567"
  },
  "deviceData": {
    "datetime": "2017-09-03T14:30:00+03:00",
    "fingerprint": "TW96aWxsYS81LjAgKHBsYXRmb3JtOyBydjpnZWNrb3ZlcnNpb24p",
    "ip": "127.0.0.1",
    "screenResolution": "1280x1024",
    "timeOnPage": 1440,
    "userAgent": "Mozilla/5.0 (platform; rv:geckoversion) Gecko/geckotrail Firefox/firefoxversion"
  },
  "customFields": {
    "cf1": "Some data",
    "FROM_MERCHANT_CONTRACT_ID": "1234"
  },
  "flags": [
    "SALE"
  ]
}

{
  "paymentId" : "223E",
  "createdDatetime" : "2018-11-01T17:10:31.284+03:00",
  "amount" : {
    "currency" : "RUB",
    "value" : 200.00
  },
  "capturedAmount" : {
    "currency" : "RUB",
    "value" : 0.00
  },
  "refundedAmount" : {
    "currency" : "RUB",
    "value" : 0.00
  },
  "paymentMethod" : {
    "type" : "CARD",
    "maskedPan" : "444444******1049"
  },
  "customer" : { },
  "deviceData" : { },
  "requirements" : {
    "threeDS" : {
      "pareq" : "eJyrrgUAAXUA+Q==",
      "acsUrl" : "https://test.paymentgate.ru/acs/auth/start.do"
    }
  },
  "status" : {
    "value" : "WAITING",
    "changedDateTime" : "2018-11-01T17:10:32.607+03:00"
  },
  "paymentCardInfo": {
    "issuingCountry": "810",
    "issuingBank": "QiwiBank",
    "paymentSystem": "VISA",
    "fundingSource": "CREDIT",
    "paymentSystemProduct": "P|Visa Gold"
  },
  "customFields" : {
    "cf1": "Some data",
    "FROM_MERCHANT_CONTRACT_ID": "1234"
  },
  "flags" : [ ]
}

{
  "serviceName" : "payin-core",
  "errorCode" : "validation.error",
  "description" : "Validation error",
  "userMessage" : "Validation error",
  "dateTime" : "2018-11-13T16:49:59.166+03:00",
  "traceId" : "fd0e2a08c63ace83"
}

{
  "serviceName":"payin-core",
  "errorCode":"internal.error",
  "userMessage":"Internal error",
  "description":"Internal error",
  "traceId":"3fb3420ee1795dcf",
  "dateTime":"2020-02-12T21:28:01.813+03:00"
}

Статус платежа

GET /partner/payin/v1/sites/test-01/payments/1811 HTTP/1.1
Accept: application/json
Authorization: Bearer 5c4b25xx93aa435d9cb8cd17480356f9
Content-type: application/json
Host: api.qiwi.com

{
  "paymentId" : "223E",
  "createdDatetime" : "2018-11-01T17:10:31.284+03:00",
  "amount" : {
    "currency" : "RUB",
    "value" : 200.00
  },
  "capturedAmount" : {
    "currency" : "RUB",
    "value" : 0.00
  },
  "refundedAmount" : {
    "currency" : "RUB",
    "value" : 0.00
  },
  "paymentMethod" : {
    "type" : "CARD",
    "maskedPan" : "444444******1049",
    "rrn": "124",
    "authCode": "182817",
  },
  "customer" : { },
  "deviceData" : { },
  "requirements" : {
    "threeDS" : {
      "pareq" : "eJyrrgUAAXUA+Q==",
      "acsUrl" : "https://test.paymentgate.ru/acs/auth/start.do"
    }
  },
  "status" : {
    "value" : "WAITING",
    "changedDateTime" : "2018-11-01T17:10:32.607+03:00"
  },
  "customFields" : { },
  "flags" : [ ]
}

{
  "serviceName" : "payin-core",
  "errorCode" : "validation.error",
  "description" : "Validation error",
  "userMessage" : "Validation error",
  "dateTime" : "2018-11-13T16:49:59.166+03:00",
  "traceId" : "fd0e2a08c63ace83"
}

{
  "serviceName":"payin-core",
  "errorCode":"internal.error",
  "userMessage":"Internal error",
  "description":"Internal error",
  "traceId":"3fb3420ee1795dcf",
  "dateTime":"2020-02-12T21:28:01.813+03:00"
}

Завершение аутентификации клиента

POST /partner/payin/v1/sites/test-01/payments/1811/complete HTTP/1.1
Accept: application/json
Authorization: Bearer 5c4b25xx93aa435d9cb8cd17480356f9
Content-type: application/json
Host: api.qiwi.com

{
  "threeDS": {
    "pares": "eJzVWFevo9iyfu9fMZrzaM0QjWHk3tIiGptgooE3cgabYMKvv3jvTurTc3XOfbkaJMuL...."
  }
}

{
  "paymentId" : "223E",
  "createdDatetime" : "2018-11-01T17:10:31.284+03:00",
  "amount" : {
    "currency" : "RUB",
    "value" : 200.00
  },
  "capturedAmount" : {
    "currency" : "RUB",
    "value" : 0.00
  },
  "refundedAmount" : {
    "currency" : "RUB",
    "value" : 0.00
  },
  "paymentMethod" : {
    "type" : "CARD",
    "maskedPan" : "444444******1049"
  },
  "customer" : { },
  "deviceData" : { },
  "requirements" : {
    "threeDS" : {
      "pareq" : "eJyrrgUAAXUA+Q==",
      "acsUrl" : "https://test.paymentgate.ru/acs/auth/start.do"
    }
  },
  "status" : {
    "value" : "COMPLETED",
    "changedDateTime" : "2018-11-01T17:10:32.607+03:00"
  },
  "customFields" : { },
  "flags" : [ ]
}

{
  "serviceName" : "payin-core",
  "errorCode" : "validation.error",
  "description" : "Validation error",
  "userMessage" : "Validation error",
  "dateTime" : "2018-11-13T16:49:59.166+03:00",
  "traceId" : "fd0e2a08c63ace83"
}

{
  "serviceName":"payin-core",
  "errorCode":"internal.error",
  "userMessage":"Internal error",
  "description":"Internal error",
  "traceId":"3fb3420ee1795dcf",
  "dateTime":"2020-02-12T21:28:01.813+03:00"
}

Подтверждение платежа

PUT /partner/payin/v1/sites/test-01/payments/1811/captures/bxwd8096 HTTP/1.1
Accept: application/json
Authorization: Bearer 5c4b25xx93aa435d9cb8cd17480356f9
Content-type: application/json
Host: api.qiwi.com

{
  "callbackUrl": "https://example.com/callbacks",
  "comment": "Example capture"
}

{
  "captureId": "bxwd8096",
  "createdDatetime": "2018-11-20T16:29:58.96+03:00",
  "amount": {
    "currency": "RUB",
    "value": 6.77
  },
  "status": {
    "value": "COMPLETED",
    "changedDateTime": "2018-11-20T16:29:58.963+03:00"
  }
}

{
  "serviceName" : "payin-core",
  "errorCode" : "validation.error",
  "description" : "Validation error",
  "userMessage" : "Validation error",
  "dateTime" : "2018-11-13T16:49:59.166+03:00",
  "traceId" : "fd0e2a08c63ace83"
}

{
  "serviceName":"payin-core",
  "errorCode":"internal.error",
  "userMessage":"Internal error",
  "description":"Internal error",
  "traceId":"3fb3420ee1795dcf",
  "dateTime":"2020-02-12T21:28:01.813+03:00"
}

Статус подтверждения

GET /partner/payin/v1/sites/test-01/payments/1811/captures/bxwd8096 HTTP/1.1
Accept: application/json
Authorization: Bearer 5c4b25xx93aa435d9cb8cd17480356f9
Content-type: application/json
Host: api.qiwi.com

{
  "captureId": "bxwd8096",
  "createdDatetime": "2018-11-20T16:29:58.96+03:00",
  "amount": {
    "currency": "RUB",
    "value": 6.77
  },
  "status": {
    "value": "COMPLETED",
    "changedDateTime": "2018-11-20T16:29:58.963+03:00"
  }
}

{
  "serviceName" : "payin-core",
  "errorCode" : "validation.error",
  "description" : "Validation error",
  "userMessage" : "Validation error",
  "dateTime" : "2018-11-13T16:49:59.166+03:00",
  "traceId" : "fd0e2a08c63ace83"
}

{
  "serviceName":"payin-core",
  "errorCode":"internal.error",
  "userMessage":"Internal error",
  "description":"Internal error",
  "traceId":"3fb3420ee1795dcf",
  "dateTime":"2020-02-12T21:28:01.813+03:00"
}

Получение QR-кода СБП

Метод PUT

PUT /partner/payin/v1/sites/test-01/sbp/qrCodes/adghj17d1g8 HTTP/1.1
Accept: application/json
Authorization: Bearer 5c4b25xx93aa435d9cb8cd17480356f9
Content-type: application/json
Host: api.qiwi.com

{
  "amount": {
    "value": 100.00,
    "currency": "RUB"
  },
  "qrCode": {
    "type": "DYNAMIC",
    "ttl": 999,
    "image": {
      "mediaType": "image/png",
      "width": "300",
      "height": "300"
    }
  },
  "paymentPurpose": "Flower for my girlfriend",
  "redirectUrl": "http://someurl.com"
}

{
  "qrCodeUid": "adghj17d1g8",
  "amount": {
    "value": 100.00,
    "currency": "RUB"
  },
  "paymentPurpose": "Flower for my girlfriend",
  "redirectUrl": "http://someurl.com",
  "qrCode": {
    "type": "DYNAMIC",
    "ttl": 999,
    "status": "CREATED",
    "payload": "",
    "image": {
      "content": "Base64 string",
      "mediaType": "image/png",
      "width": "300",
      "height": "300",
    }
  },
  "payment": {
    "paymentUid": "12s1s21",
    "paymentStatus": "WAITING",
  }
}

{
  "serviceName" : "payin-core",
  "errorCode" : "validation.error",
  "description" : "Validation error",
  "userMessage" : "Validation error",
  "dateTime" : "2018-11-13T16:49:59.166+03:00",
  "traceId" : "fd0e2a08c63ace83"
}

{
  "serviceName":"payin-core",
  "errorCode":"internal.error",
  "userMessage":"Internal error",
  "description":"Internal error",
  "traceId":"3fb3420ee1795dcf",
  "dateTime":"2020-02-12T21:28:01.813+03:00"
}

Метод POST

POST /partner/payin/v1/sites/test-01/sbp/qrCodes HTTP/1.1
Accept: application/json
Authorization: Bearer 5c4b25xx93aa435d9cb8cd17480356f9
Content-type: application/json
Host: api.qiwi.com

{
  "qrCodeUid": "adghj17d1g8",
  "amount": {
    "value": 100.00,
    "currency": "RUB"
  },
  "qrCode": {
    "type": "DYNAMIC",
    "ttl": 999,
    "image": {
      "mediaType": "image/png",
      "width": "300",
      "height": "300"
    }
  },
  "paymentPurpose": "Flower for my girlfriend",
  "redirectUrl": "http://someurl.com"
}

{
  "qrCodeUid": "adghj17d1g8",
  "amount": {
    "value": 100.00,
    "currency": "RUB"
  },
  "paymentPurpose": "Flower for my girlfriend",
  "redirectUrl": "http://someurl.com",
  "qrCode": {
    "type": "DYNAMIC",
    "ttl": 999,
    "status": "CREATED",
    "payload": "",
    "image": {
      "content": "Base64 string",
      "mediaType": "image/png",
      "width": "300",
      "height": "300",
    }
  },
  "payment": {
    "paymentUid": "12s1s21",
    "paymentStatus": "WAITING",
  }
}

{
  "serviceName" : "payin-core",
  "errorCode" : "validation.error",
  "description" : "Validation error",
  "userMessage" : "Validation error",
  "dateTime" : "2018-11-13T16:49:59.166+03:00",
  "traceId" : "fd0e2a08c63ace83"
}

{
  "serviceName":"payin-core",
  "errorCode":"internal.error",
  "userMessage":"Internal error",
  "description":"Internal error",
  "traceId":"3fb3420ee1795dcf",
  "dateTime":"2020-02-12T21:28:01.813+03:00"
}

Статус QR-кода СБП

GET /partner/payin/v1/sites/test-01/sbp/qrCodes/adghj17d1g8 HTTP/1.1
Accept: application/json
Authorization: Bearer 5c4b25xx93aa435d9cb8cd17480356f9
Content-type: application/json
Host: api.qiwi.com

{
  "qrCodeUid": "adghj17d1g8",
  "amount": {
    "value": 100.00,
    "currency": "RUB"
  },
  "paymentPurpose": "Flower for my girlfriend",
  "redirectUrl": "http://someurl.com",
  "qrCode": {
    "type": "DYNAMIC",
    "ttl": 999,
    "status": "CREATED",
    "payload": "",
    "image": {
      "content": "Base64 string",
      "mediaType": "image/png",
      "width": "300",
      "height": "300",
    }
  },
  "payment": {
    "paymentUid": "12s1s21",
    "paymentStatus": "WAITING",
  }
}

{
  "serviceName" : "payin-core",
  "errorCode" : "validation.error",
  "description" : "Validation error",
  "userMessage" : "Validation error",
  "dateTime" : "2018-11-13T16:49:59.166+03:00",
  "traceId" : "fd0e2a08c63ace83"
}

{
  "serviceName":"payin-core",
  "errorCode":"internal.error",
  "userMessage":"Internal error",
  "description":"Internal error",
  "traceId":"3fb3420ee1795dcf",
  "dateTime":"2020-02-12T21:28:01.813+03:00"
}

Платеж токеном СБП

PUT /partner/payin/v1/sites/test-01/sbp/qrCodes/adghj17d1g8/payments/11212334csd HTTP/1.1
Accept: application/json
Authorization: Bearer 5c4b25xx93aa435d9cb8cd17480356f9
Content-type: application/json
Host: api.qiwi.com

{
  "tokenizationAccount": "customer123",
  "token": "c5ba4a05-21c9-4a36-af7a-b709b4caa4d6"
}

{
  "qrCodeUid": "adghj17d1g8",
  "amount": {
    "value": 100.00,
    "currency": "RUB"
  },
  "paymentPurpose": "Flower for my girlfriend",
  "redirectUrl": "http://someurl.com",
  "qr": {
    "type": "DYNAMIC",
    "ttl": 999,
    "status": "CREATED",
    "payload": "",
    "image": {
      "content": "Base64 string",
      "mediaType": "image/png",
      "width": "300",
      "height": "300",
    }
  },
  "payment": {
    "paymentUid": "12s1s21",
    "paymentStatus": "WAITING",
  }
}

{
  "serviceName" : "payin-core",
  "errorCode" : "validation.error",
  "description" : "Validation error",
  "userMessage" : "Validation error",
  "dateTime" : "2018-11-13T16:49:59.166+03:00",
  "traceId" : "fd0e2a08c63ace83"
}

{
  "serviceName":"payin-core",
  "errorCode":"internal.error",
  "userMessage":"Internal error",
  "description":"Internal error",
  "traceId":"3fb3420ee1795dcf",
  "dateTime":"2020-02-12T21:28:01.813+03:00"
}

Операция возврата

PUT /partner/payin/v1/sites/test-01/payments/1811/refunds/tcwv3132 HTTP/1.1
Accept: application/json
Authorization: Bearer 5c4b25xx93aa435d9cb8cd17480356f9
Content-type: application/json
Host: api.qiwi.com

{
  "amount": {
    "value": 2.34,
    "currency": "RUB"
  }
}

{
  "refundId": "tcwv3132",
  "createdDatetime": "2018-11-20T16:32:55.547+03:00",
  "amount": {
    "currency": "RUB",
    "value": 2.34
  },
  "status": {
    "value": "COMPLETED",
    "changedDateTime": "2018-11-20T16:32:55.55+03:00"
  },
  "flags": [
    "REVERSAL"
  ]
}

{
  "serviceName" : "payin-core",
  "errorCode" : "validation.error",
  "description" : "Validation error",
  "userMessage" : "Validation error",
  "dateTime" : "2018-11-13T16:49:59.166+03:00",
  "traceId" : "fd0e2a08c63ace83"
}

{
  "serviceName":"payin-core",
  "errorCode":"internal.error",
  "userMessage":"Internal error",
  "description":"Internal error",
  "traceId":"3fb3420ee1795dcf",
  "dateTime":"2020-02-12T21:28:01.813+03:00"
}

Статус возврата

GET /partner/payin/v1/sites/test-01/payments/1811/refunds/tcwv3132 HTTP/1.1
Accept: application/json
Authorization: Bearer 5c4b25xx93aa435d9cb8cd17480356f9
Content-type: application/json
Host: api.qiwi.com

{
  "refundId": "tcwv3132",
  "createdDatetime": "2018-11-20T16:32:55.547+03:00",
  "amount": {
    "currency": "RUB",
    "value": 2.34
  },
  "status": {
    "value": "COMPLETED",
    "changedDateTime": "2018-11-20T16:32:55.55+03:00"
  },
  "flags": [
    "REVERSAL"
  ]
}

{
  "serviceName" : "payin-core",
  "errorCode" : "validation.error",
  "description" : "Validation error",
  "userMessage" : "Validation error",
  "dateTime" : "2018-11-13T16:49:59.166+03:00",
  "traceId" : "fd0e2a08c63ace83"
}

Статус возвратов

GET /partner/payin/v1/sites/test-01/payments/1811/refunds HTTP/1.1
Accept: application/json
Authorization: Bearer 5c4b25xx93aa435d9cb8cd17480356f9
Content-type: application/json
Host: api.qiwi.com

[
 {
  "refundId": "tcwv3132",
  "createdDatetime": "2018-11-20T16:32:55.547+03:00",
  "amount": {
    "currency": "RUB",
    "value": 2.34
  },
  "status": {
    "value": "COMPLETED",
    "changedDateTime": "2018-11-20T16:32:55.55+03:00"
  },
  "flags": [
    "REVERSAL"
  ]
 }
]

{
  "serviceName" : "payin-core",
  "errorCode" : "validation.error",
  "description" : "Validation error",
  "userMessage" : "Validation error",
  "dateTime" : "2018-11-13T16:49:59.166+03:00",
  "traceId" : "fd0e2a08c63ace83"
}

{
  "serviceName":"payin-core",
  "errorCode":"internal.error",
  "userMessage":"Internal error",
  "description":"Internal error",
  "traceId":"3fb3420ee1795dcf",
  "dateTime":"2020-02-12T21:28:01.813+03:00"
}

Операция возврата по платежу СБП

Метод PUT

PUT /partner/payin/v1/sites/test-01/sbp/qrCodes/adghj17d1g8/refunds/asdvas7dvasd6va HTTP/1.1
Accept: application/json
Authorization: Bearer 5c4b25xx93aa435d9cb8cd17480356f9
Content-type: application/json
Host: api.qiwi.com

{
  "amount": {
    "value": 100.00,
    "currency": "RUB"
  }
}

{
  "qrCodeUid": "adghj17d1g8",
  "amount": {
    "value": 100.00,
    "currency": "RUB"
  },
  "paymentPurpose": "Flower for my girlfriend",
  "redirectUrl": "http://someurl.com",
  "tokenizationPurpose": "",
  "flags": ["CREATE_TOKEN"],
  "qr": {
    "type": "DYNAMIC",
    "ttl": 999,
    "status": "CREATED",
    "payload": "",
    "image": {
      "content": "Base64 string",
      "mediaType": "image/png",
      "width": "300",
      "height": "300",
    }
  },
  "token": {
    "status": "CREATED",
    "value": "f9ac0f47-1111-2222-b947-33339cdacbc9",
    "expiredDate": "2022-05-03T14:30:00+03:00",
  },
  "payment": {
    "paymentUid": "12s1s21",
    "paymentStatus": "COMPLETED"
  },
  "refunds": [
    {
      "refundUid": "dqw2dx2",
      "refundStatus": "WAITING"
    }
  ]
}

{
  "serviceName" : "payin-core",
  "errorCode" : "validation.error",
  "description" : "Validation error",
  "userMessage" : "Validation error",
  "dateTime" : "2018-11-13T16:49:59.166+03:00",
  "traceId" : "fd0e2a08c63ace83"
}

{
  "serviceName":"payin-core",
  "errorCode":"internal.error",
  "userMessage":"Internal error",
  "description":"Internal error",
  "traceId":"3fb3420ee1795dcf",
  "dateTime":"2020-02-12T21:28:01.813+03:00"
}

Метод POST

POST /partner/payin/v1/sites/test-01/sbp/qrCodes/adghj17d1g8/refunds HTTP/1.1
Accept: application/json
Authorization: Bearer 5c4b25xx93aa435d9cb8cd17480356f9
Content-type: application/json
Host: api.qiwi.com

{
  "refundUid": "asdvas7dvasd6va",
  "amount": {
    "value": 100.00,
    "currency": "RUB"
  }
}

{
  "qrCodeUid": "adghj17d1g8",
  "amount": {
    "value": 100.00,
    "currency": "RUB"
  },
  "paymentPurpose": "Flower for my girlfriend",
  "redirectUrl": "http://someurl.com",
  "tokenizationPurpose": "",
  "flags": ["CREATE_TOKEN"],
  "qr": {
    "type": "DYNAMIC",
    "ttl": 999,
    "status": "CREATED",
    "payload": "",
    "image": {
      "content": "Base64 string",
      "mediaType": "image/png",
      "width": "300",
      "height": "300",
    }
  },
  "token": {
    "status": "CREATED",
    "value": "f9ac0f47-1111-2222-b947-33339cdacbc9",
    "expiredDate": "2022-05-03T14:30:00+03:00",
  },
  "payment": {
    "paymentUid": "12s1s21",
    "paymentStatus": "COMPLETED"
  },
  "refunds": [
    {
      "refundUid": "dqw2dx2",
      "refundStatus": "WAITING"
    }
  ]
}

{
  "serviceName" : "payin-core",
  "errorCode" : "validation.error",
  "description" : "Validation error",
  "userMessage" : "Validation error",
  "dateTime" : "2018-11-13T16:49:59.166+03:00",
  "traceId" : "fd0e2a08c63ace83"
}

{
  "serviceName":"payin-core",
  "errorCode":"internal.error",
  "userMessage":"Internal error",
  "description":"Internal error",
  "traceId":"3fb3420ee1795dcf",
  "dateTime":"2020-02-12T21:28:01.813+03:00"
}

Проверка карты

GET /partner/payin/v1/sites/test-01/validation/card/requests/acd7bf20-22e2-4cbf-a218-38d90e9f29b9 HTTP/1.1
Accept: application/json
Authorization: Bearer 5c4b25xx93aa435d9cb8cd17480356f9
Content-type: application/json
Host: api.qiwi.com

{
    "cardData": {
        "pan": "1111222233334444",
        "expiryDate": "12/34",
        "cvv2": "123",
        "holderName": "Super Man"
    },
    "tokenizationData": {
        "account": "cat_girl"
    }
}

{
    "requestUid": "acd7bf20-22e2-4cbf-a218-38d90e9f29b9",
    "status": "SUCCESS",
    "isValidCard": true,
    "threeDsStatus": "WITHOUT",
    "checkOperationDate": "2021-07-29T16:30:00+03:00",
    "cardInfo": {
        "issuingCountry": "RUS",
        "issuingBank": "Qiwi bank",
        "paymentSystem": "VISA",
        "fundingSource": "DEBIT",
        "paymentSystemProduct": "Platinum..."
    },
    "createdToken": {
        "token": "1a77343a-dd8a-11eb-ba80-0242ac130004",
        "name": "111122******4444",
        "expiredDate": "2034-12-01T00:00:00+03:00",
        "account": "cat_girl"
    }
}

{
  "serviceName" : "payin-core",
  "errorCode" : "validation.error",
  "description" : "Validation error",
  "userMessage" : "Validation error",
  "dateTime" : "2018-11-13T16:49:59.166+03:00",
  "traceId" : "fd0e2a08c63ace83"
}

{
  "serviceName":"payin-core",
  "errorCode":"internal.error",
  "userMessage":"Internal error",
  "description":"Internal error",
  "traceId":"3fb3420ee1795dcf",
  "dateTime":"2020-02-12T21:28:01.813+03:00"
}

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

GET /partner/payin/v1/sites/test-01/validation/card/requests/acd7bf20-22e2-4cbf-a218-38d90e9f29b9 HTTP/1.1
Accept: application/json
Authorization: Bearer 5c4b25xx93aa435d9cb8cd17480356f9
Content-type: application/json
Host: api.qiwi.com

{
    "requestUid": "acd7bf20-22e2-4cbf-a218-38d90e9f29b9",
    "status": "SUCCESS",
    "isValidCard": true,
    "threeDsStatus": "WITHOUT",
    "checkOperationDate": "2021-07-29T16:30:00+03:00",
    "cardInfo": {
        "issuingCountry": "RUS",
        "issuingBank": "Qiwi bank",
        "paymentSystem": "VISA",
        "fundingSource": "DEBIT",
        "paymentSystemProduct": "Platinum..."
    },
    "createdToken": {
        "token": "1a77343a-dd8a-11eb-ba80-0242ac130004",
        "name": "111122******4444",
        "expiredDate": "2034-12-01T00:00:00+03:00",
        "account": "cat_girl"
    }
}

{
  "serviceName" : "payin-core",
  "errorCode" : "validation.error",
  "description" : "Validation error",
  "userMessage" : "Validation error",
  "dateTime" : "2018-11-13T16:49:59.166+03:00",
  "traceId" : "fd0e2a08c63ace83"
}

{
  "serviceName":"payin-core",
  "errorCode":"internal.error",
  "userMessage":"Internal error",
  "description":"Internal error",
  "traceId":"3fb3420ee1795dcf",
  "dateTime":"2020-02-12T21:28:01.813+03:00"
}

Завершение аутентификации при проверке карты

POST /partner/payin/v1/sites/test-01/validation/card/requests/acd7bf20-22e2-4cbf-a218-38d90e9f29b9/complete HTTP/1.1
Accept: application/json
Authorization: Bearer 5c4b25xx93aa435d9cb8cd17480356f9
Content-type: application/json
Host: api.qiwi.com

{
    "pares": "eJzVWFevo9iyfu9fMZrzaM0QjWHk3tIiGptgooE3cgabYMKvv3jvTurTc3XOfbkaJMuL...."
}

{
    "requestUid": "acd7bf20-22e2-4cbf-a218-38d90e9f29b9",
    "status": "SUCCESS",
    "isValidCard": true,
    "threeDsStatus": "PASSED",
    "checkOperationDate": "2021-07-29T16:30:00+03:00",
    "cardInfo": {
        "issuingCountry": "RUS",
        "issuingBank": "Qiwi bank",
        "paymentSystem": "VISA",
        "fundingSource": "DEBIT",
        "paymentSystemProduct": "Platinum..."
    },
    "createdToken": {
        "token": "1a77343a-dd8a-11eb-ba80-0242ac130004",
        "name": "111122******4444",
        "expiredDate": "2034-12-01T00:00:00+03:00",
        "account": "cat_girl"
    }
}

{
  "serviceName" : "payin-core",
  "errorCode" : "validation.error",
  "description" : "Validation error",
  "userMessage" : "Validation error",
  "dateTime" : "2018-11-13T16:49:59.166+03:00",
  "traceId" : "fd0e2a08c63ace83"
}

{
  "serviceName":"payin-core",
  "errorCode":"internal.error",
  "userMessage":"Internal error",
  "description":"Internal error",
  "traceId":"3fb3420ee1795dcf",
  "dateTime":"2020-02-12T21:28:01.813+03:00"
}

Передача чека (54-ФЗ)

Для работы по 54-ФЗ Протокол приема платежей предоставляет инструмент для взаимодействия с вашей онлайн-кассой. Информация для формирования фискального чека передается в JSON-объекте cheque в операциях API выставления счета и платежа.

Для активации сервиса формирования фискального чека сообщите вашему сопровождающему менеджеру номер ИНН, с которым ваша организация зарегистрирована в сервисе по аренде онлайн-касс.

Если используется Атол, то дополнительно предоставьте сведения:

Описание объекта cheque

{
 .. 
"cheque":{
  "sellerId": 3123011520,
  "customerContact": "Test customer contact",
  "chequeType": "COLLECT",
  "taxSystem": "OSN",
  "positions": [
    {
      "quantity": 1,
      "price": {
        "value": 7.82,
        "currency": "RUB"
      },
      "tax": "NDS_0",
      "paymentSubject": "PAYMENT",
      "paymentMethod": "FULL_PAYMENT",
      "description": "Test description"
    }
  ]
 }
}
Параметр Условие Тип данных Описание
sellerId Обязательно decimal ИНН организации, для которой пробивается чек
chequeType Обязательно decimal Признак расчета (тэг 1054):
COLLECT – Приход
COLLECT_RETURN - Возврат прихода
CONSUME - Расход
CONSUME_RETURN -Возврат расхода
customerContact Обязательно string(64) Телефон или электронный адрес покупателя (тэг 1008)
taxSystem Обязательно decimal Система налогообложения (тэг 1055):
OSN - Общая, ОСН
USN – Упрощенная доход, УСН доход
USN_MINUS_CONSUM – Упрощенная доход минус расход, УСН доход - расход
ENVD – Единый налог на вмененный доход, ЕНВД
ESN - Единый сельскохозяйственный налог, ЕСН
PATENT – Патентная система налогообложения, Патент
positions Обязательно array Массив товаров
quantity Обязательно decimal Количество предмета расчета (тэг 1023)
price Обязательно decimal Цена за единицу предмета расчета с учетом скидок и наценок (тэг 1079)
tax Обязательно decimal Ставка НДС (тэг 1199):
NDS_CALC_18_118 - с учетом НДС 18% (18/118)
NDS_CALC_10_110 – с учетом НДС 10% (10/110)
NDS_0 – ставка НДС 0%
NO_NDS – НДС не облагается
NDS_CALC_20_120 – с учетом НДС 20% (20/120) (20/120)
description Обязательно string(128) Наименование предмета расчета
paymentMethod Обязательно decimal Признак способа расчёта (тэг 1214):
ADVANCED_FULL_PAYMENT – предоплата 100%. Полная предварительная оплата до момента передачи предмета расчета.
PARTIAL_ADVANCE_PAYMENT – предоплата. Частичная предварительная оплата до момента передачи предмета расчета.
ADVANCE – аванс.
FULL_PAYMENT – полный расчет. Полная оплата, в том числе с учетом аванса (предварительной оплаты) в момент передачи предмета расчета.
PARTIAL_PAYMENT – частичный расчет и кредит. Частичная оплата предмета расчета в момент его передачи с последующей оплатой в кредит.
CREDIT – передача в кредит. Передача предмета расчета без его оплаты в момент его передачи с последующей оплатой в кредит.
CREDIT_PAYMENT – оплата кредита. Оплата предмета расчета после его передачи с оплатой в кредит (оплата кредита).
paymentSubject Обязательно decimal Признак предмета расчёта (тэг 1212):
COMMODITY – товар. О реализуемом товаре, за исключением подакцизного товара (наименование и иные сведения, описывающие товар).
EXCISE_COMMODITY – подакцизный товар. О реализуемом подакцизном товаре (наименование и иные сведения, описывающие товар).
WORK – работа. О выполняемой работе (наименование и иные сведения, описывающие работу).
SERVICE – услуга. Об оказываемой услуге (наименование и иные сведения, описывающие услугу).
GAMBLING_RATE – ставка азартной игры. О приеме ставок при осуществлении деятельности по проведению азартных игр.
GAMBLING_PRIZE – выигрыш азартной игры. О выплате денежных средств в виде выигрыша при осуществлении деятельности по проведению азартных игр.
LOTTERY_TICKET – лотерейный билет. О приеме денежных средств при реализации лотерейных билетов, электронных лотерейных билетов, приеме лотерейных ставок при осуществлении деятельности по проведению лотерей.
LOTTERY_PRIZE – выигрыш лотереи. О выплате денежных средств в виде выигрыша при осуществлении деятельности по проведению лотерей.
GRANTING_RESULTS_OF_INTELLECTUAL_ACTIVITY – предоставление результатов интеллектуальной деятельности. О предоставлении прав на использование результатов интеллектуальной деятельности или средств индивидуализации.
PAYMENT – платеж. Об авансе, задатке, предоплате, кредите, взносе в счет оплаты, пени, штрафе, вознаграждении, бонусе и ином аналогичном предмете расчета.
AGENCY_FEE – агентское вознаграждение. О вознаграждении пользователя, являющегося платежным агентом (субагентом), банковским платежным агентом (субагентом), комиссионером, поверенным или иным агентом.
COMPAUND_PAYMENT_SUBJECT – составной предмет расчета. О предмете расчета, состоящем из предметов, каждому из которых может быть присвоено значение выше перечисленных признаков.
OTHER_PAYMENT_SUBJECT – иной предмет расчета. О предмете расчета, не относящемуся к выше перечисленным предметам расчета.
Примеры