Обзор протокола
Последнее обновление: 2022-04-18| Версия 1.8 | Редактировать на GitHub
Протокол приема платежей предоставляет быстрые и безопасные решения для приема и отправки платежей в интернете. Протокол дает вашим покупателям возможность использовать разнообразные методы платежей, включая:
- Банковские карты Visa, Mastercard, МИР.
- Apple Pay
- Google Pay.
- Yandex Pay.
- QIWI Кошелек.
- Система Быстрых Платежей (СБП).
Термины и сокращения
Ключ доступа к 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 | × | ✓ |
Оплата через СБП | × | ✓ |
Оплата с баланса КИВИ Кошелька | ✓ | ✓** |
*
— метод оплаты доступен по умолчанию, другие методы оплаты подключаются по запросу.
**
— посредством выпуска платежного токена для КИВИ кошелька.
Типы операций
В Протоколе доступны следующие операции:
- Счет (Invoice) — электронный документ, выставляемый продавцом покупателю. Содержит информацию о сумме и номере заказа. Не является финансовой сущностью и имеет ограниченный срок жизни. Выставление счета необходимо для получения ссылки на платежную форму QIWI.
- Платеж (Payment) — операция списания денежных средств от покупателя в пользу продавца. Фактическое списание происходит только после подтверждения (Capture). При работе через платежную форму QIWI, Payment — попытка оплаты счета (Invoice).
- Завершение (Complete) — завершение 3DS-верификации Покупателя. Используется при работе через Платежную форму мерчанта.
- Подтверждение (Capture) — операция подтверждения авторизации (списания) средств.
- Возврат (Refund) — возврат средств покупателю по успешному платежу. Финансовая операция списания денежных средств от продавца в пользу покупателя. Если подтверждения операции Payment не было, то в ответе на операцию Refund вы получите флаг Reversal и деньги со счета Покупателя на счет продавца не перечислятся (комиссия за эквайринг также не удерживается).
Общая схема проведения платежа и взаиморасчетов
мерчанта 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 цифры).
Для тестирования различных вариантов оплаты и ответов необходимо использовать различные сроки действия карты:
- Если месяц срока действия —
02
, то операция будет проведена неуспешно. - Если месяц срока действия —
03
, то операция будет проведена успешно с задержкой в 3 секунды. - Если месяц срока действия —
04
, то операция будет проведена неуспешно с задержкой в 3 секунды. - Во всех остальных случая операция выполняется успешно.
В тестовой среде установлено ограничение на сумму и количество тестовых операций. По умолчанию максимальная сумма тестовых транзакций — 10 рублей. Максимум — 100 транзакций в сутки (учитываются операции за текущие сутки, время по МСК). Учитываются операции с суммой не более установленного лимита.
Для проведения операции с 3DS необходимо использовать строку unknown name
в имени держателя карты. Прохождение 3DS в режиме тестирования можно проверить только при вводе номера реальной карты.
Оплата через СБП в тестовом режиме
Для тестирования различных вариантов оплаты и ответов указывайте разные суммы платежа (поле amount
):
200
— операция пройдет успешно с задержкой. При первом запросе статуса платежа вы получите статус"WAITING"
, после второго запроса статуса платежа — статус"SUCCESS"
.- Для других сумм платеж пройдет неуспешно.
Платеж через форму QIWI
При подключении платежей через форму QIWI покупателю доступен только способ оплаты банковскими картами. Другие способы оплаты доступны по запросу:
- Платежные токены карт.
- QIWI Кошелек.
- Apple Pay/Google Pay.
Чтобы выполнить платеж через форму QIWI, выставите счет покупателю. Воспользуйтесь выставлением счета через API или перенаправьте покупателя на форму QIWI по прямой ссылке с параметрами счета.
Процесс платежа
Одношаговый платеж — все способы оплаты
Двухшаговый платеж — только карты 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
URL https://oplata.qiwi.com/create
Параметры
В URL указываются параметры счета.
Параметр | Описание | Тип | Обяз. |
---|---|---|---|
publicKey | Ключ идентификации мерчанта | String | + |
billId | Уникальный идентификатор счета в системе мерчанта. Он должен генерироваться на вашей стороне любым способом. Идентификатором может быть любая уникальная последовательность букв или цифр. Также разрешено использование символа подчеркивания (_ ) и дефиса (- ). Если не указан, то при каждом переходе по ссылке будет создаваться новый счет. |
URL-закодированная строка String(200) | - |
amount | Сумма покупки, округленная в меньшую сторону до 2 десятичных знаков (всегда в рублях) | Number(6.2) | - |
phone | Номер телефона покупателя (в международном формате) | URL-закодированная строка | - |
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"
}
Протокол приема платежей поддерживает выставление счетов с оплатой двухшаговым платежом с холдированием средств на карте покупателя, так и одношаговым платежом без авторизации покупателя.
-
Чтобы выставить счет для оплаты через холдирование средств на карте (двухшаговый платеж), передайте в запросе API Создание счета:
- ключ API;
- сумму счета (
amount
); - дату, до которой необходимо оплатить счет (
expirationDateTime
); - (опционально) другую информацию о счете — комментарий (
comment
), данные о покупателе (customer
,address
) и получателе платежа (receiverData
), дополнительные данные по операции (customFields
).
Вы также можете выставить счет для оплаты без дополнительной авторизации покупателя (одношаговый платеж). Для этого добавьте в запрос API дополнительный параметр
"flags":["SALE"]
. Если не передать этот параметр, то будет выполнено безусловное холдирование средств для оплаты счета. - Перенаправьте покупателя на Платежную форму по ссылке из параметра
payUrl
ответа. - Дождитесь завершения платежа: вам придет уведомление, или периодически отправляйте запрос 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
Для двухшагового сценария (платеж с холдированием средств) требуется выполнить подтверждение платежа. Возмещение формируется только после подтверждения.
Чтобы подтвердить платеж в двухшаговом сценарии:
- Получите идентификатор платежа
paymentId
:- из серверного уведомления. Вы получите его после успешного холдирования средств;
- из ответа на запрос API Получение списка платежей по счету.
- Отправьте запрос 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 кошельков без ввода реквизитов карты или номера кошелька. Метод оплаты платежным токеном по умолчанию отключен. Чтобы подключить его, обратитесь к вашему сопровождающему менеджеру.
О выпуске платежного токена читайте в разделе по ссылке.
Чтобы выставить счет для оплаты платежным токеном:
- Передайте в запросе API Создание счета следующие данные:
- ключ API;
- сумму счета (
amount
); - дату, до которой необходимо оплатить счет (
expirationDateTime
); - идентификатор покупателя, для которого был выпущен платежный токен, в параметре
customer.account
. Без этого параметра оплата платежным токеном невозможна. - (опционально) другую информацию о счете.
- Перенаправьте покупателя на Платежную форму по ссылке из параметра
payUrl
ответа. -
Если для покупателя был выпущен один или несколько платежных токенов, то на Платежной форме отобразится список его привязанных карт.
Для оплаты покупателю достаточно выбрать одну из своих привязанных карт. При этом не понадобится указывать карточные данные и проходить проверку 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
для отслеживания состояния формы. Возможные значения состояния:
INITIALIZED
— Форма загружена.PAYMENT_ATTEMPT
— Попытка платежа.PAYMENT_SUCCEEDED
— Платеж прошел успешно.PAYMENT_FAILED
— Платеж не прошел.INITIALIZATION_FAILED
— Ошибка загрузки формы.
Чтобы покупателю на Платежной форме были доступны методы Apple Pay/Google Pay при открытии ссылки в <iframe>
, рекомендуем использовать параметр allow
:
<iframe allow="payment" src="<ссылка payUrl> ..." />
Настройка Платежной формы
Внешний вид Платежной формы можно настроить в соответствии с вашим стилем, включая лого, фон и цвет кнопок. Для этого обратитесь в Службу поддержки payin@qiwi.com и предоставьте следующие данные:
- уникальный псевдоним стиля, привязанный к идентификатору
siteId
(цифры, латинские буквы и символ дефиса-
); - название мерчанта, которое будет отображаться на форме;
- краткое описание деятельности (не более 120 символов);
- лого в формате PNG или SVG и размера 310x36 или пропорционально больше;
- цвет фона и цвет кнопок в HEX-формате.
Необязательные данные для настройки:
- картинка для фона в формате PNG или SVG и размера 382x560 или пропорционально больше;
- варианты предвыбранных сумм платежа (не более трех);
- контактный e-mail для отображения на странице;
- URL страницы успешного платежа;
- номер счетчика Яндекс.Метрики;
- ссылка на оферту вашего сервиса.
Пример передачи параметра стиля при выставлении счета
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"
.
Название псевдонима стиля регистрозависимое.
Платеж через форму мерчанта
При подключении платежей через собственную платежную форму по умолчанию сразу доступен способ оплаты Банковские карты. Другие способы оплаты доступны по запросу:
- Платежные токены карт и QIWI Кошелька.
- Apple Pay.
- Google Pay.
- Yandex Pay.
- Система Быстрых Платежей (СБП).
Процесс платежа
ввод платежных данных 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 Платеж:
- ключ 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;
- сумму платежа;
- метод платежа
CARD
и карточные данные покупателя; - другие данные для создания платежа.
В двухшаговом платеже возмещение формируется только после подтверждения платежа.
Для платежа без авторизации (одношаговый платеж) укажите в запросе 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
с полями:
acsUrl
— URL сервера аутентификации 3-D Secure, для перенаправления на страницу подтверждения от эмитента;pareq
— зашифрованный запрос на аутентификацию 3-D Secure.
Чтобы получить результат проверки (PaReS
), сделайте POST-запрос на URL сервера аутентификации 3-D Secure с параметрами:
TermUrl
— URL перенаправления покупателя после успешной аутентификации 3-D Secure;MD
— уникальный идентификатор транзакции;PaReq
— значение параметраpareq
из ответа на платежный запрос.
Чтобы сохранять обратную совместимость, использование протокола 3-D Secure 1.0 или 3-D Secure 2.0 не влияет на вашу интеграцию с API.
Информация о покупателе передаётся в платежную систему карты. Банк-эмитент либо предоставляет разрешение на списание средств без аутентификации (frictionless flow), либо принимает решение о необходимости аутентификации с помощью одноразового пароля (challenge flow). После прохождения проверки покупатель перенаправляется по адресу TermUrl
с зашифрованным результатом проверки в параметре PaRes
.
Чтобы завершить аутентификацию покупателя, передайте в запросе API Завершение аутентификации клиента:
- уникальный ID мерчанта;
- номер платежа (параметр
paymentId
) из ответа на запрос платежа; - результат 3-D Secure (значение параметра
PaRes
).
Подтверждение платежа
Пример уведомления
{
"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
Это действие требуется только для двухшагового платежа с холдированием.
Чтобы подтвердить платеж:
- Получите
paymentId
платежа:- Из серверного уведомления после успешного холдирования средств.
- Из ответа на запрос Статус платежа.
- Отправьте запрос API Подтверждение платежа с полученным
paymentId
.
Платежный токен
Использование платежного токена в запросе платежа
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
, - идентификатор покупателя, для которого был выпущен платежный токен, в параметре
customer.account
.
Параметр | Тип | Описание |
---|---|---|
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 Developer Program.
- Использование HTTPS на странице с Apple Pay, поддержка TLS 1.2, действительный SSL сертификат.
- Соблюдение правил Apple по использованию Apple Pay на сайтах.
- Использование фреймворка Apple Pay JS API.
Подробнее об интеграции см. на сайте Apple.
Процесс платежа
Процесс выполнения платежа Apple Pay в API:
- Создание платежной сессии Apple Pay.
- Валидация ТСП в Apple Pay.
- Получение зашифрованных платежных данных от Apple Pay.
- Расшифровка платежных данных (опционально).
- Отправка запроса на списание средств в QIWI:
- с зашифрованными данными,
- с расшифрованными данными (Если платежный токен Apple расшифрован на стороне ТСП).
Как отправлять платеж с зашифрованными данными
Пример 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
с параметрами:
type
— тип платежного метода, толькоAPPLE_PAY_TOKEN
.paymentData
— платежный токен (обязательное поле). Данные вpaymentData
берутся из поляpaymentData
платежного токена (см. описание JSON-структуры токена):version
— информация о версии платежного токена. Возможные значения:EC_v1
,RSA_v1
(обязательное поле);data
— зашифрованные платежные данные, Base64-строка (обязательное поле);header
— дополнительная информация, используемая для дешифровки и валидации платежа (обязательное поле):applicationData
— SHA-256-хэш поляapplicationData
исходного платежного токена, HEX-строка (необязательное поле);ephemeralPublicKey
— массив байтов эфемерного публичного ключа, закодированный в виде Base64-строки (используется только когдаversion=EC_v1
);wrappedKey
— симметричный ключ на основе публичного RSA-ключа, закодированный в виде Base64-строки (используется только когдаversion=RSA_v1
);publicKeyHash
— SHA-256-хэш от массива байт публичного ключа сертификата мерчанта, Base64-строка (обязательное поле);transactionId
— идентификатор транзакции, генерируемый на устройстве, где выполняется платёж. HEX-идентификатор, представленный в виде строки (обязательное поле);
signature
— подпись, вычисленная по платежному токену, Base64-строка (обязательное поле).
Как отправлять платеж с расшифрованными данными
Пример отправки расшифрованных платежных данных 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
:
type
— всегдаCARD
;- данные из расшифрованного платежного токена Apple:
- PAN в поле
"pan"
; - срок действия в формате
MM/YY
в поле"expiryDate"
;
- PAN в поле
- объект
external3dSec
с элементами:type
— всегдаAPPLE_PAY
;onlinePaymentCryptogram
— содержимое поляonlinePaymentCryptogram
платежного токена Apple (Base64-закодированная строка);eciIndicator
— ECI индикатор. Необходимо передавать, если полеeciIndicator
получено в платежном токене Apple. В противном случае параметр не передавать.
Google Pay
В способе оплаты Google Pay™ поддерживаются платежи с карт Visa и MasterCard.
Для включения способа оплаты Google Pay™ обратитесь к вашему сопровождающему менеджеру.
Процесс интеграции Google Pay™ на платежную страницу мерчанта:
- Выполните требования Google Pay™ WEB для приема шифрованных платежных данных. В том числе, проверьте контрольный список интеграции Google Pay™ для веб-сайтов и правила фирменного оформления Google Pay™ для веб-сайтов.
- Для интеграции необходимо выполнить требования к отправке данных:
- Подайте заявку на доступ к рабочей версии. В заявке на доступ укажите следующие данные:
- Tokenization Method — Gateway;
- Payment Processor or Gateway —
qiwi
; - Merchant Name — выдается технической поддержкой компании QIWI.
- 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
:
paymentMethod.type=GOOGLE_PAY_TOKEN
-
paymentMethod.paymentToken
, заполненный по следующему алгоритму:b64_encode_bytes_to_string (compress_bytes_with_zlib (to_bytes (JSON)))
Шаг 1 (
to_bytes
) — Объект JSON конвертируется в массив байтов в соответствии с кодировкой UTF-8. Структура объекта JSON описана в руководстве по криптографии платежных данных Google.Шаг 2 (
compress_bytes_with_zlib
) — Байты, полученные на предыдущем шаге, сжимаются с помощью библиотеки zlib. При выполнении сжатия необходимо следовать спецификации RFC1950 и обеспечить запись zlib header в начало потока со сжатыми данными.Шаг 3 (
b64_encode_bytes_to_string
) — Байты, полученные на предыдущем шаге, кодируются в формат base64.
Полученная в результате закодированная строка является значением поля 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
токена:
-
CRYPTOGRAM_3DS
. Без дополнительной аутентификации покупателя.Для отправки платежных данных в QIWI передайте в запросе API Платеж объект
paymentMethod
с параметрами:type
— всегдаCARD
;- данные из расшифрованного платежного токена Google:
- PAN в поле
"pan"
; - срок действия в формате
MM/YY
в поле"expiryDate"
; - объект
external3dSec
с элементами:type
— всегдаGOOGLE_PAY
;cryptogram
— содержимое поляcryptogram
платежного токена Google(Base64-закодированная строка);eciIndicator
— ECI индикатор. Необходимо передавать, если полеeciIndicator
получено в платежном токене Google. В противном случае параметр не передавать.
- PAN в поле
-
PAN_ONLY
. С дополнительной аутентификацией покупателя (3-D Secure).Для отправки платежных данных в QIWI передайте в запросе API Платеж объект
paymentMethod
с параметрами:type
— всегдаCARD
;- данные из расшифрованного платежного токена Google:
- PAN в поле
"pan"
; - срок действия в формате
MM/YY
в поле"expiryDate"
; - объект
external3dSec
с полемtype
, всегда равнымGOOGLE_PAY
.
- PAN в поле
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:
-
CLOUD_TOKEN
. Без дополнительной аутентификации покупателя.Для отправки платежных данных в QIWI передайте в запросе API Платеж объект
paymentMethod
с параметрами:type
— всегдаCARD
;- данные из расшифрованного платежного токена Yandex Pay:
- PAN в поле
"pan"
; - срок действия в формате
MM/YY
в поле"expiryDate"
; - объект
external3dSec
с элементами:type
— всегдаYANDEX_PAY
;cryptogram
— содержимое поляcryptogram
платежного токена Yandex Pay(Base64-закодированная строка);eciIndicator
— ECI индикатор. Необходимо передавать, если полеeciIndicator
получено в платежном токене Yandex Pay. В противном случае параметр не передавать.
- PAN в поле
-
PAN_ONLY
. С дополнительной аутентификацией покупателя (3-D Secure).Для отправки платежных данных в QIWI передайте в запросе API Платеж объект
paymentMethod
с параметрами:type
— всегдаCARD
;- данные из расшифрованного платежного токена Yandex Pay:
- PAN в поле
"pan"
; - срок действия в формате
MM/YY
в поле"expiryDate"
; - объект
external3dSec
с полемtype
, всегда равнымYANDEX_PAY
.
- PAN в поле
Оплата через СБП
Протокол приема платежей поддерживает списание средств с покупателя через Систему быстрых платежей (СБП). Через СБП можно выполнять платежи в пользу юридических лиц, в том числе с использованием 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-кода:- Тип QR-кода в параметре
qrCode.type
:DYNAMIC
— динамический QR-код, индивидуальный для каждой оплаты.STATIC
— статический QR-код, формируется один раз, удобно для товаров с фиксированной ценой.
- Срок действия кода в минутах в параметре
qrCode.ttl
. Указывается только дляqrCode.type=DYNAMIC
. По умолчанию динамический QR-код активен в течение 72 часов, по истечении срока деактивируется. - Тип и размер изображения QR-кода в блоке
qrCode.image
.
- Тип QR-кода в параметре
- Сумму платежа.
- Чтобы добавить описание платежа, используйте поле запроса
paymentPurpose
. Если это поле не заполнено, в приложении банка покупателя отобразится название вашего магазина.
В ответе на запрос в объекте qrCode
содержатся данные QR-кода:
image.content
— base64-encoded QR-код. После расшифровки вы получите изображение для отображения покупателю.payload
— URL-based 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-кода СБП. В запросе укажите:
- Объект
qrCode
с характеристиками запрашиваемого QR-кода:- Тип QR-кода в параметре
qrCode.type
—TOKEN
. - Тип и размер изображения QR-кода в блоке
qrCode.image
.
- Тип QR-кода в параметре
- Сумму платежа.
- Параметр
tokenizationAccount
— уникальный идентификатор Покупателя в системе ТСП. - Параметр
"flags":["CREATE_TOKEN"]
. - Описание токена в параметре
tokenizationPurpose
.
Необходимо использовать разные параметры tokenizationAccount
для разных покупателей, чтобы гарантировать безопасность привязанных карточных данных покупателей.
Вы получите информацию о платежном токене СБП в объекте token
ответа.
Оплата токеном через СБП
Пример тела запроса
{
"tokenizationAccount": "customer123",
"token": "c5ba4a05-21c9-4a36-af7a-b709b4caa4d6"
}
Чтобы оплатить покупку платежным токеном СБП, передайте в запросе API Платеж токеном СБП:
- платежный токен в параметре
token
, - идентификатор покупателя, для которого был выпущен платежный токен, в параметре
tokenizationAccount
.
Серверные уведомления
Пример уведомления
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:
PAYMENT
— отправляются при совершении операций платежа;CAPTURE
— отправляются при совершении операций подтверждения платежа;REFUND
— отправляются при совершении операций возврата платежа;CHECK_CARD
— отправляются при совершении операций проверки карты.
Адрес вашего сервера для обработки уведомлений указывается в Личном кабинете в разделе Настройки.
Чтобы указать URL сервера обработки уведомлений для отдельной операции, используйте:
- параметр
callbackUrl
— в запросах API Платеж, Подтверждение платежа, Операция возврата; - параметр
customFields.invoice_callback_url
— в запросе API Создание счета.
URL для уведомлений должен начинаться с https, так как уведомления отправляются по протоколу HTTPS на порт 443. URL должен быть доступен из Интернета.
Сертификат сайта должен быть выпущен доверенным центром сертификации (например Comodo, Verisign, Thawte и т.п.).
Для дополнительной уверенности следует принимать уведомления о платежах только с указанных ниже IP-адресов компании QIWI:
- 79.142.16.0/20
- 195.189.100.0/22
- 91.232.230.0/23
- 91.213.51.0/24
Уведомление считается успешно доставленным, если ваш сервер ответил HTTP кодом состояния 200 OK
.
До этого момента система будет пытаться доставить уведомление через увеличивающиеся интервалы времени в течение суток с момента операции.
Авторизация уведомлений
В уведомлении присутствует цифровая подпись запроса, которую необходимо проверять на вашей стороне для исключения возможности подделки уведомления.
Цифровая подпись уведомления помещается в HTTP-заголовок Signature
.
Для проверки подписи используется механизм проверки целостности HMAC с хэш-функцией SHA256 и ключом, указанным в разделе Настройки Личного кабинета мерчанта.
Алгоритм проверки подписи:
-
Объединить значения определенных параметров в одну строку с разделителем "|". Например:
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
- тип
-
Вычислить HMAC-хэш c алгоритмом хэширования SHA256:
hash = HMAС(SHA256, secret, parameters)
Где:
secret
— ключ хеширования (UTF-8). Совпадает с ключом серверных уведомлений, указанным в разделе Настройки Личного кабинета мерчанта.parameters
— строка из п.1 (UTF-8).
-
Сравнить значение подписи из HTTP-заголовка
Signature
уведомления с результатом п.2.
Частота отправки уведомлений
Сервис отправки уведомлений распределяет неуспешные уведомления по очередям:
- 1 попытка с отложенным временем 5 секунд
- 1 попытка с отложенным временем 1 минута
- 3 попытки с отложенным временем по 5 минут
Время повторной отправки может сдвигаться в бОльшую сторону.
Формат уведомления PAYMENT
HEADERS
- Signature: XXX
- Accept: application/json
- Content-type: application/json
Поле | Описание | Тип | В каких случаях используется |
---|---|---|---|
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 | Всегда |
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
HEADERS
- Signature: XXX
- Accept: application/json
- Content-type: application/json
Поле | Описание | Тип |
---|---|---|
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 |
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
HEADERS
- Signature: XXX
- Accept: application/json
- Content-type: application/json
Поле | Описание | Тип | В каких случаях используется |
---|---|---|---|
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 | Всегда |
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
HEADERS
- Signature: XXX
- Accept: application/json
- Content-type: application/json
Поле | Описание | Тип |
---|---|---|
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 |
Возвраты и отмены
Операции возврата и отмены доступны не для всех способов платежей:
- Возвраты доступны только для успешно завершенных операций платежа.
- Отмена операции возможна только при двухшаговом сценарии платежа и только для операций, по которым ещё не было подтверждения (CAPTURE).
При возврате платежа комиссия 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:
- В тело уведомления с типом
PAYMENT
добавляется JSON-массивpaymentSplits
, используемый для передачи данных о платежах поставщиков. Формат массива см. выше. - В тело уведомления с типом
REFUND
добавляется JSON-массивrefundSplits
, используемый для передачи данных о возвратах поставщикам. Формат массива см. выше.
Платежный токен
В Протоколе приема платежей поддерживается генерация платежных токенов карт и 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": ".."
}
Для выпуска платежного токена карты вы можете использовать два способа:
- Без платежа (предпочтительный способ). Воспользуйтесь запросом Проверка карты или Создание счета с проверкой карты. В запросе укажите:
- параметр
account
— уникальный идентификатор Покупателя в системе ТСП:- либо в блоке
tokenizationData
— в случае запроса Проверка карты; - либо в блоке
customer
— в случае запроса Создание счета.
- либо в блоке
- параметр
"flags":["CHECK_CARD", "BIND_PAYMENT_TOKEN"]
— в случае запроса Создание счета.
Необходимо использовать разные параметры
account
для разных покупателей, чтобы гарантировать безопасность карточных данных покупателей.Вы получите информацию о платежном токене карты после успешного завершения проверки:
- В блоке
createdToken
ответа на финальный запрос. - В уведомлении CHECK_CARD.
Также можно запросить текущий статус проверки — в ответе вернется блок
createdToken
с информацией о выпущенном платежном токене.Подробнее см. в разделе Проверка карты покупателя.
- параметр
- В процессе проведения платежа. Воспользуйтесь запросом Платеж или Создание счета. В запросе укажите дополнительные параметры:
"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:
-
Запрос инициации выпуска платежного токена QIWI Кошелька.
Отправьте POST-запрос на URL:
/payin-tokenization-api/v1/sites/{siteId}/token-requests
где
{siteId}
— идентификаторsiteId
мерчанта.В JSON-теле запроса укажите параметры:
requestId
— уникальный идентификатор запроса (от 1 до 36 символов). Уникальность означает, что идентификатор должен отличаться от идентификаторов всех ранее созданных запросов ТСП на выпуск платежного токена QIWI кошелька в рамках одногоsiteId
.phone
— номер QIWI кошелька покупателя.accountId
— уникальный идентификатор покупателя в системе ТСП.
Указывайте разные параметры
accountId
для разных покупателей, чтобы гарантировать безопасность платежных данных покупателей. -
После этого на телефон покупателя придет SMS с одноразовым кодом. Укажите его в запросе завершения выпуска платежного токена QIWI Кошелька.
Отправьте POST-запрос на URL:
/payin-tokenization-api/v1/sites/{siteId}/token-requests/complete
где
{siteId}
— идентификаторsiteId
мерчанта.В JSON-теле запроса укажите параметры:
requestId
— идентификатор из начального запроса инициации выпуска платежного токена.smsCode
— код из SMS, отправленный покупателю.
В ответе содержатся данные платежного токене:
token.value
— строка платежного токена;token.expiredDate
— срок действия платежного токена, в форматеYYYY-MM-DDThh:mm:ss+DMZ
.
Удаление платежного токена
Удаление платежного токена
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-теле запроса укажите параметры:
customerAccountId
— уникальный идентификатор покупателя в вашей системе, привязанный к платежному токену.token
— платежный токен.
Успешный ответ означает, что платежный токен для указанного покупателя больше не действует.
Этот метод действует как для платежного токена карты, так и для платежного токена 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"
}
- Отправьте запрос создания счета с дополнительным параметром
"flags":["CHECK_CARD", "BIND_PAYMENT_TOKEN"]
. Для генерации платежного токена в запросе должен быть указан параметрcustomer.account
— уникальный идентификатор покупателя в системе ТСП. Не указывайте сумму счета. Извлеките из ответа параметрbillId
— он понадобится в п.4. - Перенаправьте покупателя на Платежную форму — ссылка на нее находится в параметре
payUrl
ответа. -
На Платежной форме покупатель указывает реквизиты карты и отправляет их на проверку. На форме выполняется аутентификация покупателя (3-D Secure).
-
Дождитесь завершения проверки карты: вам придет уведомление 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"
}
}
- Отправьте запрос API "Проверка карты". В запросе укажите уникальный в рамках вашего сайта идентификатор проверки (
requestUid
). Для генерации платежного токена в запросе должен быть указан параметрtokenizationData.account
— уникальный идентификатор покупателя в системе ТСП. - В ответе информация о доступности карты для списаний содержится в атрибуте
isValidCard
(true
— номер карты валиден). Данные платежного токена возвращаются в объектеcreatedToken
.
Чтобы убедиться, что номер карты ввел именно держатель карты, вы можете использовать дополнительную аутентификацию покупателя 3-D Secure в сервисе проверки карты. Включение/отключение 3DS производится на стороне QIWI через поддержку. Если 3DS включен, то в ответе на запрос проверки карты вы получите объект "requirements"
с ACS URL для перенаправления покупателя (в поле status
будет значение "WAITING_3DS"
).
Сценарий проверки аналогичен операции покупки:
- Перенаправьте покупателя на страницу аутентификации.
- Завершите 3-D Secure запросом "Завершение 3DS при проверке карты". В запросе укажите тот же идентификатор проверки, что и в исходном запросе проверки карты.
- Если проверка 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 описывают причину отклонения операции и передаются:
- в ответах на запросы — в поле
status.reason
; - в уведомлениях — в поле
status.reasonCode
.
Ошибка 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 выставления счета и платежа.
Для активации сервиса формирования фискального чека сообщите вашему сопровождающему менеджеру номер ИНН, с которым ваша организация зарегистрирована в сервисе по аренде онлайн-касс.
Если используется Атол, то дополнительно предоставьте сведения:
- email ТСП для печати в чеке;
- полное название организации;
- реквизиты ОФД (название, ИНН, url);
- login и password для генерации токена;
- код группы.
Описание объекта 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 – иной предмет расчета. О предмете расчета, не относящемуся к выше перечисленным предметам расчета. |