Пополнение электронных кошельков с телефона

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

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

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

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

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

Чтобы инициировать платеж с предварительным холдированием средств на карте (двухшаговый платеж), передайте в запросе 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 Завершение аутентификации клиента.

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

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

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

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

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

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

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

Ссылка на форму с передачей суммы платежа

Ссылка на форму без указания суммы платежа (сумму заполняет покупатель)

billId Уникальный идентификатор счета в системе мерчанта. Генерируется на вашей стороне любым способом как уникальная последовательность букв, цифр и символов \_, -. Если не указан, то при каждом переходе по ссылке создается новый счет. URL-закодированная строка String(200)
amount Сумма покупки, округленная в меньшую сторону до 2 десятичных знаков (всегда в рублях) Number(6.2)
currency Код валюты покупки. Возможные значения: RUB, EUR, USD. По умолчанию RUB String(3)
phone Номер телефона покупателя (в международном формате) URL-закодированная строка
email E-mail покупателя URL-закодированная строка
successUrl URL для возврата на сайт мерчанта в случае успешной оплаты. Ссылку необходимо указывать в кодировке UTF-8\. URL-закодированная строка
paymentMethod Платежный метод, предлагаемый покупателю по умолчанию на платежной форме. Возможные значения: CARD, SBP, QIWI\_WALLET. Если указанный метод недоступен мерчанту, отображается другой доступный. По умолчанию — CARD. String
readonly\_extras Список дополнительных полей, которые должны быть недоступны для изменения покупателем на платежной форме Строка, разделитель имен полей ,. Пример: cf1,cf3

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

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

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

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

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

Flower for my girlfriend

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

Exchange token error. Token disabled, please create new one

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

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

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

## Выставление счета с оплатой через холдирование (двухшаговый платеж)
Уведомление об оплате счета
### Одношаговый платеж
Выставление счета с оплатой без авторизации Покупателя (одношаговый платеж)
### Платежный токен
Выставление счета с оплатой платежным токеном
Платежные токены используются для списаний с карт или QIWI кошельков без ввода реквизитов карты или номера кошелька. Метод оплаты платежным токеном по умолчанию отключен. Чтобы подключить его, обратитесь к вашему сопровождающему менеджеру.
Подробнее о выпуске платежного токена см. в этом разделе.
Чтобы покупатель смог оплатить платежным токеном:
- Для списания средств по платежному токену без участия Покупателя воспользуйтесь методом API Платеж. См. подробнее описание использования платежного токена на Платежной форме мерчанта.
## Коды ошибок
Протокол приема платежей использует для запросов API следующие HTTP-коды ошибок:
| Код ошибки | Описание |
|------------|------------------------|
| 400 | Bad Request |
| 401 | Unauthorized |
| 403 | Forbidden |
| 404 | Not Found |
| 405 | Method Not Allowed |
| 406 | Not Acceptable |
| 410 | Gone |
| 429 | Too Many Requests |
| 500 | Internal Server Error |
| 502 | Bad Gateway |
| 503 | Service Unavailable |
## ChequeData
Информация о фискальном чеке по операции.
| Имя | Описание | Тип |
|-----|----------|-------|
| id | Идентификатор чека | String |
| url | Информация о чеке (URL-ссылка) | String |
## Акты
Акт по принятым платежам формируется ежемесячно во второй рабочий день месяца.
Акт сначала отправляется на email, указанный при регистрации в сервисе. После подтверждения со стороны партнера, уполномоченное лицо КИВИ Банка подписывает Акт в системе документооборота электронной подписью. Подписанный Акт отправляется на юридический адрес партнера.
## Оплата СБП
В тестовом режиме можно через API только выпускать QR-код СБП и запрашивать его статус. Для тестирования разных вариантов ответов указывайте разные суммы платежа (поле amount.value).
При запросе статуса платежа СБП в тестовом режиме доступно ограниченное количество статусов.
## Частота отправки уведомлений
Сервис отправки уведомлений распределяет неуспешные уведомления по очередям:
Время повторной отправки может быть увеличено.
## Статус QR-кода СБП
Пример запроса статуса QR-кода СБП
## Формат уведомления CHECK\_CARD
Пример тела уведомления CHECK\_CARD
| Поле | Описание | Тип |
|-------------------------------|-------------------------------------|---------------------------------|
| checkPaymentMethod | Описание результата проверки карты | Object |
| checkPaymentMethod.checkOperationDate | Дата проверки карты | URL-закодированная строка ГГГГ-ММ-ДДTчч:мм:ссZ |
| checkPaymentMethod.requestUid | Идентификатор операции проверки карты | String |
```markdown
## Проверка метода оплаты
- `checkPaymentMethod.status`: Статус проверки карты (String)
- `checkPaymentMethod.isValidCard`: Признак доступности карты для платежей (Bool)
- `checkPaymentMethod.threeDsStatus`: Информация о статусе дополнительной аутентификации при проверке карты. Возможные значения: PASSED (3-D Secure пройден), NOT_PASSED (3-D Secure не пройден), WITHOUT (3-D Secure не требовалось) (String)
### Информация о средстве платежа
- `checkPaymentMethod.paymentMethod.type`: Тип метода оплаты (String)
- `checkPaymentMethod.paymentMethod.maskedPan`: Маскированный PAN карты (String)
- `checkPaymentMethod.paymentMethod.cardExpireDate`: Срок действия карты (String)
- `checkPaymentMethod.paymentMethod.cardHolder`: Имя держателя карты (String)
### Информация о карте
- `checkPaymentMethod.cardInfo.issuingCountry`: Код страны эмитента (String)
- `checkPaymentMethod.cardInfo.issuingBank`: Банк-эмитент (String)
- `checkPaymentMethod.cardInfo.paymentSystem`: Тип платежной системы (String)
- `checkPaymentMethod.cardInfo.fundingSource`: Тип карты (String)
- `checkPaymentMethod.cardInfo.paymentSystemProduct`: Категория карты (String)
### Созданный платежный токен
- `checkPaymentMethod.createdToken.token`: Строка платежного токена (String)
- `checkPaymentMethod.createdToken.name`: Маскированный PAN карты, для которой выпущен платежный токен (String)
- `checkPaymentMethod.createdToken.expiredDate`: Дата окончания срока действия платежного токена в формате ISO-8601 (String)
- `checkPaymentMethod.createdToken.account`: Идентификатор покупателя, указанный при выпуске платежного токена (String)
- `checkPaymentMethod.merchantSiteUid`: Строковый идентификатор сайта ТСП в QIWI Кассе (String)
### Уведомление
- `type`: Тип уведомления — только CHECK_CARD (String)
- `version`: Версия уведомлений (String)
## Возмещение
По умолчанию, возмещение по проведенным операциям производится раз в 2 дня и минимальным порогом 10.000 рублей. Если вам необходимо особое расписание, обратитесь к вашему сопровождающему менеджеру.
КИВИ взимает комиссию за каждую подтвержденную операцию. Если отмена операции была произведена до подтверждения, комиссия не взимается. Если была произведена частичная отмена до подтверждения операции, комиссия будет пересчитана.
## Mir Pay
Клиент оплачивает покупку с Mir Pay без указания данных карты, через приложение Mir Pay. Для включения способа оплаты Mir Pay обратитесь к вашему сопровождающему менеджеру.
### Как отправлять платеж с расшифрованными данными
Пример оформленного платежа. Укажите в объекте paymentMethod запроса API Платёж параметры.
### Как отправлять платеж с зашифрованными данными
API Протокола приема платежей основано на принципах REST-архитектуры. Данные и методы считаются ресурсами, которые доступны через вызов универсальных идентификаторов ресурсов (URI). Методы API вызываются через HTTP-запросы. Постоянная часть URL-адреса для вызова методов API:

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

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

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

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

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

"some comment for payout operation"

"Incorrect payout amount"

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

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

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

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

Фискальный чек по успешной операции отправляется в синхронном ответе на указанные запросы API и в уведомлении об операции в объекте chequeData.

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

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

PayoutReceiverDataRequest

Информация о получателе. Доступные типы: CARD и SBP.

Тип метода выплаты CARD:

Поле Тип или константа Описание

typerequired CARD Тип метода выплаты

panrequired string(19) Номер банковской карты

receiverFirstName string(64) Имя получателя

receiverLastName string(64) Фамилия получателя

Тип метода выплаты SBP:

Поле Тип или константа Описание

typerequired SBP Тип метода выплаты

phonerequired number(11..13) Номер телефона

flags array of strings Дополнительные флаги для операции. Поддерживается значение INIT, которое включает двухшаговый сценарий выплаты на СБП. В случае передачи флага нужно будет дополнительно отправить запрос подтверждения выплаты

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

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

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

"Товар из корзины"

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

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

Название Тип Описание

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

type String Тип передаваемых данных. Доступные значения: MERCHANT_DETAILS (данные поставщика)

siteUid String ID поставщика

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

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

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

orderId String Номер заказа (необязательный)

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

Поле ответа Тип Описание

type String Тип передаваемых данных. Всегда возвращается строка MERCHANT_DETAILS

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

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

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

value String Сумма комиссии

currency String(3) Буквенный код валюты комиссии по ISO

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

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

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

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

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

splits Array Массив данных о поставщиках

siteUid String Зарегистрированный ID поставщика

splitAmount Object Возмещение поставщику

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

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

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

splits Array Массив с данными о сплитованных платежах

splitAmount Object Данные о возмещении поставщику

value String Сумма возмещения

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

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

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

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

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

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

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

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

Ответы API

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

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

Тип операции Статус операции Описание статуса

PAYMENT WAITING Ожидание 3DS авторизации

PAYMENT DECLINED Запрос авторизации отклонен (в синхронном ответе)

PAYMENT DECLINE Запрос авторизации отклонен (в асинхронном ответе)

PAYMENT COMPLETED Запрос авторизации успешно обработан

CAPTURE DECLINE Запрос подтверждения отклонен

CAPTURE DECLINED Запрос подтверждения отклонен (в ответе API на запрос статуса)

CAPTURE COMPLETED Запрос подтверждения успешно обработан

REFUND DECLINE Запрос возврата отклонен

REFUND COMPLETED Запрос возврата успешно обработан

PAYOUT WAITING Выплата принята в обработку

PAYOUT INIT Инициализация выплаты при двушаговом сценарии

PAYOUT DECLINED Выплата отклонена

PAYOUT COMPLETED Выплата успешно проведена

PAYMENT SUCCESS Запрос авторизации успешно обработан

CAPTURE SUCCESS Запрос подтверждения успешно обработан

REFUND SUCCESS Запрос возврата успешно обработан

PAYOUT SUCCESS Выплата успешно проведена

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

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

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

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

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

Особенности

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

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

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

PayoutReceiverDataCallback

maskedPanrequired string(19) Маскированный номер банковской карты

typerequired SBP Тип метода выплаты: "SBP" — СБП

phonerequired string Номер телефона

bankMemberIdrequired string(12) Идентификатор банка получателя в СБП

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

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

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

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

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

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

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

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

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

Параметр Описание Тип

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

lang Язык платежной формы. Язык по умолчанию — русский (ru). ru, en

paymentMethod Платежный метод, предлагаемый покупателю по умолчанию на платежной форме. Если указанный метод недоступен мерчанту, отображается другой доступный. По умолчанию — CARD. CARD, SBP, QIWI_WALLET

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

// Форма загружена // Попытка платежа // Платеж прошел успешно // Платеж не прошел

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

Возможные значения состояния:

Методы библиотеки позволяют открыть Платежную форму оплаты счета как всплывающее окно (popup) поверх вашего сайта. В библиотеке доступно два метода:

Для установки и подключения библиотеки добавьте скрипт в код сайта:

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

Чтобы создать счет и открыть форму оплаты, вызовите метод QiwiCheckout.createInvoice. Параметры метода:

Параметр Описание Формат

amount Обязательный параметр. Сумма, на которую выставляется счет, округленная в меньшую сторону до 2 десятичных знаков Number(6.2)

phone Номер телефона пользователя, на который выставляется счет (в международном формате) String

email E-mail пользователя, куда будет отправлена ссылка для оплаты счета String

account Идентификатор пользователя в системе мерчанта String

customFields Дополнительные данные счета. Список полей см. в описании одноименного параметра в запросе API выставления счета Object

lifetime Дата, до которой счет будет доступен для оплаты. Если счет не будет оплачен до этой даты, он получит финальный статус и последующая оплата станет невозможна. ГГГГ-ММ-ДДTччмм

Пример вызова метода открытия существующего счета

Этот метод используется, когда ссылка на Платежную форму оплаты счета получена при выставлении счета через API.

Чтобы открыть форму оплаты выставленного счета, вызовите метод QiwiCheckout.openInvoice. Параметры метода:

payUrl Обязательный параметр. URL-ссылка на Платежную форму String

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

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

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

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

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

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

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

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

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

Уведомление считается успешно доставленным, если ваш сервер ответил HTTP кодом состояния 200 OK.

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

Пример создания счета

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

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

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

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

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

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

"Some string pareq"

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

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

"Some string pares"

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

Сценарий дополнительной аутентификации аналогичен операции покупки:

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