Ошибка авторизации qr payment

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

Последнее обновление: 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.
• Платеж через форму мерчанта.

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

Метод	Платежная форма QIWI	Платежная форма мерчанта
Банковская карта*	✓	✓
Оплата платежным токеном	✓	✓
Yandex Pay	×	✓
Оплата через СБП	✓	✓
Оплата с баланса КИВИ Кошелька	✓	✓**
Оплата с баланса мобильного телефона	×	✓

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

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

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

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

• Счет (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-архитектуры.

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 по прямой ссылке с параметрами счета.

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

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:Уведомление о статусе операции
qb->>customer: Возврат на сайт мерчанта при успешной операции (successUrl)
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?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 указываются параметры счета.

Параметр ссылки	Описание	Тип
publicKey	Обязательный параметр. Ключ идентификации мерчанта, уникальный для каждого siteId. Ключ можно получить в Личном кабинете в разделе Настройки.	String
billId	Уникальный идентификатор счета в системе мерчанта. Генерируется на вашей стороне любым способом как уникальная последовательность букв, цифр и символов _, -. Если не указан, то при каждом переходе по ссылке создается новый счет.	URL-закодированная строка String(200)
amount	Сумма покупки, округленная в меньшую сторону до 2 десятичных знаков (всегда в рублях)	Number(6.2)
currency	Код валюты покупки. Возможные значения: RUB, EUR, USD. По умолчанию RUB	String(3)
phone	Номер телефона покупателя (в международном формате)	URL-закодированная строка
email	E-mail покупателя	URL-закодированная строка
comment	Комментарий к счету	URL-закодированная строка String(255)
successUrl	URL для возврата на сайт мерчанта в случае успешной оплаты. Ссылку необходимо указывать в кодировке UTF-8.	URL-закодированная строка
paymentMethod	Платежный метод, предлагаемый покупателю по умолчанию на платежной форме. Возможные значения: CARD, SBP, QIWI_WALLET. Если указанный метод недоступен мерчанту, отображается другой доступный. По умолчанию — CARD.	String
extras[cf1]	Дополнительное поле с произвольной информацией, дополняющей данные счета	URL-закодированная строка
extras[cf2]	Дополнительное поле с произвольной информацией, дополняющей данные счета	URL-закодированная строка
extras[cf3]	Дополнительное поле с произвольной информацией, дополняющей данные счета	URL-закодированная строка
extras[cf4]	Дополнительное поле с произвольной информацией, дополняющей данные счета	URL-закодированная строка
extras[cf5]	Дополнительное поле с произвольной информацией, дополняющей данные счета	URL-закодированная строка
extras[themeCode]	Дополнительное поле с кодом стиля Платежной формы	URL-закодированная строка
readonly_extras	Список дополнительных полей, которые должны быть недоступны для изменения покупателем на платежной форме	Строка, разделитель имен полей ,. Пример: cf1,cf3

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

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

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

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

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

{
   "amount": {
     "currency": "RUB",
     "value": "42.24"
   },
   "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

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

Параметр	Описание	Тип
successUrl	URL для возврата на сайт мерчанта в случае успешной оплаты. Возврат произойдет после успешной 3DS аутентификации. Ссылку необходимо указывать в кодировке UTF-8.	URL-закодированная строка
lang	Язык платежной формы. Язык по умолчанию — русский (ru).	ru, eng
paymentMethod	Платежный метод, предлагаемый покупателю по умолчанию на платежной форме. Если указанный метод недоступен мерчанту, отображается другой доступный. По умолчанию — CARD.	CARD, SBP, QIWI_WALLET

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

Методы библиотеки позволяют открыть Платежную форму оплаты счета как всплывающее окно (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. Параметры метода:

Параметр	Описание	Формат
publicKey	Обязательный параметр. Ключ идентификации мерчанта, уникальный для каждого siteId. Ключ можно получить в Личном кабинете в разделе Настройки.	String
amount	Обязательный параметр. Сумма, на которую выставляется счет, округленная в меньшую сторону до 2 десятичных знаков	Number(6.2)
phone	Номер телефона пользователя, на который выставляется счет (в международном формате)	String
email	E-mail пользователя, куда будет отправлена ссылка для оплаты счета	String
account	Идентификатор пользователя в системе мерчанта	String
comment	Комментарий к счету	String(255)
customFields	Дополнительные данные счета. Список полей см. в описании одноименного параметра в запросе API выставления счета	Object
lifetime	Дата, до которой счет будет доступен для оплаты. Если счет не будет оплачен до этой даты, он получит финальный статус и последующая оплата станет невозможна.	ГГГГ-ММ-ДДTччмм

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

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

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

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

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

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

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

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

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

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

• картинка для фона в формате PNG или SVG и размера 382×560 или пропорционально больше;
• варианты предвыбранных сумм платежа (не более трех);
• контактный 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.
• Система Быстрых Платежей (СБП).
• Баланс мобильного телефона

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

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;
• сумму платежа;
• метод платежа;
• другую информацию для создания платежа.

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

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

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

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

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.

Параметр	Тип	Описание
paymentMethod.type	String	Тип операции. Только TOKEN
paymentMethod.paymentToken	String	Строка платежного токена
customer.account	String	Уникальный идентификатор Покупателя в системе ТСП, для которого выпущен платежный токен. Без этого параметра оплата платежным токеном невозможна.

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

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

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

Поле	Описание	Тип	В каких случаях используется
payment	Описание платежа.	Object	Всегда
type	Тип операции — только PAYMENT	String(200)	Всегда
paymentId	Уникальный идентификатор платежа в системе ТСП.	String(200)	Всегда
createdDateTime	Дата создания операции	URL-закодированная строка ГГГГ-ММ-ДДTЧЧ:ММ:ССZ	Всегда
billId	Идентификатор счета, соответствующего операции	String(200)	Всегда
qrCodeUid	Идентификатор операции выпуска QR-кода в системе ТСП	String	Если операция была выполнена через СБП
amount	Информация о сумме операции	Object	Всегда
value	Сумма операции, округленная до двух десятичных знаков в меньшую сторону	Number(6.2)	Всегда
currency	Идентификатор валюты операции (Alpha-3 ISO 4217 код)	String(3)	Всегда
status	Информация о статусе операции	Object	Всегда
value	Строковое значение статуса	String	Всегда
changedDateTime	Дата обновления статуса	URL-закодированная строка ГГГГ-ММ-ДДTЧЧ:ММ:ССZ	Всегда
reasonCode	Код причины отклонения	String(200)	В случае отклонения операции
reasonMessage	Описание причины отклонения	String(200)	В случае отклонения операции
errorCode	Код ошибки	Number	В случае ошибки
paymentMethod	Информация о средстве платежа	Object	Всегда
type	Тип метода оплаты: CARD — банковская карта, TOKEN — платежный токен, SBP — Система Быстрых Платежей, QIWI_WALLET — баланс QIWI Кошелька	String	Всегда
paymentToken	Платежный токен карты.	String	При оплате платежным токеном
maskedPan	Маскированный PAN карты	String	При оплате платежным токеном или картой
rrn	RRN платежа (по ISO 8583)	Number	При оплате платежным токеном или картой
authCode	Auth-code платежа	Number	При оплате платежным токеном или картой
phone	Телефон, с которого выполнялась оплата через СБП, или номер QIWI Кошелька	String	При оплате через СБП или с баланса QIWI Кошелька
paymentCardInfo	Информация о карте.	Object	Всегда
issuingCountry	Код страны эмитента	String(3)	Всегда
issuingBank	Банк-эмитент	String	Всегда
paymentSystem	Тип платежной системы	String	Всегда
fundingSource	Тип карты	String	Всегда
paymentSystemProduct	Категория карты	String	Всегда
customer	Информация о покупателе	Object	Всегда
phone	Номер телефона покупателя	String	Всегда
email	E-mail покупателя	String	Всегда
account	Идентификатор покупателя в системе ТСП	String	Всегда
ip	IP адрес покупателя	String	Всегда
country	Страна адреса покупателя	String	Всегда
bankAccountNumber	Номер счета плательщика	String	Только для платежей через СБП
bic	БИК банка, выпустившего карту	String	Только для платежей через СБП
lastName	Фамилия покупателя	String	Только для платежей через СБП
firstName	Имя покупателя	String	Только для платежей через СБП
middleName	Отчество покупателя	String	Только для платежей через СБП
simpleAddress	Адрес покупателя	String	Только для платежей через СБП
inn	ИНН покупателя	String	Только для платежей через СБП
customFields	Поля с произвольной информацией, дополняющей данные по операции	Object	Всегда
cf1	Поле с произвольной информацией, дополняющей данные по операции	String(256)	Всегда
cf2	Поле с произвольной информацией, дополняющей данные по операции	String(256)	Всегда
cf3	Поле с произвольной информацией, дополняющей данные по операции	String(256)	Всегда
cf4	Поле с произвольной информацией, дополняющей данные по операции	String(256)	Всегда
cf5	Поле с произвольной информацией, дополняющей данные по операции	String(256)	Всегда
flags	Дополнительные команды, переданные в API	Массив. Возможные элементы — SALE/REVERSAL	Всегда
tokenData	Объект с информацией о выпущенном платежном токене	Object	Если в платеже был запрошен выпуск платежного токена
paymentToken	Строка платежного токена	String	Если в платеже был запрошен выпуск платежного токена
expiredDate	Дата окончания срока действия платежного токена. Формат даты соответствует стандарту ISO-8601: YYYY-MM-DDThh:mm:ss±hh:mm	String	Если в платеже был запрошен выпуск платежного токена
paymentSplits	Описание сплитованных платежей.	Array(Objects)	Для сплитованных платежей
type	Тип передаваемых данных. Всегда строка MERCHANT_DETAILS	String	Для сплитованных платежей
siteUid	ID поставщика	String	Для сплитованных платежей
splitAmount	Информация о возмещении поставщику	Object	Для сплитованных платежей
value	Сумма возмещения	Number	Для сплитованных платежей
currency	Буквенный код валюты возмещения по ISO	String(3)	Для сплитованных платежей
splitCommissions	Информация о комиссии	Object	Для сплитованных платежей
merchantCms	Информация о комиссии с поставщика	Object	Для сплитованных платежей
value	Сумма комиссии	Number	Для сплитованных платежей
currency	Буквенный код валюты комиссии по ISO	String(3)	Для сплитованных платежей
orderId	Номер заказа	String	Для сплитованных платежей
comment	Комментарий к заказу	String	Для сплитованных платежей
type	Тип уведомления — только PAYMENT	String(200)	Всегда
version	Версия уведомлений	String	Всегда

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

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

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

Поле	Описание	Тип	В каких случаях используется
refund	Описание возврата.	Object	Всегда
type	Тип операции — только REFUND	String(200)	Всегда
refundId	Уникальный идентификатор возврата в системе ТСП.	String(200)	Всегда
createdDateTime	Дата создания операции	URL-закодированная строка ГГГГ-ММ-ДДTЧЧ:ММ:ССZ	Всегда
amount	Информация о сумме операции	Object	Всегда
value	Сумма операции, округленная до двух десятичных знаков в меньшую сторону	Number(6.2)	Всегда
currency	Идентификатор валюты операции (Alpha-3 ISO 4217 код)	String(3)	Всегда
billId	ID счета, соответствующего операции	String(200)	Всегда
status	Информация о статусе операции	Object	Всегда
value	Строковое значение статуса	String	Всегда
changedDateTime	Дата обновления статуса	URL-закодированная строка ГГГГ-ММ-ДДTЧЧ:ММ:ССZ	Всегда
reasonCode	Код причины отклонения	String(200)	В случае отклонения операции
reasonMessage	Описание причины отклонения	String(200)	В случае отклонения операции
errorCode	Код ошибки	Number	В случае ошибки
paymentMethod	Информация о средстве платежа	Object	Всегда
type	Тип метода оплаты	String	Всегда
maskedPan	Маскированный PAN карты	String	Всегда
rrn	RRN платежа (по ISO 8583)	Number	Всегда
authCode	Auth-code платежа	Number	Всегда
customer	Информация о покупателе	Object	Всегда
phone	Номер телефона покупателя	String	Всегда
email	E-mail покупателя	String	Всегда
account	Идентификатор покупателя в системе ТСП	String	Всегда
ip	IP адрес покупателя	String	Всегда
country	Страна адреса покупателя	String	Всегда
customFields	Поля с произвольной информацией, дополняющей данные по операции	Object	Всегда
cf1	Поле с произвольной информацией, дополняющей данные по операции	String(256)	Всегда
cf2	Поле с произвольной информацией, дополняющей данные по операции	String(256)	Всегда
cf3	Поле с произвольной информацией, дополняющей данные по операции	String(256)	Всегда
cf4	Поле с произвольной информацией, дополняющей данные по операции	String(256)	Всегда
cf5	Поле с произвольной информацией, дополняющей данные по операции	String(256)	Всегда
flags	Дополнительные команды, переданные в API	Массив. Возможные элементы — SALE/REVERSAL	Всегда
refundSplits	Описание возвратов по сплитованным платежам.	Array(Objects)	При возвратах сплитованных платежей
type	Тип передаваемых данных. Всегда строка MERCHANT_DETAILS	String	При возвратах сплитованных платежей
siteUid	ID поставщика	String	При возвратах сплитованных платежей
splitAmount	Информация об отмене возмещения поставщику	Object	При возвратах сплитованных платежей
value	Сумма отмены возмещения	Number	При возвратах сплитованных платежей
currency	Буквенный код валюты отмены возмещения по ISO	String(3)	При возвратах сплитованных платежей
splitCommissions	Информация о комиссии	Object	При возвратах сплитованных платежей
merchantCms	Информация о комиссии с поставщика	Object	При возвратах сплитованных платежей
value	Сумма комиссии	Number	При возвратах сплитованных платежей
currency	Буквенный код валюты комиссии по ISO	String(3)	При возвратах сплитованных платежей
orderId	Номер заказа	String	При возвратах сплитованных платежей
comment	Комментарий к заказу	String	При возвратах сплитованных платежей
type	Тип уведомления — только REFUND	String(200)	Всегда
version	Версия уведомлений	String	Всегда

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

Поле	Описание	Тип
checkPaymentMethod	Описание результата проверки карты	Object
checkOperationDate	Дата проверки карты	URL-закодированная строка ГГГГ-ММ-ДДTЧЧ:ММ:ССZ
requestUid	Идентификатор операции проверки карты	String
status	Статус проверки карты	String
isValidCard	Признак валидности карты для платежей	Bool
threeDsStatus	Информация о статусе дополнительной аутентификации при проверке карты. Возможные значения — PASSED (3-D Secure пройден), NOT_PASSED (3-D Secure не пройден), WITHOUT (3-D Secure не требовалось)	String
paymentMethod	Информация о средстве платежа	Object
type	Тип метода оплаты	String
maskedPan	Маскированный PAN карты	String
cardExpireDate	Срок действия карты	String
cardHolder	Имя держателя карты	String
cardInfo	Информация о карте.	Object
issuingCountry	Код страны эмитента	String(3)
issuingBank	Банк-эмитент	String
paymentSystem	Тип платежной системы	String
fundingSource	Тип карты	String
paymentSystemProduct	Категория карты	String
createdToken	Объект с информацией о выпущенном вместе с проверкой карты платежном токене	Object
token	Строка платежного токена	String
name	Маскированный PAN карты, для которой выпущен платежный токен	String
expiredDate	Дата окончания срока действия платежного токена. Формат даты соответствует стандарту ISO-8601: YYYY-MM-DDThh:mm:ss±hh:mm	String
account	Идентификатор покупателя, указанный при выпуске платежного токена	String
type	Тип уведомления — только CHECK_CARD	String(200)
version	Версия уведомлений	String

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

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

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

Поле	Описание	Тип	В каких случаях используется
payout	Описание выплаты	Object	Всегда
payoutId	Уникальный идентификатор выплаты в системе ТСП	String(200)	Всегда
createdDateTime	Дата создания операции	URL-закодированная строка ГГГГ-ММ-ДДTЧЧ:ММ:ССZ	Всегда
amount	Информация о сумме операции	Object	Всегда
value	Сумма операции, округленная до двух десятичных знаков в меньшую сторону	Number(6.2)	Всегда
currency	Идентификатор валюты операции (Alpha-3 ISO 4217 код)	String(3)	Всегда
status	Информация о статусе операции	Object	Всегда
value	Строковое значение статуса	String	Всегда
changedDateTime	Дата обновления статуса	URL-закодированная строка ГГГГ-ММ-ДДTЧЧ:ММ:ССZ	Всегда
reasonCode	Код причины отклонения	String(200)	В случае отклонения операции
reasonMessage	Описание причины отклонения	String(200)	В случае отклонения операции
errorCode	Код ошибки	Number	В случае ошибки
receiverData	Информация о получателе	Object	Всегда
type	Тип метода выплаты: CARD — банковская карта	String	Всегда
maskedPan	Маскированный номер банковской карты	String	При выплате на карту
flags	Дополнительные флаги операции	Массив. Возможные элементы — TEST	При необходимости
type	Тип уведомления — только PAYOUT	String(200)	Всегда
version	Версия уведомлений	String	Всегда

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

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

• Возвраты доступны только для успешно завершенных операций платежа.
• Отмена операции возможна только при двухшаговом сценарии платежа и только для операций, по которым ещё не было подтверждения (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	Array	Массив данных о поставщиках
type	String	Тип передаваемых данных. Доступные значения: MERCHANT_DETAILS (данные поставщика)
siteUid	String	Зарегистрированный ID поставщика
splitAmount	Object	Возмещение поставщику
value	Number	Сумма возмещения, округленная в меньшую сторону до 2 десятичных знаков
currency	String(3)	Буквенный код валюты возмещения по ISO. Доступен только RUB
orderId	String	Номер заказа (необязательный)
comment	String	Комментарий к заказу (необязательный)

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

Поле ответа	Тип	Описание
splits	Array	Массив с данными о сплитованных платежах
type	String	Тип передаваемых данных. Всегда возвращается строка MERCHANT_DETAILS
siteUid	String	Зарегистрированный ID поставщика
splitAmount	Object	Данные о возмещении поставщику
value	String	Сумма возмещения
currency	String(3)	Буквенный код валюты возмещения по ISO
orderId	String	Номер заказа
comment	String	Комментарий к заказу

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

Чтобы отправить платеж со сплитованием, передайте в запросе API Платеж JSON-массив paymentSplits с данными поставщиков.

Описание данных

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

{
 "paymentMethod": "...",
 "customer": "....",
 "deviceData": "...",
 "paymentSplits": [
   {
     "type":"MERCHANT_DETAILS",
     "siteUid":"shop_mst-01",
     "splitAmount": {
       "value":300.00,
       "currency":"RUB"
     },
     "orderId":"dasdad444ll4ll",
     "comment":"Цветы"
  },
  {
    "type":"MERCHANT_DETAILS",
    "siteUid":"shop_mst-02",
    "splitAmount": {
      "value":200.00,
      "currency":"RUB"
      },
      "orderId":"sdadada887sdDDDDd",
      "comment":"Фрукты"
    }
  ]
}

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

{
  "paymentId": "23",
  "billId": "autogenerated-2a8fcfab-45cb-43b9-81bd-edf65e0ef874",
  "createdDateTime": "2020-10-12T15:29:12+03:00",
  "amount": {
    "currency": "RUB",
    "value": "100.00"
  },
  "capturedAmount": {
    "currency": "RUB",
    "value": "100.00"
  },
  "refundedAmount": {
    "currency": "RUB",
    "value": "0.00"
  },
  "paymentMethod": "..",
  "status": "..",
  "paymentCardInfo": "..",
  "paymentSplits": [
    {
      "type": "MERCHANT_DETAILS",
      "siteUid": "shop_mst-01",
      "splitAmount": {
        "currency": "RUB",
        "value": "30.00"
      },
      "splitCommissions": {
        "merchantCms": {
          "currency": "RUB",
          "value": "10.00"
        }
      },
      "orderId": "313fh1f23j13k1k",
      "comment": "Товар из корзины"
    },
    {
      "type": "MERCHANT_DETAILS",
      "siteUid": "shop_mst-02",
      "splitAmount": {
        "currency": "RUB",
        "value": "20.00"
      },
      "splitCommissions": {
        "merchantCms": {
          "currency": "RUB",
          "value": "10.00"
        }
      },
      "orderId": "sdadada887sdDDDDd",
      "comment": "Фрукты"
    },
    {
      "type": "MERCHANT_DETAILS",
      "siteUid": "shop_mst-03",
      "splitAmount": {
        "currency": "RUB",
        "value": "50.00"
      },
      "splitCommissions": {
        "merchantCms": {
          "currency": "RUB",
          "value": "10.00"
        }
      },
      "orderId": "dasdad444ll4ll",
      "comment": "Цветы"
    }
  ]
}

Описание массива paymentSplits:

Название	Тип	Описание
paymentSplits	Array	Массив данных о поставщиках
type	String	Тип передаваемых данных. Доступные значения: MERCHANT_DETAILS (данные поставщика)
siteUid	String	Зарегистрированный ID поставщика
splitAmount	Object	Возмещение поставщику
value	Number	Сумма возмещения, округленная в меньшую сторону до 2 десятичных знаков
currency	String(3)	Буквенный код валюты возмещения по ISO. Доступен только RUB
orderId	String	Номер заказа (необязательный)
comment	String	Комментарий к заказу (необязательный)

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

Поле ответа	Тип	Описание
paymentSplits	Array	Массив с данными о принятых платежах
type	String	Тип передаваемых данных. Всегда возвращается строка MERCHANT_DETAILS
siteUid	String	Зарегистрированный ID поставщика
splitAmount	Object	Данные о возмещении поставщику
value	String	Сумма возмещения
currency	String(3)	Буквенный код валюты возмещения по ISO
splitCommissions	Object	Данные о комиссии (необязательный)
merchantCms	Object	Данные о комиссии с поставщика
value	String	Сумма комиссии
currency	String(3)	Буквенный код валюты комиссии по ISO
orderId	String	Номер заказа
comment	String	Комментарий к заказу

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

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

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

PUT /partner/payin/v1/sites/test-01/payments/23/refunds/1 HTTP/1.1
Accept: application/json
Authorization: Bearer 5c4b25xx93aa435d9cb8cd17480356f9
Content-type: application/json
Host: api.qiwi.com

{
  "amount": {
    "value": 100.00,
    "currency": "RUB"
  },
  "refundSplits": [
  {
    "type": "MERCHANT_DETAILS",
    "siteUid": "shop_mst-01",
    "splitAmount": {
      "value": 30.00,
      "currency": "RUB"
    },
    "orderId": "sdadada887sdDDDDd",
    "comment": "Фрукты"
  },
  {
    "type": "MERCHANT_DETAILS",
    "siteUid": "shop_mst-02",
    "splitAmount": {
      "value": 20.00,
      "currency": "RUB"
    },
    "orderId": "313fh1f23j13k1k",
    "comment": "Товар из корзины"
  },
  {
    "type": "MERCHANT_DETAILS",
    "siteUid": "shop_mst-03",
    "splitAmount": {
      "value": 50.00,
      "currency": "RUB"
    },
    "orderId": "dasdad444ll4ll",
    "comment": "Цветы"
  }
  ]
}

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

{
    "refundId": "1",
    "createdDateTime": "2020-10-12T15:32:29+03:00",
    "amount": {
      "currency": "RUB",
      "value": "100.00"
    },
    "status": {
      "value": "COMPLETED",
      "changedDateTime": "2020-10-12T15:32:30+03:00"
    },
    "refundSplits": [
        {
            "type": "MERCHANT_DETAILS",
            "siteUid": "shop_mst-02",
            "splitAmount": {
                "currency": "RUB",
                "value": "20.00"
            },
            "splitCommissions": {
                "merchantCms": {
                    "currency": "RUB",
                    "value": "10.00"
                }
            },
            "orderId": "sdadada887sdDDDDd",
            "comment": "Фрукты"
        },
        {
            "type": "MERCHANT_DETAILS",
            "siteUid": "shop_mst-01",
            "splitAmount": {
                "currency": "RUB",
                "value": "30.00"
            },
            "splitCommissions": {
                "merchantCms": {
                    "currency": "RUB",
                    "value": "10.00"
                }
            },
            "orderId": "313fh1f23j13k1k",
            "comment": "Товар из корзины"
        },
        {
            "type": "MERCHANT_DETAILS",
            "siteUid": "shop_mst-03",
            "splitAmount": {
                "currency": "RUB",
                "value": "50.00"
            },
            "splitCommissions": {
                "merchantCms": {
                    "currency": "RUB",
                    "value": "10.00"
                }
            },
            "orderId": "dasdad444ll4ll",
            "comment": "Цветы"
        }
    ]
}

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

Описание массива refundSplits:

Название	Тип	Описание
refundSplits	Array	Массив данных о возвратах поставщикам
type	String	Тип передаваемых данных. Доступные значения: MERCHANT_DETAILS (данные поставщика)
siteUid	String	Зарегистрированный ID поставщика
splitAmount	Object	Информация об отмене возмещения поставщику
value	Number	Сумма отмены возмещения, округленная в меньшую сторону до 2 десятичных знаков
currency	String(3)	Буквенный код валюты отмены возмещения по ISO. Доступен только RUB
orderId	String	Номер заказа (необязательный)
comment	String	Комментарий к заказу (необязательный)

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

Поле ответа	Тип	Описание
refundSplits	Array	Массив данных о возвратах поставщикам
type	String	Тип передаваемых данных. Всегда возвращается строка MERCHANT_DETAILS
siteUid	String	Зарегистрированный ID поставщика
splitAmount	Object	Информация об отмене возмещения поставщику
value	String	Сумма отмены возмещения
currency	String(3)	Буквенный код валюты по ISO
splitCommissions	Object	Информация о комиссии (необязательный)
merchantCms	Object	Информация о комиссии с поставщика
value	String	Сумма комиссии
currency	String(3)	Буквенный код валюты комиссии по ISO
orderId	String	Номер заказа
comment	String	Комментарий к заказу

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

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

{
    "payment": {
        "paymentId": "134d707d-fec4-4a84-93f3-781b4f8c24ac",
        "customFields": {
            "comment": "Мой комментарий"
        },
        "paymentCardInfo": {
            "issuingCountry": "643",
            "issuingBank": "Unknown",
            "paymentSystem": "VISA",
            "fundingSource": "UNKNOWN",
            "paymentSystemProduct": "Unknown"
        },
        "type": "PAYMENT",
        "createdDateTime": "2021-02-05T11:29:38+03:00",
        "status": {
            "value": "SUCCESS",
            "changedDateTime": "2021-02-05T11:29:39+03:00"
        },
        "amount": {
            "value": 3,
            "currency": "RUB"
        },
        "paymentMethod": {
            "type": "TOKEN",
            "paymentToken": "1620161e-d498-431b-b006-c52bb78c6bf2",
            "maskedPan": "425600******0003",
            "cardHolder": "CARD HOLDER",
            "cardExpireDate": "11/2022"
        },
        "customer": {
            "email": "glmgmmxr@qiwi123.com",
            "account": "sbderxuftsrt",
            "phone": "13387571067",
            "country": "yccsnnfjgthu",
            "city": "sqdvseezbpzo",
            "region": "shbvyjgspjvu"
        },
        "gatewayData": {
            "type": "ACQUIRING",
            "authCode": "181218",
            "rrn": "123"
        },
        "billId": "autogenerated-19cf2596-62a8-47f2-8721-b8791e9598d0",
        "flags": [],
        "paymentSplits": [
            {
                "type": "MERCHANT_DETAILS",
                "siteUid": "Obuc-00",
                "splitAmount": {
                    "value": 2,
                    "currency": "RUB"
                },
                "splitCommissions": {
                    "merchantCms": {
                        "value": 0.2,
                        "currency": "RUB"
                    },
                    "userCms": null
                },
                "orderId": "dressesforwhite",
                "comment": "Платье"
            },
            {
                "type": "MERCHANT_DETAILS",
                "siteUid": "Obuc-01",
                "splitAmount": {
                    "value": 1,
                    "currency": "RUB"
                },
                "splitCommissions": {
                    "merchantCms": {
                        "value": 0.02,
                        "currency": "RUB"
                    },
                    "userCms": null
                },
                "orderId": "shoesforvalya",
                "comment": "Туфли"
            }
        ]
    },
    "type": "PAYMENT",
    "version": "1"
}

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

{
    "refund": {
        "refundId": "42f5ca91-965e-4cd0-bb30-3b64d9284048",
        "type": "REFUND",
        "createdDateTime": "2021-02-05T11:31:40+03:00",
        "status": {
            "value": "SUCCESS",
            "changedDateTime": "2021-02-05T11:31:40+03:00"
        },
        "amount": {
            "value": 3,
            "currency": "RUB"
        },
        "paymentMethod": {
            "type": "TOKEN",
            "paymentToken": "1620161e-d498-431b-b006-c52bb78c6bf2",
            "maskedPan": null,
            "cardHolder": null,
            "cardExpireDate": null
        },
        "customer": {
            "email": "glmgmmxr@qiwi123.com",
            "account": "sbderxuftsrt",
            "phone": "13387571067",
            "country": "yccsnnfjgthu",
            "city": "sqdvseezbpzo",
            "region": "shbvyjgspjvu"
        },
        "gatewayData": {
            "type": "ACQUIRING",
            "authCode": "181218",
            "rrn": "123"
        },
        "billId": "autogenerated-19cf2596-62a8-47f2-8721-b8791e9598d0",
        "flags": [
            "REVERSAL"
        ],
        "refundSplits": [
            {
                "type": "MERCHANT_DETAILS",
                "siteUid": "Obuc-00",
                "splitAmount": {
                    "value": 2,
                    "currency": "RUB"
                },
                "splitCommissions": {
                    "merchantCms": {
                        "value": 0,
                        "currency": "RUB"
                    },
                    "userCms": null
                },
                "orderId": "dressesforwhite",
                "comment": "Покупка 1"
            },
            {
                "type": "MERCHANT_DETAILS",
                "siteUid": "Obuc-01",
                "splitAmount": {
                    "value": 1,
                    "currency": "RUB"
                },
                "splitCommissions": {
                    "merchantCms": {
                        "value": 0.02,
                        "currency": "RUB"
                    },
                    "userCms": null
                },
                "orderId": "shoesforvalya",
                "comment": "Покупка 2"
            }
        ]
    },
    "type": "REFUND",
    "version": "1"
}

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

• В тело уведомления с типом PAYMENT добавляется JSON-массив paymentSplits, используемый для передачи данных о платежах поставщиков. Формат массива см. выше.
• В тело уведомления с типом REFUND добавляется JSON-массив refundSplits, используемый для передачи информации о возвратах поставщикам. Формат массива см. выше.

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

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

Особенности

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

Выпуск платежного токена карты

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

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

{
   "amount": {
     "currency": "RUB",
     "value": 10.00
   },
   "expirationDateTime": "2021-04-13T14:30:00+03:00",
    "customer": {
      "account":"token32"
   },
   "customFields": {},
   "flags":["BIND_PAYMENT_TOKEN"]
}

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

PUT /partner/payin/v1/sites/test-01/payments/test-022 HTTP/1.1
Accept: application/json
Authorization: Bearer 5c4b25xx93aa435d9cb8cd17480356f9
Content-type: application/json
Host: api.qiwi.com

{
   "amount": {
     "currency": "RUB",
     "value": 2211.24
   },
   "customer": {
     "account": "token324",
     "phone": "79022222222"
   },
   "flags":["BIND_PAYMENT_TOKEN"]
}

Пример тела ответа с платежным токеном

{
    "paymentId": "test-022",
    "billId": "autogenerated-c4479bb1-c916-4fba-8445-802592fa8d51",
    "createdDateTime": "2020-03-26T12:22:12+03:00",
    "amount": {
        "currency": "RUB",
        "value": 2211.24
    },
    "capturedAmount": "..",
    "refundedAmount": "..",
    "paymentMethod": "..",
    "createdToken": {
        "token": "66aebf5f-098e-4e36-922a-a4107b349a96",
        "name": "411111******1111"
    },
    "customer": {
        "account": "token324",
        "phone": "79022222222"
    },
    "status": ".."
}

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

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

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

1. Запрос инициации выпуска платежного токена QIWI Кошелька.

   Отправьте POST-запрос на URL:

   /payin-tokenization-api/v1/sites/{siteId}/token-requests

   где {siteId} — идентификатор siteId мерчанта.

   В JSON-теле запроса укажите параметры:

   • requestId — уникальный идентификатор запроса (от 1 до 36 символов). Уникальность означает, что идентификатор должен отличаться от идентификаторов всех ранее созданных запросов ТСП на выпуск платежного токена QIWI кошелька в рамках одного siteId.
   • phone — номер QIWI кошелька покупателя.
   • accountId — уникальный идентификатор покупателя в системе ТСП.

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

2. После этого на телефон покупателя придет SMS с одноразовым кодом. Укажите его в запросе завершения выпуска платежного токена QIWI Кошелька.

   Отправьте POST-запрос на URL:

   /payin-tokenization-api/v1/sites/{siteId}/token-requests/complete

   где {siteId} — идентификатор siteId мерчанта.

   В JSON-теле запроса укажите параметры:

   • requestId — идентификатор из начального запроса инициации выпуска платежного токена.
   • smsCode — код из SMS, отправленный покупателю.

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

• token.value — строка платежного токена;
• token.expiredDate — срок действия платежного токена, в формате YYYY-MM-DDThh:mm:ss+DMZ.

Удаление платежного токена

Удаление платежного токена

DELETE /partner/payin/v1/sites/test-01/tokens HTTP/1.1
Accept: application/json
Authorization: Bearer 5c4b25xx93aa435d9cb8cd17480356f9
Content-type: application/json
Host: api.qiwi.com

{
   "token": "66aebf5f-098e-4e36-922a-a4107b349a96",
   "customerAccountId": "token324"
}

Чтобы прекратить действие платежного токена, отправьте запрос DELETE:

/partner/payin/v1/sites/{siteId}/tokens

В JSON-теле запроса укажите параметры:

• customerAccountId — уникальный идентификатор покупателя в вашей системе, привязанный к платежному токену.
• token — платежный токен.

Успешный ответ означает, что платежный токен для указанного покупателя больше не действует.

Этот метод действует как для платежного токена карты, так и для платежного токена QIWI Кошелька.

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

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

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

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

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

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

PUT /partner/payin/v1/sites/site-01/bills/892323232111 HTTP/1.1
Accept: application/json
Authorization: Bearer 5c4b25xx93aa435d9cb8cd1xxxx356f9
Content-type: application/json
Host: api.qiwi.com

{
    "expirationDateTime": "2023-09-14T14:30:00+03:00",
    "customer": {
        "account":"test-123"
    },
    "flags": ["CHECK_CARD","BIND_PAYMENT_TOKEN"]
}

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

{
    "siteId": "site-01",
    "billId": "892323232111",
    "amount": {
      "value": "0.00",
      "currency": "RUB"
    },
    "status": {
      "value": "CREATED",
      "changedDateTime": "2021-08-13T15:43:41"
    },
    "creationDateTime": "2021-08-13T15:43:41",
    "expirationDateTime": "2023-09-14T14:30:00",
    "payUrl": "https://oplata.qiwi.com/validation/card?invoiceUid=fxxxxx-854c-4e56-xxxx-eb49aef2xxxx"
}

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

{
   "checkPaymentMethod":{
      "status":"SUCCESS",
      "isValidCard":true,
      "threeDsStatus":"WITHOUT",
      "cardInfo":{
         "issuingCountry":"0",
         "issuingBank":"not present",
         "paymentSystem":"VISA",
         "fundingSource":"UNKNOWN",
         "paymentSystemProduct":"UNKNOWN"
      },
      "createdToken":{
         "token":"xxxxxxx-a53a-4de1-8aa4-xxxxxxx",
         "name":"411111******1111",
         "expiredDate":"2021-11-30T00:00:00+03:00",
         "account":"some_account"
      },
      "requestUid":"892323232111",
      "paymentMethod":{
         "type":"CARD",
         "maskedPan":"411111******1111",
         "cardHolder":"",
         "cardExpireDate":"11/2021"
      },
      "checkOperationDate":"2021-08-13T15:44:01+03:00"
   },
   "type":"CHECK_CARD",
   "version":"1"
}

1. Отправьте запрос создания счета с дополнительным параметром "flags":["CHECK_CARD", "BIND_PAYMENT_TOKEN"]. Для генерации платежного токена в запросе должен быть указан параметр customer.account — уникальный идентификатор покупателя в системе ТСП. Не указывайте сумму счета (параметр amount).
2. Извлеките из ответа параметр billId — он понадобится в п.4. Перенаправьте покупателя на Платежную форму — ссылка на нее находится в параметре payUrl ответа.

3. На Платежной форме покупатель указывает реквизиты карты и отправляет их на проверку. На форме выполняется аутентификация покупателя (3-D Secure).
   

4. Дождитесь завершения проверки карты: вам придет уведомление CHECK_CARD с результатом, или запросите текущий статус проверки — в качестве уникального идентификатора проверки карты укажите billId из п.1. Результат проверки:

   • Информация о доступности карты для списаний — в атрибуте isValidCard (true — номер карты валиден).
   • Данные платежного токена — в объекте createdToken.

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

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

PUT /partner/payin/v1/sites/site-01/validation/card/requests/acd7bf20-22e2-4cbf-a218-38d90e9f29b9 HTTP/1.1
Accept: application/json
Authorization: Bearer 5c4b25xx93aa435d9cb8cd17480356f9
Content-type: application/json
Host: api.qiwi.com

{
    "cardData": {
        "pan": "1111222233334444",
        "expiryDate": "12/34",
        "cvv2": "123",
        "holderName": "Super Man"
    },
    "tokenizationData": {
        "account": "cat_girl"
    }
}

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

{
    "requestUid": "acd7bf20-22e2-4cbf-a218-38d90e9f29b9",
    "status": "SUCCESS",
    "isValidCard": true,
    "threeDsStatus": "WITHOUT",
    "checkOperationDate": "2021-07-29T16:30:00+03:00",
    "cardInfo": {
        "issuingCountry": "RUS",
        "issuingBank": "Qiwi bank",
        "paymentSystem": "VISA",
        "fundingSource": "DEBIT",
        "paymentSystemProduct": "Platinum..."
    },
    "createdToken": {
        "token": "1a77343a-dd8a-11eb-ba80-0242ac130004",
        "name": "111122******4444",
        "expiredDate": "2034-12-01T00:00:00+03:00",
        "account": "cat_girl"
    }
}

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

{
    "requestUid": "acd7bf20-22e2-4cbf-a218-38d90e9f29b9",
    "status": "WAITING_3DS",
    "requirements": {
        "pareq": "Some string pareq",
        "acsUrl": "http://xxxxxxx"
    }
}

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

{
    "requestUid": "acd7bf20-22e2-4cbf-a218-38d90e9f29b9",
    "status": "ERROR"
}

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

POST /partner/payin/v1/sites/site-01/validation/card/requests/acd7bf20-22e2-4cbf-a218-38d90e9f29b9/complete HTTP/1.1
Accept: application/json
Authorization: Bearer 5c4b25xx93aa435d9cb8cd17480356f9
Content-type: application/json
Host: api.qiwi.com

{
    "pares": "Some string pares"
}

Пример тела ответа

{
    "requestUid": "acd7bf20-22e2-4cbf-a218-38d90e9f29b9",
    "status": "SUCCESS",
    "isValidCard": true,
    "threeDsStatus": "PASSED",
    "checkOperationDate": "2021-07-29T16:30:00+03:00",
    "cardInfo": {
        "issuingCountry": "RUS",
        "issuingBank": "Qiwi bank",
        "paymentSystem": "VISA",
        "fundingSource": "DEBIT",
        "paymentSystemProduct": "Platinum..."
    },
    "createdToken": {
        "token": "1a77343a-dd8a-11eb-ba80-0242ac130004",
        "name": "111122******4444",
        "expiredDate": "2034-12-01T00:00:00+03:00",
        "account": "cat_girl"
    }
}

1. Отправьте запрос API «Проверка карты». В запросе укажите:
   • Уникальный в рамках вашего сайта идентификатор проверки (requestUid в URL запроса).
   • Данные карты (cardData в теле запроса). Обязательные параметры — PAN, срок действия и CVV2.

   Для генерации платежного токена в запросе должен быть указан параметр tokenizationData.account — уникальный идентификатор покупателя в системе ТСП.

2. В ответе информация о доступности карты для списаний содержится в атрибуте isValidCard (true — номер карты валиден). Данные платежного токена возвращаются в объекте createdToken.

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

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

1. Перенаправьте покупателя на страницу аутентификации.
2. Завершите 3-D Secure запросом «Завершение 3DS при проверке карты». В запросе укажите тот же идентификатор проверки, что и в исходном запросе проверки карты.
3. Если проверка 3-D Secure завершилась успешно, в ответе информация о доступности карты для списаний содержится в атрибуте isValidCard (true — номер карты валиден). Данные платежного токена возвращаются в объекте createdToken.

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

Статусы проверки карты

Статус	Описание
INIT	Сгенерирована ссылка на проверку карты, но клиент еще ей не воспользовался
SUCCESS	Проверка выполнена успешно
ERROR	Ошибка во время проверки
WAITING_3DS	Ожидание завершения проверки 3-D Secure

Безопасная сделка

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

Алгоритм безопасной сделки состоит из двух этапов:

• 1-ый этап — списание денежных средств с покупателя.

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

• 2-ой этап — выплата денежных средств поставщику.

  Выплата производится с помощью API Выплат.

Акты

Акт по принятым платежам формируется ежемесячно во второй рабочий день месяца.

Скачать шаблон Акта

Акт сначала отправляется на email, указанный при регистрации в сервисе. После подтверждения со стороны партнера, уполномоченное лицо КИВИ Банка подписывает Акт в системе документооборота электронной подписью. Подписанный Акт отправляется на юридический адрес партнера.

Реестры

Реестр операций отправляется после 14:00 МСК по рабочим дням, содержит информацию только об успешных платежах, обработанных банком. Реестр полностью соответствует Акту.

Реестр отправляется на email, указанный при регистрации в сервисе, во вложенном в письме zip-архиве.

Формат реестра

Пример фрагмента реестра

BANK_DATA_DOC;BANK_VALUE_DOC;BANK_AGR_CODE;SUM_BANK;TRANS_DATE;TRANSACTION_ID;SUM;COMMISSION;USER_INFO;ID;MERCH;MERCH_SITE;PARENT_TRANSACTION_ID;BILL;PURPOSE;MERCHANT_SITE_NAME;PAYMENT_METHOD_TYPE;ММВБ;CLIENT_AMOUNT;CLIENT_CUR_CODE;SETTLEMENT_AMOUNT;PAYMENTDETAILS
27.08.2020;27.08.2020;3456144;-25676786,28;;;25676786,28;;;;;;;;SETTLEMENT;;;null;;;;
27.08.2020;27.08.2020;34562014;243767,27;26.08.2020 9:59;659720;2165,46;25;533669******4030;68860745;hthi;hthi-26;;autogenerated-67cd0dfb-ca5a-0baf-b0e0-735a880c0dac;Оплата;сайт;Bank card;null;2165,46;643;25664068,85;Перевод принятых денежных средств по Договору  от 2019-09-24 00:00:00. Комиссия  руб. НДС не облагается.
27.08.2020;27.08.2020;34562014;243767,27;26.08.2020 10:01;660540;1530;25;536809******4077;68860893;hthi;hthi-26;;autogenerated-90870507-acd9-0056-80f7-d050560fba09;Оплата;сайт;Bank card;null;1530;643;25664068,85;Перевод принятых денежных средств по Договору  от 2019-09-24 00:00:00. Комиссия  руб. НДС не облагается.
27.08.2020;27.08.2020;34562014;243767,27;26.08.2020 10:06;665760;3150;56,7;547007******4635;68861159;hthi;hthi-54;;autogenerated-8a30690b-8c0c-0808-a0bb-6c73cbfdf953;Оплата;сайт;Bank card;null;3150;643;25664068,85;Перевод принятых денежных средств по Договору  от 2019-09-24 00:00:00. Комиссия  руб. НДС не облагается.
27.08.2020;27.08.2020;34562014;243767,27;26.08.2020 

Файл реестра формируется в формате CSV.

Скачать пример реестра

Поле реестра	Описание
BANK_DATA_DOC	Дата документа, влияющего на баланс банковского счета, по этой дате составляется Акт в конце месяца
BANK_VALUE_DOC	Дата фактического изменения баланса счета в банке
BANK_AGR_CODE	Банковский код, уникальный номер документа
SUM_BANK	Сумма документа
TRANS_DATE	Дата создания операции
TRANSACTION_ID	Номер операции
SUM	Сумма операции
COMMISSION	Комиссия за проведение операции с мерчанта
USER_INFO	Маскированный номер карты или номер телефона ( в случае оплаты КИВИ кошельком)
ID	Номер операции paymentId на стороне мерчанта
MERCH	ID мерчанта
MERCH_SITE	siteId мерчанта
PARENT_TRANSACTION_ID	Для возвратов указывается номер исходной операции платежа
BILL	ID выставленного счета
PURPOSE	Тип проводки CHARGEBACK/ REVERT_CHARGEBACK/ Оплата/ Возврат/ OPERATION+/ OPERATION-/ SETTLEMENT
MERCHANT_SITE_NAME	URL сайта мерчанта
PAYMENT_METHOD_TYPE	Метод оплаты: Bank card/ QIWI_WALLET/ SBP
ММВБ	Курс ММВБ на момент оплаты для валютных операций
CLIENT_AMOUNT	Сумма списания с покупателя
CLIENT_CUR_CODE	Валюта списания с покупателя
SETTLEMENT_AMOUNT	Сумма платежного поручения, отправленного на расчетный счет партнера
PAYMENTDETAILS	Назначение платежного поручения, отправленного на расчетный счет партнера (Пример: Перевод принятых денежных средств по Договору **** от ***. *** НДС не облагается/облагается.)

Возмещение

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

КИВИ взимает комиссию за каждую подтвержденную операцию. Если отмена операции была произведена до подтверждения, комиссия не взимается. Если была произведена частичная отмена до подтверждения операции, комиссия будет пересчитана.

Статусы и типы операций, коды ошибок

Коды ошибок

Протокол приема платежей использует для запросов API следующие HTTP-коды ошибок:

Код ошибки	Описание
400	Bad Request — Ваш запрос некорректен (ошибка в данных или в формате запроса).
401	Unauthorized — Неправильный ключ доступа к API.
403	Forbidden — Доступ к API запрещен.
404	Not Found — Указанный ресурс не найден.
405	Method Not Allowed — Для создания платежа использовался неправильный метод.
406	Not Acceptable — Формат данных отличается от JSON.
410	Gone — Запрашиваемый ресурс удален.
429	Too Many Requests — Слишком много запросов.
500	Internal Server Error — Внутренняя ошибка сервиса. Если тело ответа пустое, повторите запрос с теми же параметрами. Если тело ответа не пустое, выполните запрос статуса платежа или статуса счета.
502	Bad Gateway — Нет связи с сервисом
503	Service Unavailable  — Сервер временно недоступен по техническим причинам, попробуйте позже.

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

Тип операции возвращается в поле {operation}.type уведомления.

Тип операции	Описание
PAYMENT	Платеж. В уведомлении может присутствовать поле flags: [ "SALE" ] (обычный платеж) или flags: [ "AUTH" ] (платеж с холдированием средств).
CAPTURE	Операция подтверждения.
REFUND	Операция возврата. В уведомлении может присутствовать поле flags: [ "REVERSAL" ]. Это значит, что финансовой операции (списания средств со счета покупателя) не было, комиссия по операции удержана не будет.
PAYOUT	Операция выплаты. В уведомлении может присутствовать поле flags: [ "TEST" ]. Это значит, что операция тестовая.

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

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

Ответы API

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

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

Тип операции	Статус операции	Описание статуса
PAYMENT	WAITING	Ожидание 3DS авторизации
PAYMENT	DECLINED	Запрос авторизации отклонен
PAYMENT	COMPLETED	Запрос авторизации успешно обработан
CAPTURE	DECLINE	Запрос подтверждения отклонен
CAPTURE	DECLINED	Запрос подтверждения отклонен. Возвращается в ответе API на запрос статуса
CAPTURE	COMPLETED	Запрос подтверждения успешно обработан
REFUND	DECLINE	Запрос возврата отклонен
REFUND	COMPLETED	Запрос возврата успешно обработан
PAYOUT	WAITING	Выплата принята в обработку
PAYOUT	DECLINED	Выплата отклонена
PAYOUT	COMPLETED	Выплата успешно проведена

Уведомления

В уведомлениях статус помещается в поле {operation}.status.value.

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

Тип операции	Статус операции	Описание статуса
PAYMENT	DECLINED	Запрос авторизации отклонен
PAYMENT	SUCCESS	Запрос авторизации успешно обработан
CAPTURE	DECLINE	Запрос подтверждения отклонен
CAPTURE	SUCCESS	Запрос подтверждения успешно обработан
REFUND	DECLINE	Запрос возврата отклонен
REFUND	SUCCESS	Запрос возврата успешно обработан
PAYOUT	WAITING	Выплата принята в обработку
PAYOUT	DECLINED	Выплата отклонена
PAYOUT	SUCCESS	Выплата успешно проведена

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

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

• в ответах на запросы — в поле status.reason;
• в уведомлениях — в поле status.reasonCode.

Ошибка API	Описание
INVALID_STATE	Некорректный статус транзакции
INVALID_AMOUNT	Некорректная сумма
INVALID_RECEIVER_DATA	Ошибка при передаче данных о получателе
DECLINED_BY_MPI	Отклонено MPI
DECLINED_BY_FRAUD	Отклонено fraud-мониторингом
REATTEMPT_NOT_PERMITTED	Повторный запрос авторизации запрещен на основании полученного ответа от Платежной системы
GATEWAY_INTEGRATION_ERROR	Ошибка взаимодействия с банком
GATEWAY_TECHNICAL_ERROR	Техническая ошибка на стороне банка
ACQUIRING_MPI_TECH_ERROR	Техническая ошибка при проведении 3DS аутентификации
ACQUIRING_GATEWAY_TECH_ERROR	Техническая ошибка
ACQUIRING_ACQUIRER_ERROR	Техническая ошибка
ACQUIRING_AUTH_TECHNICAL_ERROR	Ошибка при проведении авторизации средств
ACQUIRING_ISSUER_NOT_AVAILABLE	Ошибка эмитента. Банк-эмитент не доступен
ACQUIRING_SUSPECTED_FRAUD	Ошибка эмитента. Подозрение на мошенничество
ACQUIRING_LIMIT_EXCEEDED	Ошибка эмитента. Превышен один из лимитов
ACQUIRING_NOT_PERMITTED	Ошибка эмитента. Операция не разрешена
ACQUIRING_INCORRECT_CVV	Ошибка эмитента. Некорректный CVV
ACQUIRING_EXPIRED_CARD	Ошибка эмитента. Неверный срок действия карты
ACQUIRING_INVALID_CARD	Ошибка эмитента. Проверьте корректность введенных данных
ACQUIRING_INSUFFICIENT_FUNDS	Ошибка эмитента. Недостаточно средств
ACQUIRING_UNKNOWN	Неизвестная ошибка
BILL_ALREADY_PAID	Счет уже оплачен
PAYIN_PROCESSING_ERROR	Ошибка при проведении платежа
PAYMENT_EXPIRED_3DS	Не пройдена 3DS-аутентификация
QW_LIMIT_ERROR	Ошибка превышения лимита пользователя QIWI Кошелька
QW_IDENTIFICATION_ERROR	Пользователю необходимо пройти идентификацию в QIWI Кошельке
QW_AUTH_ERROR	Ошибка авторизации в QIWI Кошельке
QW_INSUFFICIENT_FUNDS	Недостаточно средств в QIWI Кошельке
QW_AMOUNT_ERROR	Недопустимая сумма платежа
QW_REGISTRATION_ERROR	Ошибка регистрации пользователя QIWI Кошелька
QW_AGENT_ERROR	Ошибка при пополнении QIWI Кошелька пользователя
QW_ACCOUNT_ERROR	QIWI Кошелек заблокирован
QW_IDENTIFICATION_STATUS_ERROR	Достигнут лимит платежей в QIWI Кошельке
QW_CURRENCY_ERROR	Валюта QIWI Кошелька не найдена
QW_PAYMENT_ERROR	Ошибка проведения платежа в QIWI Кошельке
QW_PROVIDER_ERROR	Провайдер QIWI Кошелька заблокирован
QW_SMS_CONFIRM_EXPIRED	Истекло время СМС-подтверждения платежа в QIWI Кошельке

Справочник методов API

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

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

PUT /partner/payin/v1/sites/site-01/bills/893794793973 HTTP/1.1
Accept: application/json
Authorization: Bearer 5c4b25xx93aa435d9cb8cd17480356f9
Content-type: application/json
Host: api.qiwi.com

{
   "amount": {
     "currency": "RUB",
     "value": 100.00
   },
   "billPaymentMethodsType": [
      "QIWI_WALLET",
      "SBP"
   ],
   "comment": "Text comment",
   "expirationDateTime": "2022-04-13T14:30:00+03:00",
   "customer": {},
   "customFields": {
     "cf1": "Some data"
   }
}

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

{
    "siteId": "23044",
    "billId": "893794793973",
    "invoiceUid": "d875277b-6f0f-445d-8a83-f62c7c07be77",
    "amount": {
      "value": "100.00",
      "currency": "RUB"
    },
    "status": {
      "value": "CREATED",
      "changedDateTime": "2022-04-05T11:27:41"
    },
    "comment": "Text comment",
    "customFields": {
      "cf1": "Some data"
    },
    "creationDateTime": "2022-03-05T11:27:41",
    "expirationDateTime": "2022-04-13T14:30:00",
    "payUrl": "https://oplata.qiwi.com/form/?invoice_uid=d875277b-6f0f-445d-8a83-f62c7c07be77"
}

Пример ответа с ошибкой 4xx на запрос создания счета

{
  "serviceName" : "payin-core",
  "errorCode" : "validation.error",
  "description" : "Validation error",
  "userMessage" : "Validation error",
  "dateTime" : "2022-03-05T11:49:59.166+03:00",
  "traceId" : "fd0e2a08c63ace83"
}

Статус счета

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

GET /partner/payin/v1/sites/site-01/bills/d35cf63943e54f50badc75f49a5aac7c/details HTTP/1.1
Accept: application/json
Authorization: Bearer 5c4b25xx93aa435d9cb8cd17480356f9
Content-type: application/json
Host: api.qiwi.com

Пример успешного ответа на запрос статуса счета { "billId": "d35cf63943e54f50badc75f49a5aac7c", "amount": { "value": "100.00", "currency": "RUB" }, "status": { "value": "PAID", "changedDateTime": "2022-03-05T11:27:41" }, "comment": "Text comment", "customFields": { "cf1": "Some data" }, "expirationDateTime": "2022-04-13T14:30:00", "payUrl": "https://oplata.qiwi.com/form/invoice_uid=d875277b-6f0f-445d-8a83-f62c7c07be77", "payments": [ { "siteId": "site-01", "billId": "d35cf63943e54f50badc75f49a5aac7c", "createdDateTime": "2022-03-05T11:23:22+03:00", "amount": { "currency": "RUB", "value": "100.00" }, "capturedAmount": { "currency": "RUB", "value": "100.00" }, "refundedAmount": { "currency": "RUB", "value": "0.00" }, "paymentMethod": { "type": "CARD", "maskedPan": "427638******1410" }, "customer": { "account": "1", "phone": "0", "address": {} }, "requirements": { "threeDS": { "pareq": "eJxVUWFvgjAQ52lBUtjD3M9++qFgCxl0i/OtJv2WT/tv8LXqG0vw==", "acsUrl": "https://ds1.mirconnect.ru:443/vbv/pareq" } }, "status": { "value": "DECLINED", "changedDateTime": "2022-03-05T11:23:54+03:00", "reason": "ACQUIRING_NOT_PERMITTED" }, "customFields": { "customer_account": "1", "customer_phone": "0" } }, { "siteId": "site-01", "billId": "d35cf63943e54f50badc75f49a5aac7c", "createdDateTime": "2022-03-05T11:26:21+03:00", "amount": { "currency": "RUB", "value": "100.00" }, "capturedAmount": { "currency": "RUB", "value": "100.00" }, "refundedAmount": { "currency": "RUB", "value": "0.00" }, "paymentMethod": { "type": "CARD", "maskedPan": "427638******1410" }, "customer": { "account": "1", "phone": "0", "address": {} }, "requirements": { "threeDS": { "pareq": "eJxVUdtuwjAM7b6t/1fcku04w==", "acsUrl": "https://ds1.mirconnect.ru:443/vbv/pareq" } }, "status": { "value": "COMPLETED", "changedDateTime": "2022-03-05T11:34:43+03:00" }, "customFields": { "customer_account": "1", "customer_phone": "0" } } ] } 

Пример ответа с ошибкой 4xx на запрос статуса счета { "serviceName" : "payin-core", "errorCode" : "validation.error", "description" : "Validation error", "userMessage" : "Validation error", "dateTime" : "2022-03-05T16:49:59.166+03:00", "traceId" : "fd0e2a08c63ace83" } 

Получение списка платежей по счету

Пример запроса на получение списка платежей по счету GET /partner/payin/v1/sites/site-01/bills/893794793973 HTTP/1.1 Accept: application/json Authorization: Bearer 5c4b25xx93aa435d9cb8cd17480356f9 Content-type: application/json Host: api.qiwi.com 

Пример успешного ответа на запрос списка платежей по счету [ { "paymentId": "824c7744-1650-4836-abaa-842ca7ca8a74", "billId": "191616216126154", "createdDateTime": "2022-07-27T12:43:35+03:00", "amount": { "currency": "RUB", "value": "1.00" }, "capturedAmount": { "currency": "RUB", "value": "0.00" }, "refundedAmount": { "currency": "RUB", "value": "0.00" }, "paymentMethod": { "type": "CARD", "maskedPan": "561251******6871", "rrn": "002612398011", "authCode": "067842" }, "createdToken": { "token": "cc2451a5-2fdd-4685-912e-8671597948a3", "name": "561251******6871", "expiredDate": "2030-03-01T00:00:00+03:00" }, "customer": { "account": "11235813", "email": "darta@mail.ru", "phone": "79850223243" }, "status": { "value": "COMPLETED", "changedDateTime": "2022-07-27T12:43:47+03:00" }, "callbackUrl": "https://qiwi.com", "comment": "test", "customFields": { "customer_email": "darta@mail.ru", "customer_account": "11235813", "customer_phone": "79850223243", "cf1": "1", "cf2": "dva", "cf3": "tri", "cf4": "4", "cf5": "5", "BIND_PAYMENT_TOKEN": "true", "themeCode": "customization_OK", }, "paymentCardInfo": { "issuingCountry": "643", "issuingBank": "Тинькофф банк", "paymentSystem": "MASTERCARD", "fundingSource": "UNKNOWN", "paymentSystemProduct": "TNW|TNW|Mastercard® NewWorld—ImmediateDebit|TNW|Mastercard New World-ImmediateDebit" } } ] 

Пример ответа с ошибкой 4xx на запрос получения списка платежей по счету { "serviceName" : "payin-core", "errorCode" : "validation.error", "description" : "Validation error", "userMessage" : "Validation error", "dateTime" : "2018-11-13T16:49:59.166+03:00", "traceId" : "fd0e2a08c63ace83" } 

Платеж

Пример запроса на платеж PUT /partner/payin/v1/sites/test-01/payments/1811 HTTP/1.1 Accept: application/json Authorization: Bearer 5c4b25xx93aa435d9cb8cd17480356f9 Content-type: application/json Host: api.qiwi.com { "billId": "string", "amount": { "currency": "RUB", "value": 200.00 }, "paymentMethod" : { "type" : "CARD", "pan" : "4444443616621049", "expiryDate" : "12/19", "cvv2" : "123", "holderName" : "CARDHOLDER NAME" }, "callbackUrl": "https://example.com/callbacks", "comment": "Example payment", "customer": { "account": "string", "address": { "city": "Moscow", "country": "Russian Federation", "details": "Severnoe chertanovo microdistrict 1a 1", "region": "Moscow city" }, "email": "customer@example.com", "phone": "+79991234567" }, "deviceData": { "datetime": "2017-09-03T14:30:00+03:00", "fingerprint": "TW96aWxsYS81LjAgKHBsYXRmb3JtOyBydjpnZWNrb3ZlcnNpb24p", "ip": "127.0.0.1", "screenResolution": "1280x1024", "timeOnPage": 1440, "userAgent": "Mozilla/5.0 (platform; rv:geckoversion) Gecko/geckotrail Firefox/firefoxversion" }, "customFields": { "cf1": "Some data" }, "flags": [ "SALE" ] } 

Пример успешного ответа на запрос платежа { "paymentId" : "223E", "createdDateTime" : "2018-11-01T17:10:31.284+03:00", "amount" : { "currency" : "RUB", "value" : "200.00" }, "capturedAmount" : { "currency" : "RUB", "value" : "0.00" }, "refundedAmount" : { "currency" : "RUB", "value" : "0.00" }, "paymentMethod" : { "type" : "CARD", "maskedPan" : "444444******1049" }, "customer" : { }, "deviceData" : { }, "requirements" : { "threeDS" : { "pareq" : "eJyrrgUAAXUA+Q==", "acsUrl" : "https://test.paymentgate.ru/acs/auth/start.do" } }, "status" : { "value" : "WAITING", "changedDateTime" : "2018-11-01T17:10:32.607+03:00" }, "paymentCardInfo": { "issuingCountry": "810", "issuingBank": "QiwiBank", "paymentSystem": "VISA", "fundingSource": "CREDIT", "paymentSystemProduct": "P|Visa Gold" }, "customFields" : { "cf1": "Some data" }, "flags" : [ ] } 

Пример ответа с ошибкой 4xx на запрос платежа { "serviceName":"payin-core", "errorCode":"validation.error", "description":"Validation error", "userMessage":"Validation error", "dateTime":"2022-11-13T16:49:59.166+03:00", "traceId":"fd0e2a08c63ace83", "cause":{ "paymentToken": [ "Exchange token error. Token disabled, please create new one" ] } } 

Пример ответа с ошибкой 5xx на запрос платежа { "serviceName":"payin-core", "errorCode":"internal.error", "userMessage":"Internal error", "description":"Internal error", "traceId":"3fb3420ee1795dcf", "dateTime":"2020-02-12T21:28:01.813+03:00" } 

Статус платежа

Пример запроса статуса платежа GET /partner/payin/v1/sites/test-01/payments/1811 HTTP/1.1 Accept: application/json Authorization: Bearer 5c4b25xx93aa435d9cb8cd17480356f9 Content-type: application/json Host: api.qiwi.com 

Пример успешного ответа на запрос статуса платежа { "paymentId" : "223E", "createdDateTime" : "2018-11-01T17:10:31.284+03:00", "amount" : { "currency" : "RUB", "value" : "200.00" }, "capturedAmount" : { "currency" : "RUB", "value" : "0.00" }, "refundedAmount" : { "currency" : "RUB", "value" : "0.00" }, "paymentMethod" : { "type" : "CARD", "maskedPan" : "444444******1049", "rrn": "124", "authCode": "182817", }, "customer" : { }, "deviceData" : { }, "requirements" : { "threeDS" : { "pareq" : "eJyrrgUAAXUA+Q==", "acsUrl" : "https://test.paymentgate.ru/acs/auth/start.do" } }, "status" : { "value" : "WAITING", "changedDateTime" : "2018-11-01T17:10:32.607+03:00" }, "customFields" : { }, "flags" : [ ] } 

Пример ответа с ошибкой 4xx на запрос статуса платежа { "serviceName":"payin-core", "errorCode":"validation.error", "description":"Validation error", "userMessage":"Validation error", "dateTime":"2022-11-13T16:49:59.166+03:00", "traceId":"fd0e2a08c63ace83", "cause":{ "paymentToken": [ "Exchange token error. Token disabled, please create new one" ] } } 

Пример ответа с ошибкой 5xx на запрос статуса платежа { "serviceName":"payin-core", "errorCode":"internal.error", "userMessage":"Internal error", "description":"Internal error", "traceId":"3fb3420ee1795dcf", "dateTime":"2020-02-12T21:28:01.813+03:00" } 

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

Пример запроса завершения аутентификации покупателя POST /partner/payin/v1/sites/test-01/payments/1811/complete HTTP/1.1 Accept: application/json Authorization: Bearer 5c4b25xx93aa435d9cb8cd17480356f9 Content-type: application/json Host: api.qiwi.com { "threeDS": { "pares": "eJzVWFevo9iyfu9fMZrzaM0QjWHk3tIiGptgooE3cgabYMKvv3jvTurTc3XOfbkaJMuL...." } } 

Пример успешного ответа на запрос завершения аутентификации покупателя { "paymentId" : "223E", "createdDateTime" : "2018-11-01T17:10:31.284+03:00", "amount" : { "currency" : "RUB", "value" : "200.00" }, "capturedAmount" : { "currency" : "RUB", "value" : "0.00" }, "refundedAmount" : { "currency" : "RUB", "value" : "0.00" }, "paymentMethod" : { "type" : "CARD", "maskedPan" : "444444******1049" }, "customer" : { }, "deviceData" : { }, "requirements" : { "threeDS" : { "pareq" : "eJyrrgUAAXUA+Q==", "acsUrl" : "https://test.paymentgate.ru/acs/auth/start.do" } }, "status" : { "value" : "COMPLETED", "changedDateTime" : "2018-11-01T17:10:32.607+03:00" }, "customFields" : { }, "flags" : [ ] } 

Пример ответа с ошибкой 4xx на запрос завершения аутентификации покупателя { "serviceName" : "payin-core", "errorCode" : "validation.error", "description" : "Validation error", "userMessage" : "Validation error", "dateTime" : "2018-11-13T16:49:59.166+03:00", "traceId" : "fd0e2a08c63ace83" } 

Пример ответа с ошибкой 5xx на запрос завершения аутентификации покупателя { "serviceName":"payin-core", "errorCode":"internal.error", "userMessage":"Internal error", "description":"Internal error", "traceId":"3fb3420ee1795dcf", "dateTime":"2020-02-12T21:28:01.813+03:00" } 

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

Пример запроса подтверждения платежа PUT /partner/payin/v1/sites/test-01/payments/1811/captures/bxwd8096 HTTP/1.1 Accept: application/json Authorization: Bearer 5c4b25xx93aa435d9cb8cd17480356f9 Content-type: application/json Host: api.qiwi.com { "callbackUrl": "https://example.com/callbacks", "comment": "Example capture" } 

Пример успешного ответа на запрос подтверждения платежа { "captureId": "bxwd8096", "createdDateTime": "2018-11-20T16:29:58.96+03:00", "amount": { "currency": "RUB", "value": "6.77" }, "status": { "value": "COMPLETED", "changedDateTime": "2018-11-20T16:29:58.963+03:00" } } 

Пример ответа с ошибкой 4xx на запрос подтверждения платежа { "serviceName" : "payin-core", "errorCode" : "validation.error", "description" : "Validation error", "userMessage" : "Validation error", "dateTime" : "2018-11-13T16:49:59.166+03:00", "traceId" : "fd0e2a08c63ace83" } 

Пример ответа с ошибкой 5xx на запрос подтверждения платежа { "serviceName":"payin-core", "errorCode":"internal.error", "userMessage":"Internal error", "description":"Internal error", "traceId":"3fb3420ee1795dcf", "dateTime":"2020-02-12T21:28:01.813+03:00" } 

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

Пример запроса статуса подтверждения GET /partner/payin/v1/sites/test-01/payments/1811/captures/bxwd8096 HTTP/1.1 Accept: application/json Authorization: Bearer 5c4b25xx93aa435d9cb8cd17480356f9 Content-type: application/json Host: api.qiwi.com 

Пример успешного ответа на запрос статуса подтверждения { "captureId": "bxwd8096", "createdDateTime": "2018-11-20T16:29:58.96+03:00", "amount": { "currency": "RUB", "value": "6.77" }, "status": { "value": "COMPLETED", "changedDateTime": "2018-11-20T16:29:58.963+03:00" } } 

Пример ответа с ошибкой 4xx на запрос статуса подтверждения { "serviceName" : "payin-core", "errorCode" : "validation.error", "description" : "Validation error", "userMessage" : "Validation error", "dateTime" : "2018-11-13T16:49:59.166+03:00", "traceId" : "fd0e2a08c63ace83" } 

Пример ответа с ошибкой 5xx на запрос статуса подтверждения { "serviceName":"payin-core", "errorCode":"internal.error", "userMessage":"Internal error", "description":"Internal error", "traceId":"3fb3420ee1795dcf", "dateTime":"2020-02-12T21:28:01.813+03:00" } 

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

Метод PUT

Пример запроса получения QR-кода СБП PUT /partner/payin/v1/sites/test-01/sbp/qrCodes/Test12 HTTP/1.1 Accept: application/json Authorization: Bearer 5c4b25xx93aa435d9cb8cd17480356f9 Content-type: application/json Host: api.qiwi.com { "amount": { "value": 1.00, "currency": "RUB" }, "qrCode": { "type": "DYNAMIC", "ttl": 60, "image": { "mediaType": "image/png", "width": 300, "height": 300 } }, "paymentPurpose": "Flower for my girlfriend", "redirectUrl": "http://example.com" } 

Пример успешного ответа на запрос получения QR-кода СБП { "qrCodeUid": "Test12", "amount": { "currency": "RUB", "value": "1.00" }, "qrCode": { "type": "DYNAMIC", "ttl": 60, "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" } 

Пример ответа с ошибкой 4xx на запрос получения QR-кода СБП { "serviceName" : "payin-core", "errorCode" : "validation.error", "description" : "Validation error", "userMessage" : "Validation error", "dateTime" : "2018-11-13T16:49:59.166+03:00", "traceId" : "fd0e2a08c63ace83" } 

Пример ответа с ошибкой 5xx на запрос получения QR-кода СБП { "serviceName":"payin-core", "errorCode":"internal.error", "userMessage":"Internal error", "description":"Internal error", "traceId":"3fb3420ee1795dcf", "dateTime":"2020-02-12T21:28:01.813+03:00" } 

Метод POST

Пример запроса получения QR-кода СБП POST /partner/payin/v1/sites/test-01/sbp/qrCodes HTTP/1.1 Accept: application/json Authorization: Bearer 5c4b25xx93aa435d9cb8cd17480356f9 Content-type: application/json Host: api.qiwi.com { "qrCodeUid": "Test12", "amount": { "value": 1.00, "currency": "RUB" }, "qrCode": { "type": "DYNAMIC", "ttl": 60, "image": { "mediaType": "image/png", "width": 300, "height": 300 } }, "paymentPurpose": "Flower for my girlfriend", "redirectUrl": "http://example.com" } 

Пример успешного ответа на запрос получения QR-кода СБП { "qrCodeUid": "Test12", "amount": { "currency": "RUB", "value": "1.00" }, "qrCode": { "type": "DYNAMIC", "ttl": 60, "image": { "mediaType": "image/png", "width": 300, "height": 300, "content": "iVBORw0KGgoAAAANSUhEUgAAASwAAAEsCAYAA" }, "payload": "https://qr.nspk.ru/AD10006M8KH234K782OQM0L13JI31LQD?type=02&bank=100000000009&sum=200&cur=RUB&crc=C63A", "status": "CREATED" }, "createdOn": "2022-08-11T20:10:32+03:00" } 

Пример ответа с ошибкой 4xx на запрос получения QR-кода СБП { "serviceName" : "payin-core", "errorCode" : "validation.error", "description" : "Validation error", "userMessage" : "Validation error", "dateTime" : "2018-11-13T16:49:59.166+03:00", "traceId" : "fd0e2a08c63ace83" } 

Пример ответа с ошибкой 5xx на запрос получения QR-кода СБП { "serviceName":"payin-core", "errorCode":"internal.error", "userMessage":"Internal error", "description":"Internal error", "traceId":"3fb3420ee1795dcf", "dateTime":"2020-02-12T21:28:01.813+03:00" } 

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

Пример запроса статуса QR-кода СБП GET /partner/payin/v1/sites/test-01/sbp/qrCodes/Test HTTP/1.1 Accept: application/json Authorization: Bearer 5c4b25xx93aa435d9cb8cd17480356f9 Content-type: application/json Host: api.qiwi.com 

Пример успешного ответа на запрос статуса QR-кода СБП { "qrCodeUid": "Test", "amount": { "currency": "RUB", "value": "1.00" }, "qrCode": { "type": "DYNAMIC", "ttl": 60, "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" } 

Пример ответа с ошибкой 4xx на запрос статуса QR-кода СБП { "serviceName" : "payin-core", "errorCode" : "validation.error", "description" : "Validation error", "userMessage" : "Validation error", "dateTime" : "2018-11-13T16:49:59.166+03:00", "traceId" : "fd0e2a08c63ace83" } 

Пример ответа с ошибкой 5xx на запрос статуса QR-кода СБП { "serviceName":"payin-core", "errorCode":"internal.error", "userMessage":"Internal error", "description":"Internal error", "traceId":"3fb3420ee1795dcf", "dateTime":"2020-02-12T21:28:01.813+03:00" } 

Платеж токеном СБП

Пример запроса платежа токеном СБП PUT /partner/payin/v1/sites/test-01/sbp/qrCodes/adghj17d1g8/payments/11212334csd HTTP/1.1 Accept: application/json Authorization: Bearer 5c4b25xx93aa435d9cb8cd17480356f9 Content-type: application/json Host: api.qiwi.com { "tokenizationAccount": "customer123", "token": "c5ba4a05-21c9-4a36-af7a-b709b4caa4d6" } 

Пример успешного ответа на запрос платежа токеном СБП { "qrCodeUid": "adghj17d1g8", "amount": { "value": "100.00", "currency": "RUB" }, "paymentPurpose": "Flower for my girlfriend", "redirectUrl": "http://someurl.com", "qrCode": { "type": "DYNAMIC", "ttl": 999, "status": "CREATED", "payload": "", "image": { "content": "Base64 string", "mediaType": "image/png", "width": 300, "height": 300 } }, "payment": { "paymentUid": "12s1s21", "paymentStatus": "WAITING", } } 

Пример ответа с ошибкой 4xx на запрос платежа токеном СБП { "serviceName" : "payin-core", "errorCode" : "validation.error", "description" : "Validation error", "userMessage" : "Validation error", "dateTime" : "2018-11-13T16:49:59.166+03:00", "traceId" : "fd0e2a08c63ace83" } 

Пример ответа с ошибкой 5xx на запрос платежа токеном СБП { "serviceName":"payin-core", "errorCode":"internal.error", "userMessage":"Internal error", "description":"Internal error", "traceId":"3fb3420ee1795dcf", "dateTime":"2020-02-12T21:28:01.813+03:00" } 

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

Пример запроса возврата по платежу PUT /partner/payin/v1/sites/test-01/payments/1811/refunds/tcwv3132 HTTP/1.1 Accept: application/json Authorization: Bearer 5c4b25xx93aa435d9cb8cd17480356f9 Content-type: application/json Host: api.qiwi.com { "amount": { "value": 2.34, "currency": "RUB" } } 

Пример успешного ответа на запрос возврата по платежу { "refundId": "tcwv3132", "createdDateTime": "2018-11-20T16:32:55.547+03:00", "amount": { "currency": "RUB", "value": "2.34" }, "status": { "value": "COMPLETED", "changedDateTime": "2018-11-20T16:32:55.55+03:00" }, "flags": [ "REVERSAL" ] } 

Пример ответа с ошибкой 4xx на запрос возврата { "serviceName" : "payin-core", "errorCode" : "validation.error", "description" : "Validation error", "userMessage" : "Validation error", "dateTime" : "2018-11-13T16:49:59.166+03:00", "traceId" : "fd0e2a08c63ace83" } 

Пример ответа с ошибкой 5xx на запрос возврата { "serviceName":"payin-core", "errorCode":"internal.error", "userMessage":"Internal error", "description":"Internal error", "traceId":"3fb3420ee1795dcf", "dateTime":"2020-02-12T21:28:01.813+03:00" } 

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

Пример запроса статуса возврата GET /partner/payin/v1/sites/test-01/payments/1811/refunds/tcwv3132 HTTP/1.1 Accept: application/json Authorization: Bearer 5c4b25xx93aa435d9cb8cd17480356f9 Content-type: application/json Host: api.qiwi.com 

Пример успешного ответа на запрос статуса возврата по платежу { "refundId": "tcwv3132", "createdDateTime": "2018-11-20T16:32:55.547+03:00", "amount": { "currency": "RUB", "value": "2.34" }, "status": { "value": "COMPLETED", "changedDateTime": "2018-11-20T16:32:55.55+03:00" }, "flags": [ "REVERSAL" ] } 

Пример ответа с ошибкой 4xx на запрос статуса возврата { "serviceName" : "payin-core", "errorCode" : "validation.error", "description" : "Validation error", "userMessage" : "Validation error", "dateTime" : "2018-11-13T16:49:59.166+03:00", "traceId" : "fd0e2a08c63ace83" } 

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

Пример запроса статуса всех возвратов по платежу GET /partner/payin/v1/sites/test-01/payments/1811/refunds HTTP/1.1 Accept: application/json Authorization: Bearer 5c4b25xx93aa435d9cb8cd17480356f9 Content-type: application/json Host: api.qiwi.com 

Пример успешного ответа на запрос статуса всех возвратов по платежу [ { "refundId": "tcwv3132", "createdDateTime": "2018-11-20T16:32:55.547+03:00", "amount": { "currency": "RUB", "value": "2.34" }, "status": { "value": "COMPLETED", "changedDateTime": "2018-11-20T16:32:55.55+03:00" }, "flags": [ "REVERSAL" ] } ] 

Пример ответа с ошибкой 4xx на запрос статуса всех возвратов по платежу { "serviceName" : "payin-core", "errorCode" : "validation.error", "description" : "Validation error", "userMessage" : "Validation error", "dateTime" : "2018-11-13T16:49:59.166+03:00", "traceId" : "fd0e2a08c63ace83" } 

Пример ответа с ошибкой 5xx на запрос статуса всех возвратов по платежу { "serviceName":"payin-core", "errorCode":"internal.error", "userMessage":"Internal error", "description":"Internal error", "traceId":"3fb3420ee1795dcf", "dateTime":"2020-02-12T21:28:01.813+03:00" } 

Отмена возврата

Пример запроса отмены возврата по платежу POST /partner/payin/v1/sites/test-01/payments/1811/refunds/tcwv3132/decline HTTP/1.1 Accept: application/json Authorization: Bearer 5c4b25xx93aa435d9cb8cd17480356f9 Content-type: application/json Host: api.qiwi.com 

Пример успешного ответа на запрос отмены возврата по платежу { "refundId": "tcwv3132", "createdDateTime": "2018-11-20T16:32:55.547+03:00", "amount": { "currency": "RUB", "value": "2.34" }, "status": { "value": "COMPLETED", "changedDateTime": "2018-11-20T16:32:55.55+03:00" }, "flags": [ "REVERSAL" ] } 

Пример ответа с ошибкой 4xx на запрос отмены возврата по платежу { "serviceName" : "payin-core", "errorCode" : "validation.error", "description" : "Validation error", "userMessage" : "Validation error", "dateTime" : "2018-11-13T16:49:59.166+03:00", "traceId" : "fd0e2a08c63ace83" } 

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

Пример запроса проверки карты GET /partner/payin/v1/sites/test-01/validation/card/requests/acd7bf20-22e2-4cbf-a218-38d90e9f29b9 HTTP/1.1 Accept: application/json Authorization: Bearer 5c4b25xx93aa435d9cb8cd17480356f9 Content-type: application/json Host: api.qiwi.com { "cardData": { "pan": "1111222233334444", "expiryDate": "12/34", "cvv2": "123", "holderName": "Super Man" }, "tokenizationData": { "account": "cat_girl" } } 

Пример успешного ответа на запрос проверки карты { "requestUid": "acd7bf20-22e2-4cbf-a218-38d90e9f29b9", "status": "SUCCESS", "isValidCard": true, "threeDsStatus": "WITHOUT", "checkOperationDate": "2021-07-29T16:30:00+03:00", "cardInfo": { "issuingCountry": "RUS", "issuingBank": "Qiwi bank", "paymentSystem": "VISA", "fundingSource": "DEBIT", "paymentSystemProduct": "Platinum..." }, "createdToken": { "token": "1a77343a-dd8a-11eb-ba80-0242ac130004", "name": "111122******4444", "expiredDate": "2034-12-01T00:00:00+03:00", "account": "cat_girl" } } 

Пример ответа с ошибкой 4xx на запрос проверки карты { "serviceName" : "payin-core", "errorCode" : "validation.error", "description" : "Validation error", "userMessage" : "Validation error", "dateTime" : "2018-11-13T16:49:59.166+03:00", "traceId" : "fd0e2a08c63ace83" } 

Пример ответа с ошибкой 5xx на запрос проверки карты { "serviceName":"payin-core", "errorCode":"internal.error", "userMessage":"Internal error", "description":"Internal error", "traceId":"3fb3420ee1795dcf", "dateTime":"2020-02-12T21:28:01.813+03:00" } 

Статус проверки карты

Пример запроса статуса проверки карты GET /partner/payin/v1/sites/test-01/validation/card/requests/acd7bf20-22e2-4cbf-a218-38d90e9f29b9 HTTP/1.1 Accept: application/json Authorization: Bearer 5c4b25xx93aa435d9cb8cd17480356f9 Content-type: application/json Host: api.qiwi.com 

Пример успешного ответа на запрос статуса проверки карты { "requestUid": "acd7bf20-22e2-4cbf-a218-38d90e9f29b9", "status": "SUCCESS", "isValidCard": true, "threeDsStatus": "WITHOUT", "checkOperationDate": "2021-07-29T16:30:00+03:00", "cardInfo": { "issuingCountry": "RUS", "issuingBank": "Qiwi bank", "paymentSystem": "VISA", "fundingSource": "DEBIT", "paymentSystemProduct": "Platinum..." }, "createdToken": { "token": "1a77343a-dd8a-11eb-ba80-0242ac130004", "name": "111122******4444", "expiredDate": "2034-12-01T00:00:00+03:00", "account": "cat_girl" } } 

Пример ответа с ошибкой 4xx на запрос статуса проверки карты { "serviceName" : "payin-core", "errorCode" : "validation.error", "description" : "Validation error", "userMessage" : "Validation error", "dateTime" : "2018-11-13T16:49:59.166+03:00", "traceId" : "fd0e2a08c63ace83" } 

Пример ответа с ошибкой 5xx на запрос статуса проверки карты { "serviceName":"payin-core", "errorCode":"internal.error", "userMessage":"Internal error", "description":"Internal error", "traceId":"3fb3420ee1795dcf", "dateTime":"2020-02-12T21:28:01.813+03:00" } 

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

Пример запроса завершения аутентификации при проверке карты POST /partner/payin/v1/sites/test-01/validation/card/requests/acd7bf20-22e2-4cbf-a218-38d90e9f29b9/complete HTTP/1.1 Accept: application/json Authorization: Bearer 5c4b25xx93aa435d9cb8cd17480356f9 Content-type: application/json Host: api.qiwi.com { "pares": "eJzVWFevo9iyfu9fMZrzaM0QjWHk3tIiGptgooE3cgabYMKvv3jvTurTc3XOfbkaJMuL...." } 

Пример успешного ответа на запрос завершения аутентификации при проверке карты { "requestUid": "acd7bf20-22e2-4cbf-a218-38d90e9f29b9", "status": "SUCCESS", "isValidCard": true, "threeDsStatus": "PASSED", "checkOperationDate": "2021-07-29T16:30:00+03:00", "cardInfo": { "issuingCountry": "RUS", "issuingBank": "Qiwi bank", "paymentSystem": "VISA", "fundingSource": "DEBIT", "paymentSystemProduct": "Platinum..." }, "createdToken": { "token": "1a77343a-dd8a-11eb-ba80-0242ac130004", "name": "111122******4444", "expiredDate": "2034-12-01T00:00:00+03:00", "account": "cat_girl" } } 

Пример ответа с ошибкой 4xx на запрос завершения аутентификации при проверке карты { "serviceName" : "payin-core", "errorCode" : "validation.error", "description" : "Validation error", "userMessage" : "Validation error", "dateTime" : "2018-11-13T16:49:59.166+03:00", "traceId" : "fd0e2a08c63ace83" } 

Пример ответа с ошибкой 5xx на запрос завершения аутентификации при проверке карты { "serviceName":"payin-core", "errorCode":"internal.error", "userMessage":"Internal error", "description":"Internal error", "traceId":"3fb3420ee1795dcf", "dateTime":"2020-02-12T21:28:01.813+03:00" } 

Выплата

Пример запроса на выплату PUT /partner/payin/v1/sites/test-01/payments/1811/payouts/bxwd8096 HTTP/1.1 Accept: application/json Authorization: Bearer 5c4b25xx93aa435d9cb8cd17480356f9 Content-type: application/json Host: api.qiwi.com X-Digital-Sign: BXXBmVDBZwwRW....XjU1ZSIfHCGw== { "amount" : { "value" : "40.00", "currency" : "RUB" }, "receiverData" : { "type" : "CARD", "pan" : "86003300000000000", "receiverFirstName" : "Ivan", "receiverLastName" : "Ivanov" }, "comment" : "some comment for payout operation", "callbackUrl" : "http://test.com/" } 

Пример успешного ответа на запрос выплаты { "createdDateTime": "2022-12-21T16:04:29+03:00", "status": { "value": "COMPLETED", "changedDateTime": "2022-12-21T16:14:12+03:00" }, "amount": { "currency": "RUB", "value": "40.00" }, "receiverData": { "type": "CARD", "maskedPan": "860033*******0000" }, "comment": "some comment for payout operation", "callbackUrl" : "http://test.com/", "flags": [ "TEST" ] } 

Пример ответа с ошибкой 4xx на запрос выплаты { "serviceName" : "payin-core", "errorCode" : "validation.error", "userMessage" : "Validation error", "description" : "Validation error", "traceId" : "4e8fc84f4706e422", "dateTime" : "2022-12-22T10:17:36.887215+03:00", "cause" : { "amount" : [ "Incorrect payout amount" ] } } 

Пример ответа с ошибкой 5xx на запрос выплаты { "serviceName":"payin-core", "errorCode":"internal.error", "userMessage":"Internal error", "description":"Internal error", "traceId":"3fb3420ee1795dcf", "dateTime":"2020-02-12T21:28:01.813+03:00" } 

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

Пример запроса статуса выплаты GET /partner/payin/v1/sites/test-01/payments/1811/payouts/bxwd8096 HTTP/1.1 Accept: application/json Authorization: Bearer 5c4b25xx93aa435d9cb8cd17480356f9 Content-type: application/json Host: api.qiwi.com 

Пример успешного ответа на запрос статуса выплаты { "createdDateTime": "2022-12-21T16:04:29+03:00", "status": { "value": "COMPLETED", "changedDateTime": "2022-12-21T16:14:12+03:00" }, "amount": { "currency": "RUB", "value": "40.00" }, "receiverData": { "type": "CARD", "maskedPan": "860033*******0000" }, "comment": "some comment for payout operation", "callbackUrl" : "http://test.com/", "flags": [ "TEST" ] } 

Пример ответа с ошибкой 4xx на запрос статуса выплаты { "serviceName" : "payin-core", "errorCode" : "validation.error", "userMessage" : "Validation error", "description" : "Validation error", "traceId" : "4e8fc84f4706e422", "dateTime" : "2022-12-22T10:17:36.887215+03:00", "cause" : { "amount" : [ "Incorrect payout amount" ] } } 

Пример ответа с ошибкой 5xx на запрос статуса выплаты { "serviceName":"payin-core", "errorCode":"internal.error", "userMessage":"Internal error", "description":"Internal error", "traceId":"3fb3420ee1795dcf", "dateTime":"2020-02-12T21:28:01.813+03:00" } 

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

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

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

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

• email ТСП для печати в чеке;
• полное название организации;
• реквизиты ОФД (название, ИНН, url);
• login и password для генерации токена;
• код группы.

Описание объекта cheque

{ .. "cheque":{ "sellerId": 3123011520, "customerContact": "Test customer contact", "chequeType": "COLLECT", "taxSystem": "OSN", "positions": [ { "quantity": 1, "price": { "value": 7.82, "currency": "RUB" }, "tax": "NDS_0", "paymentSubject": "PAYMENT", "paymentMethod": "FULL_PAYMENT", "description": "Test description" } ] } } 

Параметр	Тип данных	Описание
sellerId	decimal	Обязательный параметр. ИНН организации, для которой пробивается чек
chequeType	decimal	Обязательный параметр. Признак расчета (тэг 1054): COLLECT – Приход COLLECT_RETURN — Возврат прихода CONSUME — Расход CONSUME_RETURN -Возврат расхода
customerContact	string(64)	Обязательный параметр. Телефон или электронный адрес покупателя (тэг 1008)
taxSystem	decimal	Обязательный параметр. Система налогообложения (тэг 1055): OSN — Общая, ОСН USN – Упрощенная доход, УСН доход USN_MINUS_CONSUM – Упрощенная доход минус расход, УСН доход — расход ENVD – Единый налог на вмененный доход, ЕНВД ESN — Единый сельскохозяйственный налог, ЕСН PATENT – Патентная система налогообложения, Патент
positions	array	Обязательный параметр. Массив товаров
quantity	decimal	Обязательный параметр. Количество предмета расчета (тэг 1023)
price	decimal	Обязательный параметр. Цена за единицу предмета расчета с учетом скидок и наценок (тэг 1079)
tax	decimal	Обязательный параметр. Ставка НДС (тэг 1199): NDS_CALC_18_118 — с учетом НДС 18% (18/118) NDS_CALC_10_110 – с учетом НДС 10% (10/110) NDS_0 – ставка НДС 0% NO_NDS – НДС не облагается NDS_CALC_20_120 – с учетом НДС 20% (20/120) (20/120)
description	string(128)	Обязательный параметр. Наименование предмета расчета
paymentMethod	decimal	Обязательный параметр. Признак способа расчёта (тэг 1214): ADVANCED_FULL_PAYMENT – предоплата 100%. Полная предварительная оплата до момента передачи предмета расчета. PARTIAL_ADVANCE_PAYMENT – предоплата. Частичная предварительная оплата до момента передачи предмета расчета. ADVANCE – аванс. FULL_PAYMENT – полный расчет. Полная оплата, в том числе с учетом аванса (предварительной оплаты) в момент передачи предмета расчета. PARTIAL_PAYMENT – частичный расчет и кредит. Частичная оплата предмета расчета в момент его передачи с последующей оплатой в кредит. CREDIT – передача в кредит. Передача предмета расчета без его оплаты в момент его передачи с последующей оплатой в кредит. CREDIT_PAYMENT – оплата кредита. Оплата предмета расчета после его передачи с оплатой в кредит (оплата кредита).
paymentSubject	decimal	Обязательный параметр. Признак предмета расчёта (тэг 1212): COMMODITY – товар. О реализуемом товаре, за исключением подакцизного товара (наименование и иные сведения, описывающие товар). EXCISE_COMMODITY – подакцизный товар. О реализуемом подакцизном товаре (наименование и иные сведения, описывающие товар). WORK – работа. О выполняемой работе (наименование и иные сведения, описывающие работу). SERVICE – услуга. Об оказываемой услуге (наименование и иные сведения, описывающие услугу). GAMBLING_RATE – ставка азартной игры. О приеме ставок при осуществлении деятельности по проведению азартных игр. GAMBLING_PRIZE – выигрыш азартной игры. О выплате денежных средств в виде выигрыша при осуществлении деятельности по проведению азартных игр. LOTTERY_TICKET – лотерейный билет. О приеме денежных средств при реализации лотерейных билетов, электронных лотерейных билетов, приеме лотерейных ставок при осуществлении деятельности по проведению лотерей. LOTTERY_PRIZE – выигрыш лотереи. О выплате денежных средств в виде выигрыша при осуществлении деятельности по проведению лотерей. GRANTING_RESULTS_OF_INTELLECTUAL_ACTIVITY – предоставление результатов интеллектуальной деятельности. О предоставлении прав на использование результатов интеллектуальной деятельности или средств индивидуализации. PAYMENT – платеж. Об авансе, задатке, предоплате, кредите, взносе в счет оплаты, пени, штрафе, вознаграждении, бонусе и ином аналогичном предмете расчета. AGENCY_FEE – агентское вознаграждение. О вознаграждении пользователя, являющегося платежным агентом (субагентом), банковским платежным агентом (субагентом), комиссионером, поверенным или иным агентом. COMPAUND_PAYMENT_SUBJECT – составной предмет расчета. О предмете расчета, состоящем из предметов, каждому из которых может быть присвоено значение выше перечисленных признаков. OTHER_PAYMENT_SUBJECT – иной предмет расчета. О предмете расчета, не относящемуся к выше перечисленным предметам расчета.