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

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

Версия 1.29 | Редактировать на GitHub

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

• Банковские карты Visa, Mastercard, МИР.
• Yandex Pay.
• Mir 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 в производственный режим. В производственном режиме выполняются реальные списания средств с карт.

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

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

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

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

** — требуется сертификация PCI DSS.

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

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

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

• Счет (Invoice) — электронный документ, выставляемый продавцом покупателю. Содержит информацию о сумме и номере заказа. Не является финансовой сущностью и имеет ограниченный срок жизни. Выставление счета необходимо для получения ссылки на платежную форму QIWI.
• Платеж (Payment) — операция списания денежных средств от покупателя в пользу продавца. Фактическое списание происходит только после подтверждения (Capture). При работе через платежную форму QIWI, Payment — попытка оплаты счета (Invoice).
• Завершение (Complete) — завершение 3DS-верификации Покупателя. Используется при работе через Платежную форму мерчанта.
• Подтверждение (Capture) — операция подтверждения авторизации (списания) средств. Возможно только однократное успешное подтверждение авторизации.
• Возврат (Refund) — возврат средств покупателю по успешному платежу. Финансовая операция списания денежных средств от продавца в пользу покупателя. Если подтверждения операции Payment не было, то в ответе на операцию Refund вы получите флаг Reversal и деньги со счета Покупателя на счет продавца не перечислятся (комиссия за эквайринг также не удерживается).

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

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

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

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

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

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

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

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

Авторизация

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

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>

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

Аутентификация по цифровой подписи применяется только для создания операций типа “Выплата” через API.

Для аутентификации по цифровой подписи мерчант должен создать пару RSA-ключей, например, с помощью утилиты OpenSSL. Закрытый ключ должен быть размером 2048 бит в PEM-формате. Мерчант должен передать в QIWI закодированный в Base64 открытый ключ, соответствующий закрытому ключу.

Как создать ключи

1. Сгенерировать закрытый ключ. Выполните команду:

   openssl genrsa -out private-key.pem 2048

   В папке выполнения команды будет создан файл с закрытым ключом: private-key.pem.

2. Получить открытый ключ, соответствующий закрытому, командой:

   openssl rsa -in private-key.pem -pubout -out public-key.pem

3. Закодировать полученный ключ public-key.pem в Base64 командой:

   base64 -i public-key.pem

4. Передать закодированный в Base64 открытый ключ в QIWI, а закрытый ключ использовать для подписи запросов.

Как подписывать запросы

Алгоритм с примерами на языке Bash:

1. Сформировать body запроса в виде строки:

2. При помощи закрытого ключа private-key.pem, сгенерированного ранее, сформировать цифровую подпись по алгоритму SHA256withRSA:

3. Закодировать полученную цифровую подпись при помощи Base64 в строку:

4. Передать закодированную цифровую подпись в заголовке X-Digital-Sign при отправке запроса.

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

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

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

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

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

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

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

Оплата картой

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

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

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

• Mir: 2200000000000004, 2200000000000012, 2200000000000020, 2200000000000038, 2200000000000046, 2200000000000053, 2200000000000061, 2200000000000079, 2200000000000087, 2200000000000095, 2200000000000103, 2200000000000111
• Visa: 4256000000000003, 4256000000000011, 4256000000000029, 4256000000000037, 4256000000000045, 4256000000000052, 4256000000000060, 4256000000000078, 4256000000000086, 4256000000000094, 4256000000000102, 4256000000000110
• Mastercard: 5236000000000005, 5236000000000013, 5236000000000021, 5236000000000039, 5236000000000047, 5236000000000054, 5236000000000062, 5236000000000088, 5236000000000096, 5236000000000104, 5236000000000112, 5236000000000120
• UnionPay: 6056000000000000, 6056000000000018, 6056000000000026, 6056000000000034, 6056000000000042, 6056000000000059, 6056000000000067, 6056000000000075, 6056000000000083, 6056000000000091, 6056000000000109, 6056000000000117

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

Тестирование операций с 3-D Secure

1. Создайте платежную ссылку по API или без него.
2. Используйте любую карту из раздела Тестовые номера карт.
3. CVV для 3-D Secure в тестовом режиме должно быть равным 849 или используйте имя держателя карты, которое содержит строку 3ds.
4. Подтвердите или отклоните операцию на форме.
   

Ограничения при тестировании

• Из валют (параметр amount.currency) разрешен только рубль РФ (643).

• Установлены ограничения на сумму и количество операций:

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

Оплата СБП

В тестовом режиме можно через API только выпускать QR-код СБП и запрашивать его статус. Для тестирования разных вариантов ответов указывайте разные суммы платежа (поле amount.value):

• 200 — QR-код будет успешно создан.
• Для других сумм платеж пройдет неуспешно со статусом DECLINED.

При запросе статуса платежа СБП в тестовом режиме доступно ограниченное количество статусов:

• CREATED — Платеж создан.
• DECLINED — Платеж отклонен.
• EXPIRED — Срок действия платежа истек.

Выплаты

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

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

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

• Платежные токены карт.
• Система быстрых платежей.
• QIWI Кошелек.

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

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

sequenceDiagram
participant customer as Покупатель
participant store as Магазин
participant qb as QIWI (эквайер)
participant ips as Эмитент
customer->>store:Выбор товаров, Старт оплаты
activate store
store->>qb:API: запрос “Создание счета”
Одношаговый платеж — все способы оплаты
Двухшаговый платеж — только карты
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:Уведомление о статусе операции
rect rgb(255, 238, 223)
Note over qb, customer: Параметр “successUrl” указан в ссылке на платежную форму QIWI
qb->>customer: Возврат на сайт мерчанта при успешной операции
end
store->>qb: Проверка статуса операции
API: запрос “Статус платежа”
qb->>store: Статус операции
rect rgb(255, 238, 223)
Note over store, ips:Двухшаговый платеж
store->>qb:Подтверждение операции (capture)
qb->>ips:Подтверждение списания
deactivate ips
qb->>store:Уведомление о подтверждении платежа
store->>qb: Проверка статуса операции
API: запрос “Статус подтверждения”
qb->>store: Статус операции
end
deactivate qb
deactivate store

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

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

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

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

GET →

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

https://oplata.qiwi.com/create?publicKey5nAq6abtyCz4tcDj89e5w7Y5i524LAFmzrsN6bQTQ3ceEvMvCq55ToeErzhvK6rVkQLaCrYUQcYF5QkS8nCrjnPsLQgsLxqrpQgJ7hg2ZHmEHXFjaG8qjvgcep&extras[cf1]Order_123&extras[cf3]winnie@pooh.ru&readonly_extrascf1&commentsome%20comment&amount100.00

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

https://oplata.qiwi.com/create?publicKey5nAq6abtyCz4tcDj89e5w7Y5i524LAFmzrsN6bQTQ3ceEvMvCq55ToeErzhvK6rVkQLaCrYUQcYF5QkS8nCrjnPsLQgsLxqrpQgJ7hg2ZHmEHXFjaG8qjvgcep&extras[cf1]Order_123&extras[cf3]winnie@pooh.ru&readonly_extrascf1

• URL

• Параметры

  В URL query указываются параметры счета.

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

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

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

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

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

1. Передайте в запросе API Создание счета:

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

   Вы можете управлять методами платежа, которые будут отображены покупателю на Платежной форме. Для этого перечислите их в параметре API billPaymentMethodsType. Указанные методы должны быть включены через Службу поддержки для siteId из запроса.

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

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

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

1. Передайте в запросе API Создание счета:

   • ключ API;
   • сумму счета в параметре amount;
   • дату, до которой необходимо оплатить счет, в параметре expirationDateTime;
   • параметр "flags":["SALE"]. Если не передать его, то будет выполнено безусловное холдирование средств для оплаты счета;
   • (опционально) другую информацию о счете, в том числе:
     • комментарий в параметре comment;
     • информация о покупателе (customer, address) и получателе платежа (receiverData, при необходимости);
     • дополнительные данные по операции в параметре customFields.

   Вы можете управлять методами платежа, которые будут отображены покупателю на Платежной форме. Для этого перечислите их в параметре API billPaymentMethodsType. Указанные методы должны быть включены через Службу поддержки для siteId из запроса.

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

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

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

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

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

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

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

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

   

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

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

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

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

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

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

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

https://oplata.qiwi.com/form?invoiceUid606a5f75-4f8e-4ce2-b400-967179502275&successUrlhttps://example.com/payments/#introduction

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

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

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

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

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

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

• INITIALIZED — Форма загружена.
• PAYMENT_ATTEMPT — Попытка платежа.
• PAYMENT_SUCCEEDED — Платеж прошел успешно.
• PAYMENT_FAILED — Платеж не прошел.
• INITIALIZATION_FAILED — Ошибка загрузки формы.

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

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

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

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

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

  
     '<URL-ссылка на Платежную форму>'



      
        
    
      
        
    

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

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

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

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

• уникальный псевдоним стиля, привязанный к идентификатору siteId (цифры, латинские буквы и символ дефиса -);
• название мерчанта, которое будет отображаться на форме;
• лого в формате PNG или SVG и размера 48×48 или пропорционально больше;
• цвет кнопок в HEX-формате.

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

• ссылка на оферту вашего сервиса.

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

Чтобы применить ваш стиль на Платежной форме:

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

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

Пример применения настройки к Платежной форме:

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

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

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

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

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

• ключ доступа к API;
• сумму платежа;
• метод платежа;
• другую информацию для создания платежа.

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

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

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

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

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

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

• ключ доступа к API;
• сведения о сумме платежа;
• параметры метода платежа в объекте paymentMethod:
  • type — CARD;
  • pan — номер карты;
  • expiryDate – срок действия карты в формате MM/YY;
  • cvv2 — CVV2/CVC2 карты;
  • holderName – имя владельца карты (латиница);
• другую информацию о платеже.

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

• cardTokenPaymentType – параметр для корректной обработки транзакций в платежных системах для операций с сохраненными картами. Возможные значения:
  • FIRST_PAYMENT — если после этой операции вы сохраните карту на своей стороне.
  • INITIATED_BY_CLIENT — транзакция по сохраненной карте инициирована клиентом.
  • INITIATED_BY_MERCHANT — транзакция по сохраненной карте инициирована мерчантом.
  • RECURRING_PAYMENT — повторяющаяся операция по сохраненной карте.
  • INSTALLMENT — повторяющаяся операция по сохраненной карте в соответствии с графиком платежей для погашения кредита.
• firstTransaction – JSON-объект, содержащий сведения об идентификаторе транзакции, на которой была привязана карта. Содержит параметры:
  • paymentId – уникальный идентификатор платежа в информационной системе ТСП;
  • trnId – уникальный идентификатор платежа в информационной системе НСПК.

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

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

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

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

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

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

• acsUrl — URL сервера аутентификации 3-D Secure, для перенаправления на страницу подтверждения от эмитента;
• pareq — зашифрованный запрос на аутентификацию 3-D Secure.

Для дополнительной проверки покупателя у эмитента выполните 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).

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

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

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

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

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

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

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

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

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

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

• ключ доступа к API;
• сведения о сумме платежа;
• параметры метода платежа в объекте paymentMethod:
  • type — TOKEN;
  • paymentToken — строка платежного токена;
• customer.account — идентификатор покупателя в системе ТСП, для которого выпущен платежный токен. Без этого параметра оплата платежным токеном невозможна.
• другую информацию о платеже.

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

• cardTokenPaymentType – параметр для корректной обработки транзакций в платежных системах для операций с сохраненными картами. Возможные значения:
  • INITIATED_BY_CLIENT — транзакция по сохраненной карте инициирована клиентом.
  • INITIATED_BY_MERCHANT — транзакция по сохраненной карте инициирована мерчантом.
  • RECURRING_PAYMENT — повторяющаяся операция по сохраненной карте.
  • INSTALLMENT — повторяющаяся операция по сохраненной карте в соответствии с графиком платежей для погашения кредита.
• firstTransaction – JSON-объект, содержащий сведения об идентификаторе транзакции, на которой была привязана карта. Содержит параметры:
  • paymentId – уникальный идентификатор платежа в информационной системе ТСП;
  • trnId – уникальный идентификатор платежа в информационной системе НСПК.

Yandex Pay

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

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

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

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

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

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

• CLOUD_TOKEN. Без дополнительной аутентификации покупателя.

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

  • type — CARD;
  • данные из расшифрованного платежного токена Yandex Pay:
    • PAN карты в поле "pan";
    • срок действия в формате MM/YY в поле "expiryDate";
    • объект external3dSec с элементами:
      • type — YANDEX_PAY;
      • cryptogram — содержимое поля cryptogram платежного токена Yandex Pay (Base64-закодированная строка);
      • eciIndicator — ECI-индикатор. Необходимо передавать, если поле eciIndicator получено в платежном токене Yandex Pay. В противном случае параметр не передавать.

• PAN_ONLY. С дополнительной аутентификацией покупателя (3-D Secure).

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

  • type — CARD;
  • данные из расшифрованного платежного токена Yandex Pay:
    • PAN карты в поле "pan";
    • срок действия в формате MM/YY в поле "expiryDate";
    • объект external3dSec с полем type=YANDEX_PAY.

Mir Pay

Клиент оплачивает покупку с Mir Pay без указания данных карты, через приложение Mir Pay.

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

1. Клиент выбирает способ оплаты Mir Pay.
2. Платёжная форма зашифровывает информацию о покупке (сумма, валюта и т. д.) по технологии Deep Link или Universal Link согласно спецификации НСПК для In-Application операций и перенаправляет клиента в приложение Mir Pay.
3. Клиент подтверждает оплату в приложении.
4. Приложение передает криптограмму платежа (JWT-токен) в формате JWE мерчанту.
5. Мерчант отправляет JWT-токен в платёжном запросе к API. Токен может быть отправлен как в зашифрованном, так и в расшифрованном виде. В последнем случае мерчант должен быть подключен как агрегатор.

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

Пример оформленного платежа

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

• type — CARD;
• данные из расшифрованного платежного токена Mir Pay:
  • токенизированный номер карты в поле "pan";
  • срок действия (в формате MM/YY) в поле "expiryDate";
  • объект external3dSec с элементами:
    • type — MIR_PAY;
    • cav — In-Application криптограмма (в HEX-формате длиной 38 символов);
    • transId — идентификатор In-Application операции (в формате UUID);
    • mid — идентификатор ТСП (MerchantId) в системе агрегатора;
    • media — тип источника, через который инициирована In-Application операция. Допустимые значения:
      • ISDK (In-Application SDK),
      • DL (Deep link),
      • UL (Universal link),
      • TR (In-Application Mir HCE SDK).

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

Пример оформленного платежа

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

• type — MIR_PAY_TOKEN;
• cryptogram — JWE-токен с зашифрованными данными In-Application операции, полученный от приложения Mir Pay после подтверждения платежа клиентом.

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

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

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

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

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

"Flower for my girlfriend"

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

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

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

• Уникальный идентификатор запроса.
• Объект qrCode с характеристиками запрашиваемого QR-кода:
  • Тип QR-кода в параметре qrCode.type:
    • DYNAMIC — динамический QR-код, индивидуальный для каждой оплаты.
  • Срок действия кода в минутах в параметре qrCode.ttl. По истечении срока QR-код деактивируется. По умолчанию срок действия 72 часа.
  • Тип и размер изображения QR-кода в блоке qrCode.image.
• Сумму платежа в блоке amount.
• Параметр paymentPurpose с описанием платежа. Если не указан, в приложении банка покупателя отобразится название вашего магазина.

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

• image.content — base64-encoded QR-код. После расшифровки вы получите изображение для отображения покупателю.
• payload — URL-based QR для перенаправления покупателя в приложение банка.

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

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

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

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

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

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

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

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

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

• платежный токен в параметре token,
• идентификатор покупателя, для которого был выпущен платежный токен, в параметре tokenizationAccount.

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

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

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

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

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

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

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

• type — MOBILE_COMMERCE.
• phone — номер телефона, с баланса которого выполняется оплата. Номер указывается в международном формате со знаком +.

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

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

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

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

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

• callbackUrl — в запросах API Платеж, Подтверждение платежа, Операция возврата и Выплата;
• customFields.invoice_callback_url — в запросе API Создание счета.

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

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

• 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 и ключом, указанным в разделе Настройки Личного кабинета мерчанта.

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

1. Набор полей уведомления для проверки подписи зависит от типа уведомления:

   • тип 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
   • тип TOKEN: token.merchantSiteUid|token.account|token.status.value|token.status.changedDateTime
   • тип PAYOUT: payout.payoutId|payout.createdDateTime|payout.amount.value

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

   hash = HMAC(SHA256, secret, parameters)

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

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

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

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

• 1 попытка с отложенным временем 5 секунд.
• 1 попытка с отложенным временем 1 минута.
• 3 попытки с отложенным временем по 5 минут.

Время повторной отправки может быть увеличено.