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

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

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

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

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

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

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

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

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

Статус выплаты

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

some comment for payout operation

Incorrect payout amount

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

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

Оплата со счета мобильного телефона

Оплата покупок со счета мобильного телефона происходит без ввода данных карты. Сразу после инициирования платежа покупатель получает SMS-сообщение от своего мобильного оператора с информацией о платеже и подтверждает или отклоняет оплату ответным SMS.

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

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

При отправке платежа укажите в блоке paymentMethod в запросе API Платеж параметры:

Тестирование

См. описание тестового режима для выплат.

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

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

Статус счета

Пример запроса статуса счета

Детская футбольная школа ТигрыДетская футбольная школа ТигрыДетская футбольная школа Тигры

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

API Протокола приема платежей основано на принципах REST-архитектуры. Данные и методы считаются ресурсами, которые доступны через вызов универсальных идентификаторов ресурсов (URI).

Методы API вызываются через HTTP-запросы. Постоянная часть URL-адреса для вызова методов API:

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

Необходимо указывать Accept: application/json в заголовках запроса — API всегда возвращает ответ в формате JSON.

Методы API обеспечивают логическую идемпотентность, т. е. многократный вызов метода эквивалентен однократному. Однако ответ сервера может меняться (например, состояние счёта может измениться между запросами).

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

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

Двухшаговый платеж

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

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

Одношаговый платеж

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

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

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

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

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

Чтобы покупатель смог оплатить платежным токеном:

Для списания средств по платежному токену без участия Покупателя воспользуйтесь методом API Платеж. См. подробнее описание использования платежного токена на Платежной форме мерчанта.
## Типы операций
Тип операции | Описание
--- | ---
CAPTURE | Операция подтверждения.
## Статус платежа
Пример запроса статуса платежа
Exchange token error. Token disabled, please create new one
## PayoutReceiverDataRequest
### Информация о получателе
Доступные типы: CARD и SBP.
#### Тип метода выплаты CARD:
Поле | Тип или константа | Описание
--- | --- | ---
type | required CARD | Тип метода выплаты
pan | required string(19) | Номер банковской карты
receiverFirstName | string(64) | Имя получателя
receiverLastName | string(64) | Фамилия получателя
#### Тип метода выплаты SBP:
Поле | Тип или константа | Описание
--- | --- | ---
type | required SBP | Тип метода выплаты
phone | required number(11..13) | Номер телефона
flags | array of strings | Дополнительные флаги для операции. Поддерживается значение INIT, которое включает двухшаговый сценарий выплаты на СБП. В случае передачи флага нужно будет дополнительно отправить запрос подтверждения выплаты
## Интеграция с Платёжной формой мерчанта
Чтобы отправить платёж со сплитованием, передайте в запросе API Платеж JSON-массив paymentSplits с данными поставщиков.
### Пример платежа со сплитованием
### Пример ответа на платеж со сплитованием
Товар из корзины
#### Формат массива paymentSplits в запросе:
Название | Тип | Описание
--- | --- | ---
paymentSplits | Array | Массив данных о поставщиках
type | String | Тип передаваемых данных. Доступные значения: MERCHANT_DETAILS (данные поставщика)
siteUid | String | ID поставщика
splitAmount | Object | Возмещение поставщику
value | Number | Сумма возмещения, округленная в меньшую сторону до 2 десятичных знаков
currency | String(3) | Буквенный код валюты возмещения по ISO. Доступен только RUB
orderId | String | Номер заказа (необязательный)
#### В объекте paymentSplits ответа содержатся данные о принятых платежах и комиссиях:
Поле ответа | Тип | Описание
--- | --- | ---
paymentSplits | Array | Массив с данными о принятых платежах
type | String | Тип передаваемых данных. Всегда возвращается строка MERCHANT_DETAILS
splitAmount | Object | Данные о возмещении поставщику
value | String | Сумма возмещения
splitCommissions | Object | Данные о комиссии (необязательный)
merchantCms | Object | Данные о комиссии с поставщика
value | String | Сумма комиссии
currency | String(3) | Буквенный код валюты комиссии по ISO
## Частота отправки уведомлений
Сервис отправки уведомлений распределяет неуспешные уведомления по очередям:
Время повторной отправки может быть увеличено.
## Завершение аутентификации при проверке карты
Пример завершения аутентификации при проверке карты
## Возвраты по проведенным платежам
Возврат по платежу возможен только для успешно проведенного платежа. Возврат может быть как частичным, так и полным. В первом случае возвращается вся сумма принятого платежа. Во втором — только часть от суммы платежа. Перед возвратом платежа проверьте, что платеж успешно завершен и находится в статусе COMPLETED.
Чтобы выполнить возврат по карточному платежу, используйте метод API Операция возврата.
## Формат уведомления TOKEN

Уведомление об успешной привязке токена СБП

Уведомление о неуспешной привязке токена СБП

Поле Описание Тип В каких случаях используется

• token: Описание токена Object Всегда

• token.status: Информация о статусе операции Object Всегда

• token.status.value: Строковое значение статуса String Всегда

• token.status.changedDateTime: Дата обновления статуса URL-закодированная строкаГГГГ-ММ-ДДTчч:мм:ссZ Всегда

• token.status.rejectReason: Причина отклонения String В случае отклонения операции

• token.merchantSiteUid: ID поставщика String Всегда

• token.account: Идентификатор покупателя, указанный при выпуске платежного токена String Всегда

• token.value: Платежный токен String В случае успешной операции

• token.expiredDate: Дата окончания срока действия платежного токена. Формат даты соответствует стандарту ISO-8601: ГГГГ-ММ-ДДTчч:мм:сс±чч:мм String В случае успешной операции

• token.tokenizationSource: Информация об источнике токенизации Object Всегда

• token.tokenizationSource.type: Тип источника токенизации String Всегда

• token.tokenizationSource.uid: ID источника токенизации String Всегда

• token.bankMemberId: Идентификатор банка покупателя String В случае успешной операции

• type: Тип уведомления — только TOKEN String Всегда

• version: Версия уведомлений String Всегда

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

Формат массива refundSplits в запросе:

• refundSplits: Array Массив данных о возвратах

• splitAmount: Object Информация об отменённом возмещении поставщику

  • value: Number Сумма отменённого возмещения, округленная в меньшую сторону до 2 десятичных знаков

  • currency: String(3) Буквенный код валюты отменённого возмещения по ISO. Доступен только RUB

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

• value: String Сумма отменённого возмещения

• splitCommissions: Object Информация о комиссии (необязательный)

• merchantCms: Object Информация о комиссии с поставщика

Аутентификация по цифровой подписи

## Аутентификация по цифровой подписи
Аутентификация по цифровой подписи применяется только для создания операций типа Выплата через API.
Для аутентификации по цифровой подписи мерчант должен создать пару RSA-ключей, например, с помощью утилиты OpenSSL. Закрытый ключ должен быть размером 2048 бит в PEM-формате. Мерчант должен передать в QIWI закодированный в Base64 открытый ключ, соответствующий закрытому ключу.
## Как создать ключи
Алгоритм с примерами на языке Bash.
## Формат уведомления CAPTURE
Пример тела уведомления CAPTURE.
### CAPTURE Описание операции подтверждения
- capture.type: Тип операции — только CAPTURE String(200)
- capture.paymentId: Идентификатор платежа в системе ТСП String(200)
- capture.captureId: Идентификатор подтверждения в системе ТСП String(200)
- capture.createdDateTime: Дата создания операции URL-закодированная строкаГГГГ-ММ-ДДTчч:мм:ссZ
### Информация о сумме операции
- capture.amount.value: Сумма операции, округленная до двух десятичных знаков в меньшую сторону Number(6.2)
- capture.amount.currency: Идентификатор валюты операции (Alpha-3 ISO 4217 код) String(3)
- capture.billId: ID счета, соответствующего операции String(200)
### Информация о статусе операции
- capture.status.value: Строковое значение статуса String
- capture.status.changedDateTime: Дата обновления статуса URL-закодированная строкаГГГГ-ММ-ДДTчч:мм:ссZ
- capture.status.reasonCode: Код причины отклонения String(200)
- capture.status.reasonMessage: Описание причины отклонения String(200)
- capture.status.errorCode: Код ошибки Number
### Информация о средстве платежа
- capture.paymentMethod.type: Тип метода оплаты String
- capture.paymentMethod.maskedPan: Маскированный PAN карты String
- capture.paymentMethod.rrn: RRN платежа (по ISO 8583) Number
- capture.paymentMethod.authCode: Auth-code платежа Number
### Информация о покупателе
- capture.customer.phone: Номер телефона покупателя String
- capture.customer.email: E-mail покупателя String
- capture.customer.account: Идентификатор покупателя в системе ТСП String
- capture.customer.ip: IP адрес покупателя String
- capture.customer.country: Страна адреса покупателя String
### Поля с произвольной информацией
- capture.customFields.cf1: Поле с произвольной информацией, дополняющей данные по операции String(256)
- capture.customFields.cf2: Поле с произвольной информацией, дополняющей данные по операции String(256)
- capture.customFields.cf3: Поле с произвольной информацией, дополняющей данные по операции String(256)
- capture.customFields.cf4: Поле с произвольной информацией, дополняющей данные по операции String(256)
- capture.customFields.cf5: Поле с произвольной информацией, дополняющей данные по операции String(256)
### Дополнительные команды
- capture.flags: Дополнительные команды, переданные в API Array(Strings). Возможные элементы: SALE, REVERSAL
### Сведения о сумме расчёта с мерчантом
- capture.settlementAmount: Если валюта платежа и расчёта с мерчантом различаются

capture.settlementAmount.value Сумма расчёта с мерчантом Number(6.2) Если валюта платежа и расчёта с мерчантом различаются

capture.settlementAmount.currency Идентификатор валюты расчёта с мерчантом (Alpha-3 ISO 4217 код) String(3) Если валюта платежа и расчёта с мерчантом различаются

type Тип уведомления — только CAPTURE String

Тестирование проведения операций

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

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

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

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

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

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

Выплата

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

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

О выпуске платежного токена см. подробнее в этом разделе.

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

Если карта, для которой выпущен платежный токен, была уже ранее сохранена (токенизирована) на вашей стороне, должны быть добавлены дополнительные параметры в объекте paymentMethod:

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

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

checkPaymentMethod Описание результата проверки карты Object

checkPaymentMethod.checkOperationDate Дата проверки карты URL-закодированная строкаГГГГ-ММ-ДДTчч:мм:ссZ

checkPaymentMethod.requestUid Идентификатор операции проверки карты String

checkPaymentMethod.status Статус проверки карты String

checkPaymentMethod.isValidCard Признак доступности карты для платежей Bool

checkPaymentMethod.threeDsStatus Информация о статусе дополнительной аутентификации при проверке карты. Возможные значения: PASSED (3-D Secure пройден), NOT_PASSED (3-D Secure не пройден), WITHOUT (3-D Secure не требовалось) String

checkPaymentMethod.paymentMethod Информация о средстве платежа Object

checkPaymentMethod.paymentMethod.type Тип метода оплаты String

checkPaymentMethod.paymentMethod.maskedPan Маскированный PAN карты String

checkPaymentMethod.paymentMethod.cardExpireDate Срок действия карты String

checkPaymentMethod.paymentMethod.cardHolder Имя держателя карты String

checkPaymentMethod.cardInfo Информация о карте Object

checkPaymentMethod.cardInfo.issuingCountry Код страны эмитента String(3)

checkPaymentMethod.cardInfo.issuingBank Банк-эмитент String

checkPaymentMethod.cardInfo.paymentSystem Тип платежной системы String

checkPaymentMethod.cardInfo.fundingSource Тип карты String

checkPaymentMethod.cardInfo.paymentSystemProduct Категория карты String

checkPaymentMethod.createdToken Объект с информацией о платежном токене, выпущенном вместе с проверкой карты Object

checkPaymentMethod.createdToken.token Строка платежного токена String

checkPaymentMethod.createdToken.name Маскированный PAN карты, для которой выпущен платежный токен String

checkPaymentMethod.createdToken.expiredDate Дата окончания срока действия платежного токена. Формат даты соответствует стандарту ISO-8601:ГГГГ-ММ-ДДTчч:мм:сс±чч:мм String

checkPaymentMethod.createdToken.account Идентификатор покупателя, указанный при выпуске платежного токена String

checkPaymentMethod.merchantSiteUid Строковый идентификатор сайта ТСП в QIWI Кассе String

type Тип уведомления — только CHECK_CARD String

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

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

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

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

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

"Flower for my girlfriend"

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

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

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

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

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

После перехода платежа в финальный статус вы получите уведомление с указанным в исходном запросе идентификатором выпуска QR-кода в поле qrCodeUid. Актуальный статус платежа по идентификатору платежа paymentId из уведомления можно получить через API.

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

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

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

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

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

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

Тестирование оплаты СБП

См. информацию в этом разделе.

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

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

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

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

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

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

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

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

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

Если карта, указанная клиентом, была ранее сохранена (токенизирована) на вашей стороне, должны быть добавлены дополнительные параметры в объекте paymentMethod:

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

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

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

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

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

Если требуется 3-D Secure аутентификация покупателя, в ответе на запрос платежа добавляется объект requirements.threeDS с полями:

Для дополнительной проверки покупателя у эмитента выполните POST-запрос на URL сервера аутентификации 3-D Secure с параметрами:

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

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

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

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

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

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

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

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

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

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

Некоторые ошибки API сопровождаются детализацией ошибки и рекомендованными действиями, полученными от платежной системы в поле status.psErrorCode.

Ошибка API Описание

INVALID_STATE Некорректный статус транзакции

INVALID_AMOUNT Некорректная сумма

INVALID_RECEIVER_DATA Ошибка при передаче данных о получателе

DECLINED_BY_MPI Отклонено MPI

DECLINED_BY_FRAUD Отклонено fraud-мониторингом

REATTEMPT_NOT_PERMITTED Повторный запрос авторизации запрещен на основании правил Платежной системы

REATTEMPT_NOT_PERMITTED_BY_PS Операция отклонена платежной системой. Детализация ошибки содержится в поле status.psErrorCode. По данной карте повторная операция невозможна

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 Ошибка при проведении платежа

PAYMENT_EXPIRED_3DS Не пройдена 3DS-аутентификация

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 Кошельке

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

Ошибки операции выплаты

GATEWAY_TECHNICAL_ERROR Неизвестная техническая ошибка, попробуйте повторить запрос еще раз

MERCHANT_SETTINGS_ERROR Ошибка в настройках мерчанта, обратитесь в Службу поддержки

DECLINED_BY_PAYOUT_GATEWAY Отклонено выплатным шлюзом

ChequeData

Информация о фискальном чеке по операции.

Имя Описание Тип

id Идентификатор чека String

url Информация о чеке (URL-ссылка) String