Вопросы
bss@qiwi.com
NAV Navbar
Примеры

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

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

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

Термины и сокращения

Ключ доступа к 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 Платежная форма мерчанта
Банковская карта* ✓ ✓**
Оплата платежным токеном ✓ ✓
Yandex Pay × ✓
Mir Pay ✓ ✓
Оплата через СБП ✓ ✓
Оплата с баланса КИВИ Кошелька ✓ ✓***
Оплата с баланса мобильного телефона × ✓

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

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

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

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

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

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

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

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

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

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

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

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

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

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

Авторизация

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

curl -X PUT \
  https://api.qiwi.com/partner/v1/sites/{site_id}/payments/{payment_id} \
  --oauth2-bearer <Ключ API>

Пример заголовка авторизации

Authorization: Bearer 5c4b25xx93aa435d9cb8cd17480356f9

Для авторизации запросов к API используется стандарт OAuth 2.0 согласно RFC 6750. Указывайте значение ключа доступа к API в HTTP-заголовке Authorization как

Bearer <Ключ API>

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

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

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

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

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

    openssl genrsa -out private-key.pem 2048

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

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

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

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

    base64 -i public-key.pem

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

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

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

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

    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 API Протокола.

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

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

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

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

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

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

Месяц срока действия карты Результат
02 Операция проведена неуспешно
03 Операция проведена успешно, задержка — 3 секунды
04 Операция проведена неуспешно, задержка — 3 секунды
Все остальные значения Операция выполняется успешно

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

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

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

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

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

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

Оплата СБП

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

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

Выплаты

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

Значение поля amount.value Результат
200.00 или 2.00 На инициирующий запрос выплаты возвращается status.value=WAITING, на последующие запросы статуса выплаты возвращается status.value=SUCCESS
500.00 или 5.00 На запрос выплаты возвращается status.value=DECLINED
510.00 или 5.10 На инициирующий запрос выплаты возвращается status.value=WAITING, на последующие запросы статуса выплаты возвращается status.value=DECLINED

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

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

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

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

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

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

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

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

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

GET →

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

https://oplata.qiwi.com/create?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
Параметр ссылки Описание Тип
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/captures/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"
    },
    "merchantSiteUid": "test-00",
    "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:
  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. Если для покупателя был выпущен один или несколько платежных токенов, то на Платежной форме отобразится список его привязанных карт.

    qiwi-form-tokens

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

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

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

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

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

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

Пример передачи параметра стиля при выставлении счета через 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"
   }
}

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

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

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

Customer form

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

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

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

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 Платеж:

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

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

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

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

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 Платеж:

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

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

Для одношагового платежа без холдирования укажите в запросе 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 с полями:

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

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

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

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

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

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

{
  "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"
    },
    "merchantSiteUid":"test-00",
    "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/captures/bxwd8096 HTTP/1.1
Accept: application/json
Authorization: Bearer 5c4b25xx93aa435d9cb8cd17480356f9
Content-type: application/json
Host: api.qiwi.com

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

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

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

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

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

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

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

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

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

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:

Mir Pay

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

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

Сценарий оплаты:

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

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

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

{
  "paymentMethod": {
    "type": "CARD",
    "pan": "4444443616621049",
    "expiryDate": "12/19",
    "external3dSec": {
        "type": "MIR_PAY",
        "cav": "3D6FC826A08C82B89780029F69670FDDCF299B",
        "transId": "5ab52487-177f-464b-b695-2954ffc44a13",
        "mid": "000000000000001",
        "media": "DL",
    }
  },
  "amount": {
    "value": "5900.00",
    "currency": "RUB"
  },
  "flags": [
    "SALE"
  ],
  "customer": {
    "account": "79111111111",
    "email": "test@qiwi.com",
    "phone": "79111111111"
  }
}

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

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

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

{
  "paymentMethod": {
    "type" : "MIR_PAY_TOKEN",
    "cryptogram" : "eyJhbGciOiJSUzI1NiIsImN0eSI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwiaWF0IjoxNjAzMzc2MDExfQ.Ce16subvpzUm-xKTdInJ4Nxr75mzpDG2sFrjmdi02vvVmPhcYRju7ulVaZ0wLZqnjnM6XeXR6FZ473-cVMPAJ_O2wTr-EP6O2FnYUCzrrhQWCv5_4-Xk6QNSFD5bsHB8xTPYSsWilPvZuD5rhp80HpztJ0y95bZau8RQsJTVRPE"
  },
  "amount": {
    "value": 3300.00,
    "currency": "RUB"
  },
  "flags": [
    "SALE"
  ],
  "customer": {
    "account": "79111111111",
    "email": "test@qiwi.com",
    "phone": "79111111111"
  }
}

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

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

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

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

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

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

Оплата покупок со счета мобильного телефона происходит без ввода данных карты. Сразу после инициирования платежа покупатель получает 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 Платеж параметры:

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

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

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

{
  "payment": {
    ...
  },
  "type": "PAYMENT",
  "version": "1"
}

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

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

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

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

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

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

Для дополнительной уверенности следует принимать уведомления о платежах только от указанных диапазонов IP-адресов компании QIWI:

Уведомление считается успешно доставленным, если ваш сервер ответил 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
    • тип TOKEN: token.merchantSiteUid|token.account|token.status.value|token.status.changedDateTime
    • тип PAYOUT: payout.payoutId|payout.createdDateTime|payout.amount.value

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

    hash = HMAC(SHA256, secret, parameters)

    Где:

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

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

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

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

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

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

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

{
  "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"
    },
    "merchantSiteUid": "test-00",
    "customer": {
      "phone": "0",
      "bankAccountNumber": "4081710809561219555",
      "bic": "044525974",
      "lastName": "ИВАНОВ",
      "firstName": "ИВАН",
      "middleName": "ИВАНОВИЧ",
      "simpleAddress": "",
      "bankMemberId": "100000000008"
    },
    "billId": "autogenerated-6cd20922-b1d0-4e67-ba61-e2b7310c4006",
    "flags": [
      "SALE"
    ],
    "qrCodeUid": "acfd9"
  },
  "type": "PAYMENT",
  "version": "1"
}

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

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

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

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

{
  "capture": {
    "paymentId": "134d707d-fec4-4a84-93f3-781b4f8c24ac",
    "captureId": "B33180934426031511100733DG332XTQ1",
    "customFields": {},
    "type": "CAPTURE",
    "createdDateTime": "2022-08-06T11:34:42+03:00",
    "status": {
      "value": "SUCCESS",
      "changedDateTime": "2022-08-06T12:55:44+03:00"
    },
    "amount": {
      "value": 5,
      "currency": "RUB"
    },
    "paymentMethod": {
      "type": "CARD",
      "maskedPan": "54************47",
      "cardHolder": null,
      "cardExpireDate": "12/2024"
    },
    "merchantSiteUid": "test-00",
    "customer": {},
    "billId": "autogenerated-6cd20922-b1d0-4e67-ba61-e2b7310c4006",
    "flags": []
  },
  "type": "CAPTURE",
  "version": "1"
}
Поле Описание Тип  
capture Описание операции подтверждения Object  
capture.
type		 Тип операции — только CAPTURE String(200)  
capture.
paymentId		 Идентификатор платежа в системе ТСП String(200)  
capture.
captureId		 Идентификатор подтверждения в системе ТСП String(200)  
capture.
createdDateTime		 Дата создания операции URL-закодированная строка
ГГГГ-ММ-ДДTчч:мм:ссZ		  
capture.
amount		 Информация о сумме операции Object  
capture.
amount.
value		 Сумма операции, округленная до двух десятичных знаков в меньшую сторону Number(6.2)  
capture.
amount.
currency		 Идентификатор валюты операции (Alpha-3 ISO 4217 код) String(3)  
capture.
billId		 ID счета, соответствующего операции String(200)  
capture.
status		 Информация о статусе операции Object  
capture.
status.
value		 Строковое значение статуса String  
capture.
status.
changedDateTime		 Дата обновления статуса URL-закодированная строка
ГГГГ-ММ-ДДTчч:мм:ссZ		  
capture.
status.
reasonCode		 Код причины отклонения String(200)  
capture.
status.
reasonMessage		 Описание причины отклонения String(200)  
capture.
status.
errorCode		 Код ошибки Number  
capture.
paymentMethod		 Информация о средстве платежа Object  
capture.
paymentMethod.
type		 Тип метода оплаты String  
capture.
paymentMethod.
maskedPan		 Маскированный PAN карты String  
capture.
paymentMethod.
rrn		 RRN платежа (по ISO 8583) Number  
capture.
paymentMethod.
authCode		 Auth-code платежа Number  
capture.
merchantSiteUid		 Строковый идентификатор сайта ТСП в QIWI Кассе String  
capture.
customer		 Информация о покупателе Object  
capture.
customer.
phone		 Номер телефона покупателя String  
capture.
customer.
email		 E-mail покупателя String  
capture.
customer.
account		 Идентификатор покупателя в системе ТСП String  
capture.
customer.
ip		 IP адрес покупателя String  
capture.
customer.
country		 Страна адреса покупателя String  
capture.
customFields		 Поля с произвольной информацией, дополняющей данные по операции Object  
capture.
customFields.
cf1		 Поле с произвольной информацией, дополняющей данные по операции String(256)  
capture.
customFields.
cf2		 Поле с произвольной информацией, дополняющей данные по операции String(256)  
capture.
customFields.
cf3		 Поле с произвольной информацией, дополняющей данные по операции String(256)  
capture.
customFields.
cf4		 Поле с произвольной информацией, дополняющей данные по операции String(256)  
capture.
customFields.
cf5		 Поле с произвольной информацией, дополняющей данные по операции String(256)  
capture.
flags		 Дополнительные команды, переданные в API Array(Strings). Возможные элементы: SALE, REVERSAL  
capture.
settlementAmount		 Сведения о сумме расчёта с мерчантом Object Если валюта платежа и расчёта с мерчантом различаются
capture.
settlementAmount.
value		 Сумма расчёта с мерчантом Number(6.2) Если валюта платежа и расчёта с мерчантом различаются
capture.
settlementAmount.
currency		 Идентификатор валюты расчёта с мерчантом (Alpha-3 ISO 4217 код) String(3) Если валюта платежа и расчёта с мерчантом различаются
type Тип уведомления — только CAPTURE String  
version Версия уведомлений String  

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

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

{
    "refund": {
        "paymentId": "134d707d-fec4-4a84-93f3-781b4f8c24ac",
        "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
        },
        "merchantSiteUid": "test-00",
        "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"
}
Поле Описание Тип В каких случаях используется
refund Описание возврата Object Всегда
refund.
type		 Тип операции — только REFUND String(200) Всегда
refund.
paymentId		 Идентификатор платежа в системе ТСП String(200) Всегда
refund.
refundId		 Идентификатор возврата в системе ТСП String(200) Всегда
refund.
createdDateTime		 Дата создания операции URL-закодированная строка
ГГГГ-ММ-ДДTчч:мм:ссZ		 Всегда
refund.
amount		 Информация о сумме операции Object Всегда
refund.
amount.
value		 Сумма операции, округленная до двух десятичных знаков в меньшую сторону Number(6.2) Всегда
refund.
amount.
currency		 Идентификатор валюты операции (Alpha-3 ISO 4217 код) String(3) Всегда
refund.
billId		 ID счета, соответствующего операции String(200) Всегда
refund.
status		 Информация о статусе операции Object Всегда
refund.
status.
value		 Строковое значение статуса String Всегда
refund.
status.
changedDateTime		 Дата обновления статуса URL-закодированная строка
ГГГГ-ММ-ДДTчч:мм:ссZ		 Всегда
refund.
status.
reasonCode		 Код причины отклонения String(200) В случае отклонения операции
refund.
status.
reasonMessage		 Описание причины отклонения String(200) В случае отклонения операции
refund.
status.
errorCode		 Код ошибки Number В случае ошибки
refund.
paymentMethod		 Информация о средстве платежа Object Всегда
refund.
paymentMethod.
type		 Тип метода оплаты String Всегда
refund.
paymentMethod.
maskedPan		 Маскированный PAN карты String Всегда
refund.
paymentMethod.
rrn		 RRN платежа (по ISO 8583) Number Всегда
refund.
paymentMethod.
authCode		 Auth-code платежа Number Всегда
refund.
merchantSiteUid		 Строковый идентификатор сайта ТСП в QIWI Кассе String Всегда
refund.
customer		 Информация о покупателе Object Всегда
refund.
customer.
phone		 Номер телефона покупателя String Всегда
refund.
customer.
email		 E-mail покупателя String Всегда
refund.
customer.
account		 Идентификатор покупателя в системе ТСП String Всегда
refund.
customer.
ip		 IP адрес покупателя String Всегда
refund.
customer.
country		 Страна адреса покупателя String Всегда
refund.
customFields		 Поля с произвольной информацией, дополняющей данные по операции Object Всегда
refund.
customFields.
cf1		 Поле с произвольной информацией, дополняющей данные по операции String(256) Всегда
refund.
customFields.
cf2		 Поле с произвольной информацией, дополняющей данные по операции String(256) Всегда
refund.
customFields.
cf3		 Поле с произвольной информацией, дополняющей данные по операции String(256) Всегда
refund.
customFields.
cf4		 Поле с произвольной информацией, дополняющей данные по операции String(256) Всегда
refund.
customFields.
cf5		 Поле с произвольной информацией, дополняющей данные по операции String(256) Всегда
refund.
flags		 Дополнительные команды, переданные в API Array(Strings). Возможные элементы: SALE, REVERSAL Всегда
refund.
chequeData		 Описание фискального чека ChequeData Если в операции был отправлены данные для формирования фискального чека
refund.
refundSplits		 Описание возвратов по сплитованным платежам Array(Objects) При возвратах сплитованных платежей
refund.
refundSplits.
type		 Тип передаваемых данных. Всегда строка MERCHANT_DETAILS String При возвратах сплитованных платежей
refund.
refundSplits.
siteUid		 ID поставщика String При возвратах сплитованных платежей
refund.
refundSplits.
splitAmount		 Информация об отмене возмещения поставщику Object При возвратах сплитованных платежей
refund.
refundSplits.
splitAmount.
value		 Сумма отмены возмещения Number При возвратах сплитованных платежей
refund.
refundSplits.
splitAmount.
currency		 Буквенный код валюты отмены возмещения по ISO String(3) При возвратах сплитованных платежей
refund.
refundSplits.
splitCommissions		 Информация о комиссии Object При возвратах сплитованных платежей
refund.
refundSplits.
splitCommissions.
merchantCms		 Информация о комиссии с поставщика Object При возвратах сплитованных платежей
refund.
refundSplits.
splitCommissions.
merchantCms.
value		 Сумма комиссии Number При возвратах сплитованных платежей
refund.
refundSplits.
splitCommissions.
merchantCms.
currency		 Буквенный код валюты комиссии по ISO String(3) При возвратах сплитованных платежей
refund.
refundSplits.
orderId		 Номер заказа String При возвратах сплитованных платежей
refund.
refundSplits.
comment		 Комментарий к заказу String При возвратах сплитованных платежей
refund.
settlementAmount		 Сведения о сумме расчёта с мерчантом Object Если валюта платежа и расчёта с мерчантом различаются
refund.
settlementAmount.
value		 Сумма расчёта с мерчантом Number(6.2) Если валюта платежа и расчёта с мерчантом различаются
refund.
settlementAmount.
currency		 Идентификатор валюты расчёта с мерчантом (Alpha-3 ISO 4217 код) String(3) Если валюта платежа и расчёта с мерчантом различаются
type Тип уведомления — только REFUND String Всегда
version Версия уведомлений String Всегда

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

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

{
    "checkPaymentMethod": {
        "status": "SUCCESS",
        "isValidCard": true,
        "threeDsStatus": "PASSED",
        "cardInfo": {
            "issuingCountry": "RUS",
            "issuingBank": "Альфа-банк",
            "paymentSystem": "MASTERCARD",
            "fundingSource": "PREPAID",
            "paymentSystemProduct": "TNW|TNW|Mastercard® New World—Immediate Debit|TNW|Mastercard New World-Immediate Debit"
        },
        "createdToken": {
            "token": "7653465767c78-a979-5bae621db96f",
            "name": "54**********47",
            "expiredDate": "2022-12-30T00:00:00+03:00",
            "account": "acc1"
        },
        "requestUid": "uuid1-uuid2-uuid3-uuid4",
        "paymentMethod": {
            "type": "CARD",
            "maskedPan": "54************47",
            "cardHolder": null,
            "cardExpireDate": "12/2022"
        },
        "checkOperationDate": "2021-08-16T14:15:07+03:00",
        "merchantSiteUid": "test-00"
    },
    "type": "CHECK_CARD",
    "version": "1"
}
Поле Описание Тип
checkPaymentMethod Описание результата проверки карты Object
checkPaymentMethod.
checkOperationDate		 Дата проверки карты URL-закодированная строка
ГГГГ-ММ-ДДTчч:мм:ссZ
checkPaymentMethod.
requestUid		 Идентификатор операции проверки карты String
checkPaymentMethod.
status		 Статус проверки карты String
checkPaymentMethod.
isValidCard		 Признак доступности карты для платежей Bool
checkPaymentMethod.
threeDsStatus		 Информация о статусе дополнительной аутентификации при проверке карты. Возможные значения: PASSED (3-D Secure пройден), NOT_PASSED (3-D Secure не пройден), WITHOUT (3-D Secure не требовалось) String
checkPaymentMethod.
paymentMethod		 Информация о средстве платежа Object
checkPaymentMethod.
paymentMethod.
type		 Тип метода оплаты String
checkPaymentMethod.
paymentMethod.
maskedPan		 Маскированный PAN карты String
checkPaymentMethod.
paymentMethod.
cardExpireDate		 Срок действия карты String
checkPaymentMethod.
paymentMethod.
cardHolder		 Имя держателя карты String
checkPaymentMethod.
cardInfo		 Информация о карте Object
checkPaymentMethod.
cardInfo.
issuingCountry		 Код страны эмитента String(3)
checkPaymentMethod.
cardInfo.
issuingBank		 Банк-эмитент String
checkPaymentMethod.
cardInfo.
paymentSystem		 Тип платежной системы String
checkPaymentMethod.
cardInfo.
fundingSource		 Тип карты String
checkPaymentMethod.
cardInfo.
paymentSystemProduct		 Категория карты String
checkPaymentMethod.
createdToken		 Объект с информацией о платежном токене, выпущенном вместе с проверкой карты Object
checkPaymentMethod.
createdToken.
token		 Строка платежного токена String
checkPaymentMethod.
createdToken.
name		 Маскированный PAN карты, для которой выпущен платежный токен String
checkPaymentMethod.
createdToken.
expiredDate		 Дата окончания срока действия платежного токена. Формат даты соответствует стандарту ISO-8601:
ГГГГ-ММ-ДДTчч:мм:сс±чч:мм		 String
checkPaymentMethod.
createdToken.
account		 Идентификатор покупателя, указанный при выпуске платежного токена String
checkPaymentMethod.
merchantSiteUid		 Строковый идентификатор сайта ТСП в QIWI Кассе String
type Тип уведомления — только CHECK_CARD String
version Версия уведомлений String

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

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

{
  "token": {
    "status": {
      "value": "CREATED",
      "changedDateTime": "2023-01-01T10:00:00+03:00"
    },
    "merchantSiteUid": "test-00",
    "account": "test",
    "value": "d28a4ff8-548d-4536-927d-fc01123bebbf",
    "expiredDate": "2029-01-01T10:00:00+03:00",
    "tokenizationSource": {
      "type": "QR_CODE",
      "uid": "100220001"
    },
    "bankMemberId": "100000000008"
  },
  "type": "TOKEN",
  "version": "1"
}

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

{
  "token": {
    "status": {
      "value": "REJECTED",
      "changedDateTime": "2023-01-01T10:00:00+03:00"
    },
    "merchantSiteUid": "test-00",
    "account": "test",
    "tokenizationSource": {
      "type": "QR_CODE",
      "uid": "14012000011"
    }
  },
  "type": "TOKEN",
  "version": "1"
}
Поле Описание Тип В каких случаях используется
token Описание токена Object Всегда
token.
status		 Информация о статусе операции Object Всегда
token.
status.
value		 Строковое значение статуса String Всегда
token.
status.
changedDateTime		 Дата обновления статуса URL-закодированная строка
ГГГГ-ММ-ДДTчч:мм:ссZ		 Всегда
token.
status.
rejectReason		 Причина отклонения String В случае отклонения операции
token.
merchantSiteUid		 ID поставщика String Всегда
token.
account		 Идентификатор покупателя, указанный при выпуске платежного токена String Всегда
token.
value		 Платежный токен String В случае успешной операции
token.
expiredDate		 Дата окончания срока действия платежного токена. Формат даты соответствует стандарту ISO-8601: ГГГГ-ММ-ДДTчч:мм:сс±чч:мм String В случае успешной операции
token.
tokenizationSource		 Информация об источнике токенизации Object Всегда
token.
tokenizationSource.
type		 Тип источника токенизации String Всегда
token.
tokenizationSource.
uid		 ID источника токенизации String Всегда
token.
bankMemberId		 Идентификатор банка покупателя String В случае успешной операции
type Тип уведомления — только TOKEN String Всегда
version Версия уведомлений String Всегда

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

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

{
  "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"
    },
    "merchantSiteUid": "test-00",
    "flags":["TEST"],
    "payoutSplits" : [
      {
        "type" : "MERCHANT_DETAILS",
        "siteUid" : "Obuc-00",
        "splitAmount" : {
          "value" : "150.00",
          "currency" : "RUB"
        },
        "splitCommissions" : {
          "merchantCms" : {
            "value" : "1.50",
            "currency" : "RUB"
          }
        }
      },
      {
        "type" : "MERCHANT_DETAILS",
        "siteUid" : "Obuc-01",
        "splitAmount" : {
          "value" : "50.00",
          "currency" : "RUB"
        },
        "splitCommissions" : {
          "merchantCms" : {
            "value" : "0.50",
            "currency" : "RUB"
          }
        }
      }
    ]
  },
  "type":"PAYOUT",
  "version":"1"
}
Поле Описание Тип В каких случаях используется
payout Описание выплаты Object Всегда
payout.
payoutId		 Идентификатор выплаты в системе ТСП String(200) Всегда
payout.
createdDateTime		 Дата создания операции URL-закодированная строка
ГГГГ-ММ-ДДTчч:мм:ссZ		 Всегда
payout.
amount		 Информация о сумме операции Object Всегда
payout.
amount.
value		 Сумма операции, округленная до двух десятичных знаков в меньшую сторону Number(6.2) Всегда
payout.
amount.
currency		 Идентификатор валюты операции (Alpha-3 ISO 4217 код) String(3) Всегда
payout.
status		 Информация о статусе операции Object Всегда
payout.
status.
value		 Строковое значение статуса String Всегда
payout.
status.
changedDateTime		 Дата обновления статуса URL-закодированная строка
ГГГГ-ММ-ДДTчч:мм:ссZ		 Всегда
payout.
status.
reasonCode		 Код причины отклонения String(200) В случае отклонения операции
payout.
status.
reasonMessage		 Описание причины отклонения String(200) В случае отклонения операции
payout.
status.
errorCode		 Код ошибки Number В случае ошибки
payout.
receiverData		 Информация о получателе PayoutReceiverDataCallback Всегда
payout.
merchantSiteUid		 Строковый идентификатор сайта ТСП в QIWI Кассе String Всегда
payout.
flags		 Дополнительные флаги операции Array(Strings). Возможные элементы: TEST При необходимости
payout.
payoutSplits		 Описание сплитованных выплат Array(Objects) Всегда
payout.
payoutSplits.
type		 Тип передаваемых данных. Всегда строка MERCHANT_DETAILS String Всегда
payout.
payoutSplits.
siteUid		 ID поставщика String Всегда
payout.
payoutSplits.
splitAmount		 Информация о списании с поставщика Object Всегда
payout.
payoutSplits.
splitAmount.
value		 Сумма списания Number Всегда
payout.
payoutSplits.
splitAmount.
currency		 Буквенный код валюты списания по ISO String(3) Всегда
payout.
payoutSplits.
splitCommissions		 Информация о комиссии Object При необходимости
payout.
payoutSplits.
splitCommissions.
merchantCms		 Информация о комиссии с поставщика Object При необходимости
payout.
payoutSplits.
splitCommissions.
merchantCms.
value		 Сумма комиссии Number При необходимости
payout.
payoutSplits.
splitCommissions.
merchantCms.
currency		 Буквенный код валюты комиссии по ISO String(3) При необходимости
payout.
payoutSplits.
orderId		 Номер заказа String При необходимости
payout.
payoutSplits.
comment		 Комментарий к заказу String При необходимости
type Тип уведомления — только PAYOUT String Всегда
version Версия уведомлений String Всегда

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

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

При возврате платежа комиссия 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 Комментарий к заказу

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

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

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

В Протоколе приема платежей поддерживается выпуск платежных токенов карт, токенов для QR-кодов СБП и 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 для разных покупателей.

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

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

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

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

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

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

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

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

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

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

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

{
  "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-кода:
      • qrCode.type — TOKEN.
      • qrCode.image — тип и размер изображения QR-кода.
    • tokenizationAccount — уникальный идентификатор Покупателя в системе ТСП.
    • "flags":["CREATE_TOKEN"].
    • tokenizationPurpose — описание токена.

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

    Отправьте запрос API Получение QR-кода СБП с данными:

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

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

Информацию о платежном токене СБП вы получите в объекте token ответа и в уведомлении 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, отправленный покупателю.

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

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

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

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-теле запроса укажите параметры:

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

Этот метод действует как для платежного токена карты, так и для платежного токена 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",
      "merchantSiteUid":"test-00"
   },
   "type":"CHECK_CARD",
   "version":"1"
}
  1. Отправьте запрос создания счета с дополнительным параметром "flags":["CHECK_CARD", "BIND_PAYMENT_TOKEN"]. Для генерации платежного токена в запросе должен быть указан параметр customer.account — уникальный идентификатор покупателя в системе ТСП. Не указывайте сумму счета (параметр amount).
  2. Извлеките из ответа параметр billId — он понадобится в п.4. Перенаправьте покупателя на Платежную форму — ссылка на нее находится в параметре payUrl ответа.

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

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

    • Информация о доступности карты для списаний — в атрибуте isValidCard (true — карта доступна).
    • Данные платежного токена — в объекте createdToken. Важно! Объект возвращается только когда isValidCard=true и в п. 1 запрошена генерация платежного токена.

Как использовать сервис через 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 — карта доступна). Если 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 — карта доступна). Если isValidCard=true и запрошен выпуск платежного токена, то платежный токен возвращается в объекте createdToken.

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

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

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

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

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

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

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

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

Акты

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

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

Акт сначала отправляется на 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 DECLINE Запрос авторизации отклонен (в асинхронном ответе)
PAYMENT COMPLETED Запрос авторизации успешно обработан
CAPTURE DECLINE Запрос подтверждения отклонен
CAPTURE DECLINED Запрос подтверждения отклонен (в ответе API на запрос статуса)
CAPTURE COMPLETED Запрос подтверждения успешно обработан
REFUND DECLINE Запрос возврата отклонен
REFUND COMPLETED Запрос возврата успешно обработан
PAYOUT WAITING Выплата принята в обработку
PAYOUT INIT Инициализация выплаты при двушаговом сценарии
PAYOUT DECLINED Выплата отклонена
PAYOUT COMPLETED Выплата успешно проведена

Уведомления

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

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

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

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

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

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

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

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

Ошибка API Описание
GATEWAY_TECHNICAL_ERROR Неизвестная техническая ошибка, попробуйте повторить запрос еще раз
MERCHANT_SETTINGS_ERROR Ошибка в настройках мерчанта, обратитесь в Службу поддержки
DECLINED_BY_FRAUD Отклонено fraud-мониторингом
DECLINED_BY_PAYOUT_GATEWAY Отклонено выплатным шлюзом

Справочник кодов детализации ошибки

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

Код Ошибка API, с которой возвращается Детализация причины ошибки и рекомендация по ее устранению
03 REATTEMPT_NOT_PERMITTED_BY_PS Операция в данную категорию ТСП запрещена эмитентом
04 REATTEMPT_NOT_PERMITTED_BY_PS Карта заблокирована
05 ACQUIRING_NOT_PERMITTED Отклонение запроса по иным причинам
12 REATTEMPT_NOT_PERMITTED_BY_PS Операция данного типа запрещена Правилами и Стандартами платежной системой
13 ACQUIRING_NOT_PERMITTED Некорректная сумма. Повторите попытку совершения операции с другой суммой
14 ACQUIRING_NOT_PERMITTED Некорректный номер карты. Введите корректный номер карты или используйте другую карту
15 REATTEMPT_NOT_PERMITTED_BY_PS Эмитента с данной картой не существует
30 ACQUIRING_NOT_PERMITTED Операция отклонена, обратитесь в Qiwi за дополнительной информацией
33 REATTEMPT_NOT_PERMITTED_BY_PS Данная карта недоступна для использования
41 REATTEMPT_NOT_PERMITTED_BY_PS Данная карта недоступна для использования
43 REATTEMPT_NOT_PERMITTED_BY_PS Данная карта недоступна для использования
51 ACQUIRING_INSUFFICIENT_FUNDS Клиенту может быть рекомендовано повторить попытку совершения операции после пополнения счёта
54 ACQUIRING_EXPIRED_CARD Срок действия карты отсутствует или передан неверно
57 REATTEMPT_NOT_PERMITTED_BY_PS Операция данного типа недоступна для карты
58 REATTEMPT_NOT_PERMITTED_BY_PS Операция данного типа недоступна для эквайера
61 ACQUIRING_LIMIT_EXCEEDED Клиенту может быть рекомендовано повторить попытку совершения операции в другой день — после переустановки Эмитентом лимита по общей сумме операций данного типа
62 REATTEMPT_NOT_PERMITTED_BY_PS Операция недоступна из-за ограничений на карте или счёте Держателя карты
63 ACQUIRING_NOT_PERMITTED Операция отклонена, обратитесь в Qiwi за дополнительной информацией
65 ACQUIRING_LIMIT_EXCEEDED Клиенту может быть рекомендовано повторить попытку совершения операции в другой день — после переустановки Эмитентом лимита по общему количеству операций данного типа
75 ACQUIRING_INCORRECT_CVV Отклонение запроса по причине неверного ввода PIN-кода ранее
76 REATTEMPT_NOT_PERMITTED_BY_PS Отклонение отмены запроса из-за отсутствия оригинального запроса
78 REATTEMPT_NOT_PERMITTED_BY_PS Отклонение запроса из-за попытки использования закрытой карты
86 ACQUIRING_INCORRECT_CVV Отклонение запроса по причине неверного ввода PIN-кода ранее
88 ACQUIRING_AUTH_TECHNICAL_ERROR Отклонение запроса из-за ошибки криптографии, может возникнуть из-за неправильного CVV2/CVC2
91 ACQUIRING_ISSUER_NOT_AVAILABLE Клиенту может быть рекомендовано повторить попытку совершения операции в другое время — после восстановления работоспособности Эмитента
92 REATTEMPT_NOT_PERMITTED_BY_PS Отклонение Платежной Системой из-за невозможности проведения операции
93 REATTEMPT_NOT_PERMITTED_BY_PS Отклонение запроса по причине нарушения требований законодательства
94 REATTEMPT_NOT_PERMITTED_BY_PS Отклонение задублированного запроса
96 ACQUIRING_NOT_PERMITTED Клиенту может быть рекомендовано повторить попытку совершения операции в другое время — после восстановления работоспособности Эмитента или Платформы
TS REATTEMPT_NOT_PERMITTED_BY_PS Отклонение запроса в связи с отменой длительного поручения Держателя карты
CB ACQUIRING_ACQUIRER_ERROR Отклонение запроса из-за некорректной даты рождения Держателя карты
CD REATTEMPT_NOT_PERMITTED_BY_PS Отклонение запроса по причине смерти Держателя карты

Правила работы с детализированной информацией

Существуют две группы кодов ошибок:

По правилам НСПК действуют следующие условия совершения повторов транзакций с non-3DS авторизацией по картам платёжной системы МИР:

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

Справочник методов 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"
   }
}

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

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

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

{
 "billId": "12345",
 "invoiceUid": "3b39ad6d-f111-401d-8108-ed11af920a65",
 "amount": {
   "currency": "RUB",
   "value": "1.00"
 },
 "expirationDateTime": "2023-03-21T13:02:00+03:00",
 "status": {
   "value": "EXPIRED",
   "changedDateTime": "2023-03-21T13:02:00+03:00"
 },
 "comment": "Text comment",
 "flags": [
   "TEST"
 ],
 "payUrl": "https://oplata.qiwi.com/form?invoiceUid=3b39ad6d-f211-401d-8008-ed11af920a65"
}

Пример ответа с ошибкой 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/3a3d0286cefe645d2b11/details HTTP/1.1
Accept: application/json
Authorization: Bearer 5c4b25xx93aa435d9cb8cd17480356f9
Content-type: application/json
Host: api.qiwi.com

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

{
    "billId": "3a3d0286cefe645d2b11",
    "invoiceUid": "235d8d5a-38ed-11fc-9ab6-8b5a65d7e2f8",
    "amount": {
        "currency": "RUB",
        "value": "3000.00"
    },
    "expirationDateTime": "2023-05-07T19:25:36+03:00",
    "status": {
        "value": "PAID",
        "changedDateTime": "2023-04-07T19:28:12+03:00"
    },
    "comment": "Детская футбольная школа «Тигры»",
    "flags": [
        "SALE"
    ],
    "payUrl": "https://oplata.qiwi.com/form?invoiceUid=235d8d5a-11ed-46fc-9ab6-8b5a65d7e2f8",
    "payments": [
        {
            "paymentId": "cd4a4ade-011e6-484d-87c8-40a7f48326fa",
            "billId": "3a3d0286cefe645d2b11",
            "createdDateTime": "2023-04-07T19:27:52+03:00",
            "amount": {
                "currency": "RUB",
                "value": "3000.00"
            },
            "capturedAmount": {
                "currency": "RUB",
                "value": "3000.00"
            },
            "refundedAmount": {
                "currency": "RUB",
                "value": "0.00"
            },
            "paymentMethod": {
                "type": "CARD",
                "maskedPan": "422264******1232",
                "rrn": "309711196151",
                "authCode": "231181"
            },
            "status": {
                "value": "COMPLETED",
                "changedDateTime": "2023-04-07T19:28:12+03:00"
            },
            "comment": "Детская футбольная школа «Тигры»",
            "customFields": {
                "auto_capture": "true",
                "invoice_creation_type": "PUBLIC_KEY"
            },
            "paymentCardInfo": {
                "issuingCountry": "643",
                "issuingBank": "Сбербанк России",
                "paymentSystem": "VISA",
                "fundingSource": "DEBIT",
                "paymentSystemProduct": "N1|Visa Rewards"
            }
        },
        {
            "paymentId": "A30971626215731E01110841111138B2",
            "billId": "3a3d0286cefe645d2b11",
            "createdDateTime": "2023-04-07T19:26:21+03:00",
            "amount": {
                "currency": "RUB",
                "value": "3000.00"
            },
            "capturedAmount": {
                "currency": "RUB",
                "value": "3000.00"
            },
            "refundedAmount": {
                "currency": "RUB",
                "value": "0.00"
            },
            "paymentMethod": {
                "type": "SBP",
                "phone": "0079031232001"
            },
            "status": {
                "value": "DECLINED",
                "changedDateTime": "2023-04-07T19:26:23+03:00",
                "reason": "GATEWAY_INTEGRATION_ERROR",
                "reasonMessage": "I07999 OPKC_TECH_ERROR"
            },
            "comment": "Детская футбольная школа «Тигры»",
            "customFields": {
                "auto_capture": "true",
                "invoice_creation_type": "PUBLIC_KEY"
            }
        }
    ]
}

Пример ответа с ошибкой 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/3a3d0286cefe645d2b00 HTTP/1.1
Accept: application/json
Authorization: Bearer 5c4b25xx93aa435d9cb8cd17480356f9
Content-type: application/json
Host: api.qiwi.com

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

[
    {
        "paymentId": "cd4a4ade-12e6-484d-87c8-40a7f48326fa",
        "billId": "3a3d0286cefe645d2b11",
        "createdDateTime": "2023-04-07T19:27:52+03:00",
        "amount": {
            "currency": "RUB",
            "value": "3000.00"
        },
        "capturedAmount": {
            "currency": "RUB",
            "value": "3000.00"
        },
        "refundedAmount": {
            "currency": "RUB",
            "value": "0.00"
        },
        "paymentMethod": {
            "type": "CARD",
            "maskedPan": "422264******1232",
            "rrn": "309711234151",
            "authCode": "232481"
        },
        "status": {
            "value": "COMPLETED",
            "changedDateTime": "2023-04-07T19:28:12+03:00"
        },
        "comment": "Детская футбольная школа «Тигры»",
        "customFields": {
            "auto_capture": "true",
            "invoice_creation_type": "PUBLIC_KEY"
        },
        "paymentCardInfo": {
            "issuingCountry": "643",
            "issuingBank": "Сбербанк России",
            "paymentSystem": "VISA",
            "fundingSource": "DEBIT",
            "paymentSystemProduct": "N1|Visa Rewards"
        }
    },
    {
        "paymentId": "A30971626215731E000008415C2D38B2",
        "billId": "3a3d0286cefe645d2b00",
        "createdDateTime": "2023-04-07T19:26:21+03:00",
        "amount": {
            "currency": "RUB",
            "value": "3000.00"
        },
        "capturedAmount": {
            "currency": "RUB",
            "value": "3000.00"
        },
        "refundedAmount": {
            "currency": "RUB",
            "value": "0.00"
        },
        "paymentMethod": {
            "type": "SBP",
            "phone": "0079099922001"
        },
        "status": {
            "value": "DECLINED",
            "changedDateTime": "2023-04-07T19:26:23+03:00",
            "reason": "GATEWAY_INTEGRATION_ERROR",
            "reasonMessage": "I07999 OPKC_TECH_ERROR"
        },
        "comment": "Детская футбольная школа «Тигры»",
        "customFields": {
            "auto_capture": "true",
            "invoice_creation_type": "PUBLIC_KEY"
        }
    }
]

Пример ответа с ошибкой 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",
    "cardTokenPaymentType" : "INSTALLMENT",     
    "firstTransaction" : {         
      "paymentId" : "testPaymentId28"     
    } 
  },
  "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"
  },
  "callbackUrl": "https://example.com/callbacks",
  "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-кода СБП

Метод POST

Пример получения QR-кода СБП (метод POST)

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

Метод PUT

Пример получения QR-кода СБП (метод PUT)

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

Статус 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"
}

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

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

POST /partner/payin/v1/sites/test-01/sbp/qrCodes/adghj17d1g8/payments 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": "INIT_PAYMENT_BY_TOKEN",
    "payload": ""
  }
}

Пример ответа с ошибкой 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/",
  "payoutSplits": [
    {
      "type": "MERCHANT_DETAILS",
      "siteUid": "Obuc-00",
      "splitAmount": {
        "value": 30.00,
        "currency": "RUB"
      },
      "orderId": "dressesforwhite",
      "comment": "Платье"
    },
    {
      "type": "MERCHANT_DETAILS",
      "siteUid": "Obuc-01",
      "splitAmount": {
        "value": 10.00,
        "currency": "RUB"
      },
      "orderId": "shoesforvalya",
      "comment": "Туфли"
    }
  ]
}

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

{
  "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",
    "receiverFirstName" : "Ivan",
    "receiverLastName" : "Ivanov"
  },
  "comment": "some comment for payout operation",
  "callbackUrl" : "http://test.com/",
  "flags": [
    "TEST"
  ],
  "payoutSplits": [
    {
      "type": "MERCHANT_DETAILS",
      "siteUid": "Obuc-00",
      "splitAmount": {
        "currency": "RUB",
        "value": "30.00"
      },
      "splitCommissions" : {
        "merchantCms" : {
          "value" : "3.00",
          "currency" : "RUB"
        }
      },
      "orderId": "dressesforwhite",
      "comment": "Платье"
    },
    {
      "type": "MERCHANT_DETAILS",
      "siteUid": "Obuc-01",
      "splitAmount": {
        "currency": "RUB",
        "value": "10.00"
      },
      "splitCommissions" : {
        "merchantCms" : {
          "value" : "1.00",
          "currency" : "RUB"
        }
      },
      "orderId": "shoesforvalya",
      "comment": "Туфли"
    }
  ]
}

Пример ответа с ошибкой 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",
    "receiverFirstName" : "Ivan",
    "receiverLastName" : "Ivanov"
  },
  "comment": "some comment for payout operation",
  "callbackUrl" : "http://test.com/",
  "flags": [
    "TEST"
  ],
  "payoutSplits": [
    {
      "type": "MERCHANT_DETAILS",
      "siteUid": "Obuc-00",
      "splitAmount": {
        "currency": "RUB",
        "value": "30.00"
      },
      "splitCommissions" : {
        "merchantCms" : {
          "value" : "3.00",
          "currency" : "RUB"
        }
      },
      "orderId": "dressesforwhite",
      "comment": "Платье"
    },
    {
      "type": "MERCHANT_DETAILS",
      "siteUid": "Obuc-01",
      "splitAmount": {
        "currency": "RUB",
        "value": "10.00"
      },
      "splitCommissions" : {
        "merchantCms" : {
          "value" : "1.00",
          "currency" : "RUB"
        }
      },
      "orderId": "shoesforvalya",
      "comment": "Туфли"
    }
  ]
}

Пример ответа с ошибкой 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"
}

Завершение выплаты

Пример завершения выплаты

PUT /partner/payin/v1/sites/test-01/payments/1811/payouts/bxwd8096/complete 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",
    "receiverFirstName" : "Ivan",
    "receiverLastName" : "Ivanov"
  },
  "comment": "some comment for payout operation",
  "callbackUrl" : "http://test.com/",
  "flags": [
    "TEST"
  ],
  "payoutSplits": [
    {
      "type": "MERCHANT_DETAILS",
      "siteUid": "Obuc-00",
      "splitAmount": {
        "currency": "RUB",
        "value": "30.00"
      },
      "splitCommissions" : {
        "merchantCms" : {
          "value" : "3.00",
          "currency" : "RUB"
        }
      },
      "orderId": "dressesforwhite",
      "comment": "Платье"
    },
    {
      "type": "MERCHANT_DETAILS",
      "siteUid": "Obuc-01",
      "splitAmount": {
        "currency": "RUB",
        "value": "10.00"
      },
      "splitCommissions" : {
        "merchantCms" : {
          "value" : "1.00",
          "currency" : "RUB"
        }
      },
      "orderId": "shoesforvalya",
      "comment": "Туфли"
    }
  ]
}

Пример ответа с ошибкой 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"
}

Модели данных

PayoutReceiverDataRequest

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

Тип CARD

  "receiverData" : {
    "type" : "CARD",
    "pan" : "86003300000000000",
    "receiverFirstName" : "Ivan",
    "receiverLastName" : "Ivanov"
  }

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

Поле Тип или константа Описание
type
required		 CARD Тип метода выплаты
pan
required		 string(19) Номер банковской карты
receiverFirstName string(64) Имя получателя
receiverLastName string(64) Фамилия получателя

Тип SBP

  "receiverData": {
    "type": "SBP",
    "phone" : "79998887766",
    "bankMemberId" : "100000000111"
  }

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

Поле Тип или константа Описание
type
required		 SBP Тип метода выплаты
phone
required		 number(11..13) Номер телефона
bankMemberId
required		 string(12) Идентификатор банка получателя в СБП. См. список банков, доступных для выплаты на СБП, в формате xlsx (скачать) или csv (скачать)
flags array of strings Дополнительные флаги для операции. Поддерживается значение INIT, которое включает двухшаговый сценарий выплаты на СБП. В случае передачи флага нужно будет дополнительно отправить запрос подтверждения выплаты

PayoutReceiverDataResponse

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

Тип CARD

  "receiverData" : {
    "type" : "CARD",
    "maskedPan": "860033*******0000",
    "receiverFirstName" : "Ivan",
    "receiverLastName" : "Ivanov"
  }

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

Поле Тип или константа Описание
type
required		 CARD Тип метода выплаты
maskedPan
required		 string(19) Маскированный номер банковской карты
receiverFirstName string(64) Имя получателя
receiverLastName string(64) Фамилия получателя

Тип SBP

  "receiverData": {
    "type": "SBP",
    "phone" : "79998887766",
    "bankMemberId" : "100000000111"
  }

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

Поле Тип или константа Описание
type
required		 SBP Тип метода выплаты
phone
required		 number(11..13) Номер телефона
bankMemberId
required		 string(12) Идентификатор банка получателя в СБП

PayoutReceiverDataCallback

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

Тип CARD

  "receiverData" : {
    "type" : "CARD",
    "maskedPan": "860033*******0000"
  }

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

Поле Тип или константа Описание
type
required		 CARD Тип метода выплаты
maskedPan
required		 string(19) Маскированный номер банковской карты

Тип SBP

  "receiverData": {
    "type": "SBP",
    "phone" : "79998887766",
    "bankMemberId" : "100000000111"
  }

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

Поле Тип или константа Описание
type
required		 SBP Тип метода выплаты: "SBP" — СБП
phone
required		 string Номер телефона
bankMemberId
required		 string(12) Идентификатор банка получателя в СБП

ChequeData

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

  "chequeData": {
    "id":5849136,
    "url":"https://cheques.qiwi.com/cheques/receipt/4a02b590-ae81-479c-8f70-85e4f425e05f"
  }
Имя Описание Тип
id Идентификатор чека String
url Информация о чеке (URL-ссылка) String

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

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

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

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

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

Описание объекта 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 string Обязательный параметр. Признак расчета (тэг 1054):
COLLECT – Приход
COLLECT_RETURN - Возврат прихода
CONSUME - Расход
CONSUME_RETURN -Возврат расхода
customerContact string(64) Обязательный параметр. Телефон или электронный адрес покупателя (тэг 1008)
taxSystem string Обязательный параметр. Система налогообложения (тэг 1055):
OSN - Общая, ОСН
USN – Упрощенная доход, УСН доход
USN_MINUS_CONSUM – Упрощенная доход минус расход, УСН доход - расход
ENVD – Единый налог на вмененный доход, ЕНВД
ESN - Единый сельскохозяйственный налог, ЕСН
PATENT – Патентная система налогообложения, Патент
positions array Обязательный параметр. Массив товаров
quantity decimal Обязательный параметр. Количество предмета расчета (тэг 1023)
price decimal Обязательный параметр. Цена за единицу предмета расчета с учетом скидок и наценок (тэг 1079)
tax string Обязательный параметр. Ставка НДС (тэг 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)
description string(128) Обязательный параметр. Наименование предмета расчета
paymentMethod string Обязательный параметр. Признак способа расчёта (тэг 1214):
ADVANCED_FULL_PAYMENT – предоплата 100%. Полная предварительная оплата до момента передачи предмета расчета.
PARTIAL_ADVANCE_PAYMENT – предоплата. Частичная предварительная оплата до момента передачи предмета расчета.
ADVANCE – аванс.
FULL_PAYMENT – полный расчет. Полная оплата, в том числе с учетом аванса (предварительной оплаты) в момент передачи предмета расчета.
PARTIAL_PAYMENT – частичный расчет и кредит. Частичная оплата предмета расчета в момент его передачи с последующей оплатой в кредит.
CREDIT – передача в кредит. Передача предмета расчета без его оплаты в момент его передачи с последующей оплатой в кредит.
CREDIT_PAYMENT – оплата кредита. Оплата предмета расчета после его передачи с оплатой в кредит (оплата кредита).
paymentSubject string Обязательный параметр. Признак предмета расчёта (тэг 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 – иной предмет расчета. О предмете расчета, не относящемуся к выше перечисленным предметам расчета.
Примеры