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

Последнее обновление: 23-01-2023 | Версия 1.19 | Редактировать на GitHub

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

• Банковские карты Visa, Mastercard, МИР.
• 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.
• Платеж через форму мерчанта.

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

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

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

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

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

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

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

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

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

URL-адрес для вызова API:

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

Методы API вызываются через HTTP-запросы. Параметры методов помещаются в 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>

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

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

Для аутентификации по цифровой подписи мерчант должен создать пару 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 запроса в виде строки:

   REQUEST_BODY='{"amount":{"value":100, "currency":"RUB"},...'

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

   SIGNATURE_RAW=$(echo -n $REQUEST_BODY | openssl dgst -sha256 -sign private-key.pem)

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

   SIGNATURE_BASE64=$(echo -n $SIGNATURE_RAW | base64)

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

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

При подключении ваш идентификатор 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. Учитываются операции за текущие сутки (время по МСК) с суммой каждой операции не более установленного лимита 10 рублей.

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

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

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

• 200 — операция пройдет успешно с задержкой. При первом запросе статуса платежа вы получите статус "WAITING", после второго запроса статуса платежа — статус "SUCCESS".
• Для других сумм платеж пройдет неуспешно.

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

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

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

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

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

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

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

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

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

GET →

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

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?publicKey={key}&{parameter}={value}

• Параметры

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

Выставление счета и получение ссылки на оплату через 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"
   },
   "billPaymentMethodsType": [
      "QIWI_WALLET",
      "SBP"
   ],
   "comment": "Spasibo",
   "expirationDateTime": "2019-09-13T14:30:00+03:00",
   "customFields": {}
}

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

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

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

{
  "payment": {
    "type": "PAYMENT",
    "paymentId": "824c7744-1650-4836-abaa-842ca7ca8a74",  <==paymentId, необходимый для подтверждения
    "createdDateTime": "2022-07-27T12:43:35+03:00",
    "status": {
        "value": "SUCCESS",
        "changedDateTime": "2022-07-27T12:43:47+03:00"
    },
    "amount": {
        "value": 1.00,
        "currency": "RUB"
    },
    "paymentMethod": {
        "type": "CARD",
        "maskedPan": "512391******6871",
        "cardHolder": null,
        "cardExpireDate": "3/2030"
    },
    "tokenData": {
        "paymentToken": "cc123da5-2fdd-4685-912e-8671597948a3",
        "expiredDate": "2030-03-01T00:00:00+03:00"
    },
    "customFields": {
        "cf2": "dva",
        "cf1": "1",
        "cf4": "4",
        "cf3": "tri",
        "cf5": "5",
        "full_name": "full_name",
        "phone": "phone",
        "contract_id": "contract_id",
        "comment": "test",
        "booking_number": "booking_number"
    },
    "paymentCardInfo": {
        "issuingCountry": "643",
        "issuingBank": "Тинькофф банк",
        "paymentSystem": "MASTERCARD",
        "fundingSource": "UNKNOWN",
        "paymentSystemProduct": "TNW|TNW|Mastercard® New World—Immediate Debit|TNW|Mastercard New World-Immediate Debit"
    },
    "customer": {
        "email": "darta@mail.ru",
        "account": "11235813",
        "phone": "79850223243"
    },
    "gatewayData": {
        "type": "ACQUIRING",
        "eci": "2",
        "authCode": "0123342",
        "rrn": "001239598011"
    },
    "billId": "191616216126154",
    "flags": [
        "AFT"
    ]
  },
  "type": "PAYMENT",
  "version": "1"
}

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

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

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

2. Перенаправьте покупателя на Платежную форму по ссылке из параметра payUrl ответа, или используйте библиотеку Popup, чтобы открыть форму во всплывающем окне.
3. Получите идентификатор платежа paymentId:
   • из серверного уведомления после успешного холдирования средств;
   • из ответа на запрос API Получение списка платежей по счету.
4. Отправьте запрос API Подтверждение платежа с полученным paymentId. Возмещение формируется только после подтверждения.
5. Дождитесь завершения платежа: вам поступит уведомление, или периодически отправляйте запрос 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": "100.00"
   },
   "expirationDateTime": "2018-04-13T14:30:00+03:00",
   "flags": [
     "SALE"
    ]
}

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

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

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

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

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

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

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"
   }
   }
}

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

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

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

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

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

   

   Для оплаты покупателю достаточно выбрать карту из списка. Указывать карточные данные и проходить проверку 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

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

Пример обработчика событий 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 — Ошибка загрузки формы.

Библиотека Checkout Popup

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

• Выставление нового счета.
• Открытие существующего счета.

Пример работы popup

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

<script src='https://oplata.qiwi.com/popup/v2.js'></script>

Выставление нового счета

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

QiwiCheckout.createInvoice({
    publicKey: '5nAq6abtyCz4tcDj89e5w7Y5i524LAFmzrsN6bQTQ3c******',
    amount: 10.00,
    phone: '79123456789',
    email: 'test@example.ru',
    account: 'account1',
    comment: 'Платеж',
    customFields: {
        data: 'data'
    },
    lifetime: '2022-04-04T1540'
})
    .then(data => {
        //     ...
    })
    .catch(error => {
        //     ...
    })

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

Открытие существующего счета

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

params = {
    payUrl: '<URL-ссылка на Платежную форму>'
}

QiwiCheckout.openInvoice(params)
    .then(data => {
        // ...
    })
    .catch(error => {
        // ...
    })

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

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

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

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

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

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

• картинка для фона в формате PNG или SVG и размера 382x560 или пропорционально больше;
• варианты предвыбранных сумм платежа (не более трех);
• контактный e-mail для отображения на странице;
• URL страницы успешного платежа;
• номер счетчика Яндекс.Метрики;
• ссылка на оферту вашего сервиса.

Пример передачи параметра стиля при выставлении счета через 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": 100.00
   },
   "comment": "Text comment",
   "expirationDateTime": "2018-04-13T14:30:00+03:00",
   "customer": {},
   "customFields": {
     "themeCode":"merchant01-theme01"
   }
}

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

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

  "themeCode":"merchant01-theme01".

• Передайте в прямом вызове Платежной формы в параметре extras[themeCode] псевдоним стиля, который вы указали при настройке. Например:

  ...&extras[themeCode]=merchant01-theme01.

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

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

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

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

• Платежные токены карт и QIWI Кошелька.
• Yandex Pay.
• Система Быстрых Платежей (СБП).
• Баланс мобильного телефона

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

Чтобы создать платеж, передайте в запросе 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...."
  }
}

Если требуется 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).

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

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

{
  "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.

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

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_ONLY. С дополнительной аутентификацией покупателя (3-D Secure).

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

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

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

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

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

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

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

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

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

{
  "qrCodeUid": "Test12",
  "amount": {
    "currency": "RUB",
    "value": "100.00"
  },
  "qrCode": {
    "type": "DYNAMIC",
    "ttl": 999,
    "image": {
        "mediaType": "image/png",
        "width": 300,
        "height": 300,
        "content": "iVBORw0KGgoAAAANSUhEUgAAASwAAAEsCAYAA"
    },
    "payload": "https://qr.nspk.ru/AD10006M8KH234K782OQM0L13JI31LQDtype=02bank=100000000009&sum=200&cur=RUB&crc=C63A",
    "status": "CREATED"
  },
  "createdOn": "2022-08-11T20:10:32+03:00"
}

При оплате через СБП покупатель сканирует 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-кода

{
  "qrCodeUid": "Test",
  "amount": {
    "currency": "RUB",
    "value": "1.00"
  },
  "qrCode": {
    "type": "DYNAMIC",
    "ttl": 999,
    "payload": "https://qr.nspk.ru/AD10006M8KH234K782OQM0L13JI31LQDtype=02bank=100000000009&sum=200&cur=RUB&crc=C63A",
    "status": "PAYED"
  },
  "payment": {
    "paymentUid": "A22231710446971300200933E625FCB3",
    "paymentStatus": "COMPLETED"
  },
  "createdOn": "2022-08-11T20:10:32+03:00"
}

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

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

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

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

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

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

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

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

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

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

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

Пример платежа

{
  "paymentMethod": {
    "type": "MOBILE_COMMERCE",
    "phone": "+79111111111"
  },
  "amount": {
    "value": 5900.00,
    "currency": "RUB"
  },
  "flags": [
    "SALE"
  ],
  "customer": {
    "account": "79111111111",
    "email": "test@qiwi.com",
    "phone": "79111111111"
  }
}

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

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

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

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

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 — отправляются при совершении операций проверки карты;
• PAYOUT — отправляются при совершении операций выплаты.

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

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

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

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

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

   где {*} – значение параметра уведомления. Все значения предварительно приводятся к строковому представлению (UTF-8).

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

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

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

   hash = HMAС(SHA256, secret, parameters)

   Где:

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

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

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

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

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

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

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

• HEADERS

  • Signature: XXX
  • Accept: application/json
  • Content-type: application/json

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

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

{
  "payment": {
    "paymentId": "A22170834426031500000733E625FCB3",
    "customFields": {},
    "type": "PAYMENT",
    "createdDateTime": "2022-08-05T11:34:42+03:00",
    "status": {
      "value": "SUCCESS",
      "changedDateTime": "2022-08-05T11:34:44+03:00"
    },
    "amount": {
      "value": 5,
      "currency": "RUB"
    },
    "paymentMethod": {
      "type": "SBP",
      "phone": "79111112233"
    },
    "customer": {
      "phone": "0",
      "bankAccountNumber": "4081710809561219555",
      "bic": "044525974",
      "lastName": "ИВАНОВ",
      "firstName": "ИВАН",
      "middleName": "ИВАНОВИЧ",
      "simpleAddress": ""
    },
    "billId": "autogenerated-6cd20922-b1d0-4e67-ba61-e2b7310c4006",
    "flags": [
      "SALE"
    ],
    "qrCodeUid": "acfd9"
  },
  "type": "PAYMENT",
  "version": "1"
}

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

• HEADERS

  • Signature: XXX
  • Accept: application/json
  • Content-type: application/json

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

• HEADERS

  • Signature: XXX
  • Accept: application/json
  • Content-type: application/json

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

• HEADERS

  • Signature: XXX
  • Accept: application/json
  • Content-type: application/json

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

• HEADERS

  • Signature: XXX
  • Accept: application/json
  • Content-type: application/json

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

POST <callback-path> HTTP/1.1
Accept: application/json
Content-type: application/json
Signature: J4WNfNZd***V5mv2w=
Host: <callback-url>

{
  "payout": {
    "payoutId":"kxnawm631754",
    "createdDateTime":"2022-12-22T16:20:30+03:00",
    "amount": {
      "value":200.00,
      "currency":"RUB"
    },
    "status":{
      "value":"SUCCESS",
      "changedDateTime":"2022-12-22T16:34:44+03:00"
    },
    "receiverData": {
      "type":"CARD",
      "maskedPan":"400000******0002"
    },
    "flags":["TEST"]
  },
  "type":"PAYOUT",
  "version":"1"
}

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

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

• Возвраты доступны только для успешно завершенных операций платежа.
• Отмена операции возможна только при двухшаговом сценарии платежа и только для операций, по которым ещё не было подтверждения (CAPTURE).

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

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

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

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

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

Чтобы выполнить возврат по карточному платежу, используйте метод 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 ответа содержатся данные о сплитованных платежах:

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

Чтобы отправить платеж со сплитованием, передайте в запросе 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 ответа содержатся данные о принятых платежах и комиссиях:

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

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

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

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:

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

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

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

{
    "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": ".."
}

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

1. Без платежа (предпочтительный способ).

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

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

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

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

   • В блоке createdToken ответа на финальный запрос.
   • В уведомлении CHECK_CARD.

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

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

2. В процессе проведения платежа.

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

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

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

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

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

См. подробности о том, как использовать платежный токен на Платежной форме QIWI и на Платежной форме мерчанта.

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

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

{
  "qrCodeUid": "Test123",
  "qrCode": {
    "type": "TOKEN",
    "image": {
        "mediaType": "image/png",
        "width": 300,
        "height": 300
      }
  },
  "tokenizationPurpose": "Описание с деталями привязки счета",
  "tokenizationAccount": "3e2322",
  "flags": ["CREATE_TOKEN"]
}

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

{
  "qrCodeUid": "Test123",
  "qrCode": {
    "type": "TOKEN",
    "ttl": 10,
    "image": {
        "mediaType": "image/png",
        "width": 300,
        "height": 300,
        "content": "iVBORw0KGgoAAAANSUhEUgAAASwAAAEsCAYAA"
    },
    "payload": "https://qr.nspk.ru/AD10006M8KH234K782OQM0L13JI31LQDб",
    "status": "CREATED"
  },
  "tokenizationPurpose": "Описание с деталями привязки счета",
  "flags": ["CREATE_TOKEN"],
  "token": {
      "status": "CREATED",
      "value": "a4a312345-6789-1234-a567-89a1234567a0",
      "expiredDate": "2023-08-11T10:10:32+03:00"
  },
  "createdOn": "2022-08-11T20:10:32+03:00"
}

Пример тела запроса выпуска qr-кода СБП на оплату с привязкой счета

{
  "qrCodeUid": "Test123",
  "amount": {
    "value": 100.00,
    "currency": "RUB"
  },
  "qrCode": {
    "type": "DYNAMIC",
    "image": {
        "mediaType": "image/png",
        "width": 300,
        "height": 300
      }
  },
  "tokenizationPurpose": "Описание с деталями привязки счета",
  "tokenizationAccount": "3e2322",
  "redirectUrl": "http://someurl.com"
  "flags": ["CREATE_TOKEN"]
}

Пример тела ответа выпуска qr-кода СБП на оплату с привязкой счета

{
  "qrCodeUid": "Test123",
  "amount": {
    "value": 100.00,
    "currency": "RUB"
  },
  "qrCode": {
    "type": "DYNAMIC",
    "ttl": 10,
    "image": {
        "mediaType": "image/png",
        "width": 300,
        "height": 300,
        "content": "iVBORw0KGgoAAAANSUhEUgAAASwAAAEsCAYAA"
    },
    "payload": "https://qr.nspk.ru/AD10006M8KH234K782OQM0L13JI31LQDб",
    "status": "CREATED"
  },
  "redirectUrl": "http://someurl.com",
  "tokenizationPurpose": "Описание с деталями привязки счета",
  "flags": ["CREATE_TOKEN"],
  "token": {
    "status": "CREATED",
    "value": "a4a312345-6789-1234-a567-89a1234567a0",
    "expiredDate": "2023-08-11T10:10:32+03:00"
  },
  "createdOn": "2022-08-11T20:10:32+03:00"
}

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

1. Без платежа.

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

   • Объект qrCode с характеристиками запрашиваемого QR-кода:
     • Тип QR-кода в параметре qrCode.type — TOKEN.
     • Тип и размер изображения QR-кода в блоке qrCode.image.
   • Параметр tokenizationAccount — уникальный идентификатор Покупателя в системе ТСП.
   • Параметр "flags":["CREATE_TOKEN"].
   • Описание токена в параметре tokenizationPurpose.

2. Платеж с привязкой счета.

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

   • Объект qrCode с характеристиками запрашиваемого QR-кода:
     • Тип QR-кода в параметре qrCode.type — DYNAMIC.
     • Тип и размер изображения QR-кода в блоке qrCode.image.
   • Сумму платежа.
   • Параметр tokenizationAccount — уникальный идентификатор Покупателя в системе ТСП.
   • Параметр "flags":["CREATE_TOKEN"].
   • Описание токена в параметре tokenizationPurpose.

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

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

О том, как платить токеном СБП, читайте в разделе Оплата токеном через СБП.

Выпуск платежного токена 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"
    }
}