NAV
json php java html shell

Введение

Интерфейс QiwiPay предназначен для обслуживания операций по банковским картам. Сервис позволяет ТСП принимать безопасные платежи по картам от клиентов.

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

Способы взаимодействия

Существует два способа работы с QiwiPay:

URL сервисов оплаты

https://pay.qiwi.com/paypage/initial.

https://acquiring.qiwi.com/merchant/direct.

Возможные операции

В каждом запросе ТСП к API или при загрузке платежной формы WPF должен указываться код операции. Операция определяет, какое именно действие должно быть выполнено.

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

Код операции QIWIPay WPF QIWIPay API Операция Финансовая Описание
1 + + sale Да Одношаговый сценарий оплаты
2 - + finish_3ds Зависит от сценария Возврат в систему после 3DS аутентиификации
3 + + auth Нет Авторизационный запрос (холдирование средств) в случае двухшагового сценария оплаты
5 - + capture Да Подтверждение авторизации в случае двухшагового сценария оплаты
6 - + reversal Нет Отмена платежа (средства расхолдируются практически сразу)
7 - + refund Да Возврат платежа (средства возвращаются в течение 30 дней)
10 + + recurring_init_sale Да Инитный платеж в случае рекурентных списаний (одношаговый сценарий)
11 + + recurring_init_auth Нет Инитный платеж в случае рекурентных списаний (двухшаговый сценарий)
12 - + recurring Да Рекурентный платеж
13 - + recurring_cancel Нет Отмена автоматических рекурентных списаний
20 - + payout Да Операция выплаты (OCT)
30 - + status Нет Запрос статуса операции
40 - + get_cards_by_token нет Получение списка привязанных карт
51 - + mobile_auth_init Нет Подготовка к авторизационному запросу в случае двухшагового сценария оплаты (от ТСП)
52 - + mobile_auth_card_data Нет Передача карточных данных для выполнения авторизации (из приложения)

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

Методы проведения оплаты

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

Как правило, двухшаговый сценарий используется в том случае, когда ТСП проводит проверку возможности оказания услуги после факта оплаты. Т.к. после операции auth и до совершения операции capture можно сделать операцию reversal, которая не является финансовой.

Для операции sale также можно делать операцию reversal, но только до конца дня и не для всех банков-эквайеров. Подробности надо уточнять у своего менеджера при подключении.

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

Для операции инициации рекаррингового платежа также существует два сценария:

С точки зрения наличия полей в запросе, все операции идентичны. Отличаются лишь коды операций.

Технология 3DS

3DS (3-D Secure) — общее название программ Verified By Visa и MasterCard Secure Code от платежных систем Visa и MasterCard соответственно. Суть программы в проверке подлинности держателя (то есть защита от несанкционированного использования карты) эмитентом перед оплатой. На практике это выглядит так: держатель указывает реквизиты карты, далее открывается сайт эмитента, где держателю предлагается ввести пароль или секретный код (как правило, код отправляется в СМС сообщении). Если код указан правильно, оплата будет проведена. Если нет — отклонена.

Операция покупки может быть проведена через QiwiPay с использованием технологии 3DS, если по карте необходима 3DS-аутентификация.

Диаграмма функционирования 3DS на примере операции с использованием способа QiwiPay WPF.

QIWIPay WPF

Клиенту отображается платежная форма для ввода реквизитов карты на стороне QiwiPay.

ТСП достаточно просто сделать редирект клиента на платежную форму.

Схема одношагового сценария платежа с использованием платежной формы (WPF) на стороне QiwiPay.

Перенаправление на платежную форму

<form method="post" action="https://pay.qiwi.com/paypage/initial">
  <input name="opcode" type="hidden" value="1">
  <input name="merchant_site" type="hidden" value="99">
  <input name="currency" type="hidden" value="643">
  <input name="sign" type="hidden" value="bb5c48ea540035e6b7c03c8184f74f09d26e9286a9b8f34b236b1bf2587e4268">
  <input name="amount" type="text">
  <input type="submit" value="Оплатить">
</form>

Все операции платежа (sale, auth, recurring_init_sale, recurring_init_auth) используют один и тот же набор параметров.

Параметр Условие Тип данных Описание
opcode Обязательно integer Код операции (только 1, 3, 10, 11)
merchant_site Обязательно integer Идентификатор сайта ТСП
currency Обязательно integer Валюта суммы операции в цифровом формате согласно ISO 4217
sign Обязательно string(64) Контрольная сумма переданных параметров
amount Опционально decimal Сумма операции
order_id Опционально string(256) Уникальный номер заказа в системе ТСП
email Опционально string(64) E-mail Покупателя
country Опционально string(3) Страна Покупателя в формате 3-х буквенных кодов согласно ISO 3166-1
city Опционально string(64) Город местонахождения Покупателя
region Опционально string(6) Регион страны формате геокодов согласно ISO 3166-2
address Опционально string(64) Адрес местонахождения Покупателя
phone Опционально string(15) Контактный телефон Покупателя
cf1 Опционально string(256) Поля для ввода произвольной информации, дополняющей данные по операции. Например - описание услуг ТСП.
cf2 Опционально string(256) Поля для ввода произвольной информации, дополняющей данные по операции. Например - описание услуг ТСП.
cf3 Опционально string(256) Поля для ввода произвольной информации, дополняющей данные по операции. Например - описание услуг ТСП.
cf4 Опционально string(256) Поля для ввода произвольной информации, дополняющей данные по операции. Например - описание услуг ТСП.
cf5 Опционально string(256) Поля для ввода произвольной информации, дополняющей данные по операции. Например - описание услуг ТСП.
product_name Опционально string(256) Описание услуги которую получает Плательщик.
merchant_uid Опционально string(64) Уникальный идентификатор Покупателя в системе ТСП.
modifiers Опционально string(64) Модификатор типа транзакции AFT, MO/TO. Можно указывать несколько модификаторов через запятую. Возможные варианты: aft, moto.
card_token Опционально string(40) Токен карты
order_expire Опционально YYYY-MM-DDThh:mm:ss±hh:mm Время истечения заказа в формате ISO8601 с временной зоной
callback_url Опционально string(256) URL отправки callback
success_url Опционально string(256) URL для перенаправления Покупателя в случае успешной оплаты
decline_url Опционально string(256) URL для перенаправления Покупателя в случае не успешной оплаты
cheque Опционально string Данные для кассового чека по 54-ФЗ

QIWIPay API

Авторизация

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

Реализация сценариев платежа

Схема одношагового сценария платежа (sale, recurring_init_sale)

Схема двухшагового сценария платежа (auth, recurring_init_auth, capture)

Операция покупки

Запрос

{
  "opcode": 1,
  "merchant_uid": "10001",
  "merchant_site": 555,
  "pan": "4111111111111111",
  "expiry": "1219",
  "cvv2": "123",
  "amount": "4678.50",
  "currency": 643,
  "modifiers": "aft,moto",
  "card_name": "cardholder name",
  "order_id": "order1231231",
  "ip": "127.0.0.1",
  "email": "merchant@qiwi.com",
  "country": "RUS",
  "city": "Moscow",
  "region": "606008",
  "address": "South Park",
  "phone": "79166554321",
  "user_device_id": "12312321Un43243",
  "user_timedate": "2017-03-15T09:57:21+03:00",
  "user_screen_res": "1080x1794",
  "user_agent": "Mozilla/5.0 (iPhone; CPU iPhone OS 10_2_1 like Mac OS X) AppleWebKit/602.4.6 (KHTML, like Gecko)...",
  "cf1": "cf1",
  "cf2": "cf2",
  "cf3": "cf3",
  "cf4": "cf4",
  "cf5": "cf5",
  "callback_url": "http://domain.tld/callback_service",
  "success_url": "http://domain.tld/success",
  "decline_url": "http://domain.tld/decline",
  "product_name": "Название услуги",
  "sign": "bb5c48ea540035e6b7c03c8184f74f09d26e..........................."
}

Все операции платежа (sale, auth, recurring_init_sale, recurring_init_auth) используют один и тот же набор параметров.

Параметр Условие Тип данных Описание
opcode Обязательно integer Код операции (1, 3, 10, 11)
merchant_site Обязательно integer Идентификатор сайта ТСП
pan Условно обязательно string(19) Номер банковской карты
expiry Условно обязательно string(4) Срок действия банковской карты
card_token Условно обязательно string(40) Токен карты
cvv2 Условно обязательно string(4) CVV2/CVC2 на банковской карте
amount Обязательно string(20) Сумма операции
currency Обязательно integer Валюта суммы операции в цифровом формате согласно ISO 4217
sign Обязательно string(64) Контрольная сумма переданных параметров
card_name Условно обязательно string(64) Имя Покупателя, как указано на карте (латинские буквы)
order_id Условно обязательно string(256) Уникальный номер заказа в системе ТСП
ip Условно обязательно string(15) IP-адрес Покупателя
email Условно обязательно string(64) E-mail Покупателя
country Условно обязательно string(3) Страна Покупателя в формате 3-х буквенных кодов согласно ISO 3166-1
user_device_id Условно обязательно string(64) Уникальный идентификатор устройства Покупателя
city Условно обязательно string(64) Город местонахождения Покупателя
region Условно обязательно string(6) Регион страны формате геокодов согласно ISO 3166-2
address Условно обязательно string(64) Адрес местонахождения Покупателя
phone Условно обязательно string(15) Контактный телефон Покупателя
user_timedate Опционально YYYY-MM-DDThh:mm:ss±hh:mm Локальное время в системе Покупателя в формате ISO8601 с временной зоной
user_screen_res Опционально string(64) Разрешение экрана Покупателя
user_agent Опционально string(256) Браузер Покупателя
cf1 Опционально string(256) Поля для ввода произвольной информации, дополняющей данные по операции. Например - описание услуг ТСП.
cf2 Опционально string(256) Поля для ввода произвольной информации, дополняющей данные по операции. Например - описание услуг ТСП.
cf3 Опционально string(256) Поля для ввода произвольной информации, дополняющей данные по операции. Например - описание услуг ТСП.
cf4 Опционально string(256) Поля для ввода произвольной информации, дополняющей данные по операции. Например - описание услуг ТСП.
cf5 Опционально string(256) Поля для ввода произвольной информации, дополняющей данные по операции. Например - описание услуг ТСП.
product_name Опционально string(256) Описание услуги которую получает Плательщик.
merchant_uid Опционально string(64) Уникальный идентификатор Покупателя в системе ТСП.
modifiers Опционально string(64) Модификатор типа транзакции AFT, MO/TO. Можно указывать несколько модификаторов через запятую. Возможные варианты: aft, moto.
callback_url Опционально string(256) URL отправки callback
success_url Опционально string(256) URL для перенаправления Покупателя в случае успешной оплаты
decline_url Опционально string(256) URL для перенаправления Покупателя в случае не успешной оплаты
cheque Опционально string Данные для кассового чека по 54-ФЗ

Ответ на операцию покупки в случае не 3DS операции

{
  "txn_id":172001,
  "txn_status":3,
  "txn_type":1,
  "txn_date": "2017-03-09T17:16:06+00:00",
  "card_token": "4d5b363e-a116-35f5-e053-6751080ac38e",
  "card_token_expire": "2018-02-27T21:00:00+00:00",
  "error_code":0,
  "pan": "411111xxxxxx1111",
  "amount": 4678.50,
  "currency": 643,
  "auth_code": "2G4923",
  "eci": 
}
Параметр Тип данных Описание
txn_id integer Идентификатор транзакции
txn_status integer Статус транзакции
txn_type integer Тип транзакции
txn_date YYYY-MM-DDThh:mm:ss±hh:mm Дата транзакции в формате ISO8601 с временной зоной
card_token string(40) Токен карты (если функционал токенизации включен для данного сайта)
card_token_expire YYYY-MM-DDThh:mm:ss±hh:mm Срок истечения токена карты (если функционал токенизации включен для данного сайта)
error_code integer Код ошибки работы системы
pan string(19) Номер карты Покупателя
amount decimal Сумма списания
currency integer Валюта суммы списания в цифровом формате согласно ISO 4217
auth_code string(6) Код авторизации
eci string(2) Индикатор E-Commerce операции

Ответ в случае если необходима 3DS аутентификация

{
  "txn_id":172001,
  "txn_status":0,
  "txn_type":1,
  "txn_date": "2017-03-09T17:16:06+00:00",
  "error_code":0,
  "acs_url":"https://test.paymentgate.ru/acs/auth/start.do",
  "pareq":"eJxVUmtvgjAUuG79oClYe51uDcsi2B+ZrJPgKtipGHRnUTgy1w5bVwyf4BfjpuJ........."
}
Параметр Тип данных Описание
txn_id integer Идентификатор транзакции
txn_status integer Статус транзакции
txn_type integer Тип транзакции
txn_date YYYY-MM-DDThh:mm:ss±hh:mm Дата транзакции в формате ISO8601 с временной зоной
error_code integer Код ошибки работы системы
acs_url string(1024) URL адрес банка-эмитента куда необходимо перенаправить Покупателя
pareq string(4096) Уникальный идентификатор Покупателя, используемый при дальнейшем его перенаправлении на acs_url.

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

Завершение 3DS аутентификации

После успешного прохождения 3DS аутентификации, ТСП необходимо отправить запрос для завершения проверки.

Запрос после прохождения 3DS аутентификации

{
  "opcode":2,
  "merchant_site":99,
  "pares": "eJzVWFevo9iyfu9fMZrzaM0QjWHk3tIiGptgooE3cgabYMKvv3jvTurTc3XOfbkaJMuL............",
  "txn_id": "172001"
}
Параметр Условие Тип данных Описание
opcode Обязательно integer Код операции (2)
merchant_site Обязательно integer Идентификатор сайта ТСП
pares Обязательно string(4096) Результат верификации Покупателя
txn_id Обязательно integer Идентификатор транзакции
sign Обязательно string(64) Контрольная сумма переданных параметров

Ответ на операцию покупки после 3DS аутентификации

{
  "txn_id":172001,
  "txn_status":3,
  "txn_type":1,
  "txn_date": "2017-03-09T17:16:06+00:00",
  "card_token": "4d5b363e-a116-35f5-e053-6751080ac38e",
  "card_token_expire": "2018-02-27T21:00:00+00:00",
  "error_code":0,
  "pan": "411111xxxxxx1111",
  "amount": 4678.50,
  "currency": 643,
  "auth_code": "2G4923",
  "eci": "5"
}
Параметр Тип данных Описание
txn_id integer Идентификатор транзакции
txn_status integer Статус транзакции
txn_type integer Тип транзакции
txn_date YYYY-MM-DDThh:mm:ss±hh:mm Дата транзакции в формате ISO8601 с временной зоной
card_token string(40) Токен карты (если функционал токенизации включен для данного сайта)
card_token_expire YYYY-MM-DDThh:mm:ss±hh:mm Срок истечения токена карты (если функционал токенизации включен для данного сайта)
error_code integer Код ошибки работы системы
pan string(19) Номер карты Покупателя
amount decimal Сумма списания
currency integer Валюта суммы списания в цифровом формате согласно ISO 4217
auth_code string(6) Код авторизации
eci string(2) Индикатор E-Commerce операции

Операция подтверждения покупки

Запрос

{
  "opcode": 5,
  "merchant_site": 99,
  "txn_id": "172001",
  "sign": "bb5c48ea540035e6b7c03c8184f74f09d26e9286a9b8f34b236b1bf2587e4268"
}
Параметр Условие Тип данных Описание
opcode Обязательно integer Код операции (5)
merchant_site Обязательно integer Идентификатор сайта ТСП
txn_id Обязательно integer Идентификатор транзакции
cheque Опционально string Данные для кассового чека по 54-ФЗ
sign Обязательно string(64) Контрольная сумма переданных параметров

Ответ

{
  "txn_id":172001,
  "txn_status":3,
  "txn_type":2,
  "txn_date": "2017-03-09T17:16:06+00:00",
  "error_code":0
}
Параметр Тип данных Описание
txn_id integer Идентификатор транзакции
txn_status integer Статус транзакции
txn_type integer Тип транзакции
txn_date YYYY-MM-DDThh:mm:ss±hh:mm Дата транзакции в формате ISO8601 с временной зоной
error_code integer Код ошибки работы системы

Операция отмены

Запрос

{
  "opcode":6,
  "merchant_site": 99,
  "txn_id": 181001,
  "amount": "700",
  "sign": "bb5c48ea540035e6b7c03c8184f74f09d26e9286a9b8f34b236b1bf2587e4268"
}
Параметр Условие Тип данных Описание
opcode Обязательно integer Код операции (6)
merchant_site Обязательно integer Идентификатор сайта ТСП
txn_id Обязательно integer Идентификатор транзакции
amount Опционально string(20) Сумма операции
cheque Опционально string Данные для кассового чека по 54-ФЗ
sign Обязательно string(64) Контрольная сумма переданных параметров

Ответ

{
  "txn_id":182001,
  "txn_status":3,
  "txn_type":4,
  "txn_date": "2017-03-09T17:16:06+00:00",
  "error_code":0,
  "amount": 700
}
Параметр Тип данных Описание
txn_id integer Идентификатор транзакции
txn_status integer Статус транзакции
txn_type integer Тип транзакции
txn_date YYYY-MM-DDThh:mm:ss±hh:mm Дата транзакции в формате ISO8601 с временной зоной
error_code integer Код ошибки работы системы
amount decimal Сумма списания

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

Запрос

{
  "opcode":7,
  "merchant_site": 99,
  "txn_id": 181001,
  "amount": "700",
  "sign": "bb5c48ea540035e6b7c03c8184f74f09d26e9286a9b8f34b236b1bf2587e4268"
}
Параметр Условие Тип данных Описание
opcode Обязательно integer Код операции (7)
merchant_site Обязательно integer Идентификатор сайта ТСП
txn_id Обязательно integer Идентификатор транзакции
amount Опционально string(20) Сумма операции
cheque Опционально string Данные для кассового чека по 54-ФЗ
sign Обязательно string(64) Контрольная сумма переданных параметров

Ответ

{
  "txn_id":182001,
  "txn_status":3,
  "txn_type":3,
  "txn_date": "2017-03-09T17:16:06+00:00",
  "error_code":0,
  "amount": 700
}
Параметр Тип данных Описание
txn_id integer Идентификатор транзакции
txn_status integer Статус транзакции
txn_type integer Тип транзакции
txn_date YYYY-MM-DDThh:mm:ss±hh:mm Дата транзакции в формате ISO8601 с временной зоной
error_code integer Код ошибки работы системы
amount decimal Сумма списания

Рекурентный платеж

Запрос

{
  "opcode": 12,
  "merchant_uid": "10001",
  "merchant_site": 99,
  "txn_id": 172001,
  "amount": "4678.50",
  "currency": 643,
  "order_id": "order1231231",
  "cf1": "cf1",
  "cf2": "cf2",
  "cf3": "cf3",
  "cf4": "cf4",
  "cf5": "cf5",
  "product_name": "Название услуги",
  "sign": "bb5c48ea540035e6b7c03c8184f74f09d26e9286a9b8f34b236b1bf2587e4268"
}
Параметр Условие Тип данных Описание
opcode Обязательно integer Код операции (12)
merchant_site Обязательно integer Идентификатор сайта ТСП
txn_id Обязательно integer Идентификатор транзакции
amount Обязательно string(20) Сумма операции
currency Обязательно integer Валюта суммы операции в цифровом формате согласно ISO 4217
sign Обязательно string(64) Контрольная сумма переданных параметров
order_id Условно обязательно string(256) Уникальный номер заказа в системе ТСП
cf1 Опционально string(256) Поля для ввода произвольной информации, дополняющей данные по операции. Например - описание услуг ТСП.
cf2 Опционально string(256) Поля для ввода произвольной информации, дополняющей данные по операции. Например - описание услуг ТСП.
cf3 Опционально string(256) Поля для ввода произвольной информации, дополняющей данные по операции. Например - описание услуг ТСП.
cf4 Опционально string(256) Поля для ввода произвольной информации, дополняющей данные по операции. Например - описание услуг ТСП.
cf5 Опционально string(256) Поля для ввода произвольной информации, дополняющей данные по операции. Например - описание услуг ТСП.
product_name Опционально string(256) Описание услуги которую получает Плательщик.
cheque Опционально string Данные для кассового чека по 54-ФЗ

Ответ

{
  "txn_id":182001,
  "txn_status":3,
  "txn_type":5,
  "txn_date": "2017-03-09T17:16:06+00:00",
  "error_code":0,
  "amount": 4678.50,
  "currency": 643,
  "auth_code": "2G4923"
}
Параметр Тип данных Описание
txn_id integer Идентификатор транзакции
txn_status integer Статус транзакции
txn_type integer Тип транзакции
txn_date YYYY-MM-DDThh:mm:ss±hh:mm Дата транзакции в формате ISO8601 с временной зоной
error_code integer Код ошибки работы системы
amount decimal Сумма списания
currency integer Валюта суммы списания в цифровом формате согласно ISO 4217
auth_code string(6) Код авторизации

Операция выплаты

Запрос

{
  "opcode": 20,
  "merchant_uid": "10001",
  "merchant_site": 555,
  "card_token": "4d5b363e-a116-35f5-e053-6751080ac38e",
  "txn_id":182001,
  "amount": "4678.50",
  "currency": 643,
  "card_name": "cardholder name",
  "order_id": "order1231231",
  "cf1": "cf1",
  "cf2": "cf2",
  "cf3": "cf3",
  "cf4": "cf4",
  "cf5": "cf5",
  "callback_url": "http://domain.tld/callback_service",
  "success_url": "http://domain.tld/success",
  "decline_url": "http://domain.tld/decline",
  "product_name": "Выплата выигрыша",
  "sign": "bb5c48ea540035e6b7c03c8184f74f09d26e..........................."
}
Параметр Условие Тип данных Описание
opcode Обязательно integer Код операции (20)
merchant_site Обязательно integer Идентификатор сайта ТСП
pan Условно обязательно string(19) Номер банковской карты
card_token Условно обязательно string(40) Токен карты
txn_id Условно обязательно integer Идентификатор транзакции (для контроля максимальной суммы выплаты)
amount Обязательно string(20) Сумма операции
currency Обязательно integer Валюта суммы операции в цифровом формате согласно ISO 4217
sign Обязательно string(64) Контрольная сумма переданных параметров
card_name Условно обязательно string(64) Имя Покупателя, как указано на карте (латинские буквы)
order_id Условно обязательно string(256) Уникальный номер заказа в системе ТСП
cf1 Опционально string(256) Поля для ввода произвольной информации, дополняющей данные по операции. Например - описание услуг ТСП.
cf2 Опционально string(256) Поля для ввода произвольной информации, дополняющей данные по операции. Например - описание услуг ТСП.
cf3 Опционально string(256) Поля для ввода произвольной информации, дополняющей данные по операции. Например - описание услуг ТСП.
cf4 Опционально string(256) Поля для ввода произвольной информации, дополняющей данные по операции. Например - описание услуг ТСП.
cf5 Опционально string(256) Поля для ввода произвольной информации, дополняющей данные по операции. Например - описание услуг ТСП.
product_name Опционально string(256) Описание услуги которую получает Плательщик.
merchant_uid Опционально string(64) Уникальный идентификатор Покупателя в системе ТСП.
callback_url Опционально string(256) URL отправки callback
success_url Опционально string(256) URL для перенаправления Покупателя в случае успешной оплаты
decline_url Опционально string(256) URL для перенаправления Покупателя в случае не успешной оплаты

Ответ

{
  "txn_id":172001,
  "txn_status":3,
  "txn_type":8,
  "txn_date": "2017-03-09T17:16:06+00:00",
  "error_code":0,
  "pan": "411111xxxxxx1111",
  "amount": 4678.50,
  "currency": 643,
  "auth_code": "2G4923"
}
Параметр Тип данных Описание
txn_id integer Идентификатор транзакции
txn_status integer Статус транзакции
txn_type integer Тип транзакции
txn_date YYYY-MM-DDThh:mm:ss±hh:mm Дата транзакции в формате ISO8601 с временной зоной
error_code integer Код ошибки работы системы
pan string(19) Номер карты
amount decimal Сумма выплаты
currency integer Валюта суммы списания в цифровом формате согласно ISO 4217
auth_code string(6) Код авторизации

Запрос статуса операции

Запрос

{
  "opcode":30,
  "merchant_site": 99,
  "order_id": "41324123412342",
  "sign": "bb5c48ea540035e6b7c03c8184f74f09d26e9286a9b8f34b236b1bf2587e4268"
}
Параметр Условие Тип данных Описание
opcode Обязательно integer Код операции (30)
merchant_site Обязательно integer Идентификатор сайта ТСП
txn_id Опционально integer Идентификатор транзакции
order_id Опционально string(256) Уникальный номер заказа в системе ТСП
sign Обязательно string(64) Контрольная сумма переданных параметров

Ответ

{
  "transactions": [
    {
      "error_code": 0,
      "txn_id": 3666050,
      "txn_status": 2,
      "txn_type": 2,
      "txn_date": "2017-03-09T17:16:06+00:00",
      "pan": "400000******0002",
      "amount": 10000,
      "currency": 643,
      "auth_code": "181218",
      "merchant_site": 99,
      "card_name": "cardholder name",
      "card_bank": "",
      "order_id": "41324123412342"
    },
    {
      "error_code": 0,
      "txn_id": 3684050,
      "txn_status": 3,
      "txn_type": 4,
      "txn_date": "2017-03-09T17:16:09+00:00",
      "pan": "400000******0002",
      "amount": 100,
      "currency": 643,
      "merchant_site": 99,
      "card_name": "cardholder name",
      "card_bank": ""
    },
    {
      "error_code": 0,
      "txn_id": 3685050,
      "txn_status": 3,
      "txn_type": 4,
      "txn_date": "2017-03-19T17:16:06+00:00",
      "pan": "400000******0002",
      "amount": 100,
      "currency": 643,
      "merchant_site": 99,
      "card_name": "cardholder name",
      "card_bank": ""
    }
  ],
  "error_code": 0
}
Параметр Тип данных Описание
txn_id integer Идентификатор транзакции
txn_status integer Статус транзакции
txn_type integer Тип транзакции
txn_date YYYY-MM-DDThh:mm:ss±hh:mm Дата транзакции в формате ISO8601 с временной зоной
error_code integer Код ошибки работы системы
pan string(19) Номер карты Покупателя в формате 411111XXXXXX1111
amount decimal Сумма списания
currency integer Валюта суммы списания в цифровом формате согласно ISO 4217
auth_code string(6) Код авторизации
eci string(2) Индикатор E-Commerce операции
card_name string(64) Имя Покупателя, как указано на карте (латинские буквы)
card_bank string(64) Банк-эмитент карты
order_id string(256) Уникальный номер заказа в системе ТСП
ip string(15) IP-адрес Покупателя
email string(64) E-mail Покупателя
country string(3) Страна Покупателя в формате 3-х буквенных кодов согласно ISO 3166-1
city string(64) Город местонахождения Покупателя
region string(6) Регион страны формате геокодов согласно ISO 3166-2
address string(64) Адрес местонахождения Покупателя
phone string(15) Контактный телефон Покупателя
cf1 string(256) Поля для ввода произвольной информации, дополняющей данные по операции. Например - описание услуг ТСП.
cf2 string(256) Поля для ввода произвольной информации, дополняющей данные по операции. Например - описание услуг ТСП.
cf3 string(256) Поля для ввода произвольной информации, дополняющей данные по операции. Например - описание услуг ТСП.
cf4 string(256) Поля для ввода произвольной информации, дополняющей данные по операции. Например - описание услуг ТСП.
cf5 string(256) Поля для ввода произвольной информации, дополняющей данные по операции. Например - описание услуг ТСП.
product_name string(256) Описание услуги которую получает Плательщик.

Отраслевые данные

Авиаданные

{
  "pan": "4111111111111111",
  "expiry": "1217",
  "cvv2": "002",
  "card_name": "cardholder name",
  "merchant_site": 1234,
  "cf1": "Ghbdtn",
  "opcode": 3,
  "callback_url": "testtest",
  "amount": 100,
  "currency": 643,
  "sign": "9FD874BF9D4483854E25D1D3371D01821AA4814CDFA4FE2033B5EDD4D5DE94C9",
  "industryData": { 
      "type": "avia",
      "pnr": "6Q32R2",
      "tickets": [
          {
              "number": "1",
              "passenger_name": "Ivan Ivanov",
              "amount": 500,
              "amount_total": 700,
              "restricted": false,
              "agency_code": "avi",
              "agency_name": "avia company",
              "airport_code": "air",
              "segments": [
                  {
                      "amount": 500,
                      "service_class": "A",
                      "fare_basis_code": "B",
                      "dest_city": "XYB",
                      "carrier_code": "AI",
                      "stopover_code": "X",
                      "departure_date": "2016-12-30T02:45:00Z",
                      "flight_number": "12545"
                  }
              ]
          }
      ]
  }
}

Авиаданные передаются в параметре industry_data в операциях auth, capture, sale при работе через QIWIPay API. В случае, если на момент совершения операции auth присутствуют не все необходимые данные, их можно отправить в операции capture после получения.

В авиаданных должны присутствовать билеты из брони, а также все сегменты (перелеты) из каждого билета.

Параметр Условие Тип данных Описание
type Обязательно string Типы отраслевых данных (avia)
pnr Опционально string(6) Номер брони
tickets Обязательно array Массив билетов
number Обязательно string(14) Номер билета
passenger_name Обязательно string(20) Имя пассажира
amount Обязательно decimal Цена билета без сборов
amount_total Обязательно decimal Цена билета со сборами
restricted Обязательно boolean Restricted Ticked Indicator
agency_code Обязательно string(8) Код агентства
agency_name Обязательно string(25) Название агентства
airport_code Обязательно string(3) Аэропорт вылета (3 буквы по классификации IATA)
segments Обязательно array Массив сегментов
amount Обязательно decimal Номер билета
service_class Обязательно string(1) Класс обслуживания
fare_basis_code Обязательно string(6) Вид тарифа
dest_city Обязательно string(3) Аэропорт назначения (3 буквы по классификации IATA)
carrier_code Обязательно string(2) Код авиакомпании
stopover_code Обязательно string(1) Stop-Over Code
departure_date Обязательно YYYY-MM-DDThh:mm:ss±hh:mm Дата вылета в формате ISO8601 с временной зоной
flight_number Обязательно string(5) Номер рейса, только цифры

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

{
  "seller_id" : 3123011520,
  "cheque_type" : 1,
  "customer_contact" : "foo@domain.tld",
  "tax_system" : 1,
  "positions" : [
    {
      "quantity" : 2,
      "price" : 322.94,
      "tax" : 4,
      "description" : "Товар/Услуга 1"
    },
    {
      "quantity" : 1,
      "price" : 500,
      "tax" : 4,
      "description" : "Товар/Услуга 2"
    }
  ]
}
<?php
$cheque_json = '{
  "seller_id" : 3123011520,
  "cheque_type" : 1,
  "customer_contact" : "foo@domain.tld",
  "tax_system" : 1,
  "positions" : [
    {
      "quantity" : 2,
      "price" : 322.94,
      "tax" : 4,
      "description" : "Товар/Услуга 1"
    },
    {
      "quantity" : 1,
      "price" : 500,
      "tax" : 4,
      "description" : "Товар/Услуга 2"
    }
  ]
}';


$cheque = base64_encode(gzcompress($cheque_json));
?>

Output:
eJyljk0KwjAQRveeImRdtEl1oSvvIVJCGjHQNrWZgqUUFG+iFyi6FDxDeiOT+LcQV25m8d58800zQAhrkaaijGWC0QxFhEYhIRMaBs7xtdhUIoa6EM6SB6w0qMxGuMqBcXAGr5SaJypjMh9CmmC/CGwb61qDyD7hQmkJUuXaoYUlCDV+WrepWA4Saqdo8KJFKblvjygdTsdvbq87+gGJ0LyUhbvuXzJHczNn0/W7kTn1e3PtD+ZiOkSwT7TB73by3T4Jw/+r6bPazuWgvQNvoHPJ

Чек передается в параметре cheque при редиректе на QIWIPay WPF, а также в операциях auth, capture, sale при работе через QIWIPay API.

JSON структура чека должна быть сжата алгоритмом DEFLATE, описанным в RFC1951, а после предствалена в ZLIB формате, описанным в RFC1950. Далее результат кодируется в BASE64 и передается в параметре cheque.

Описание чека

Параметр Условие Тип данных Описание
seller_id Обязательно decimal ИНН организации, для которой пробивается чек
cheque_type Обязательно decimal Признак расчета (тэг 1054):
1. Приход
2. Возврат прихода
3. Расход
4. Возврат расхода
customer_contact Обязательно string(64) Телефон или электронный адрес покупателя (тэг 1008)
tax_system Обязательно decimal Система налогообложения (тэг 1055):
0 – Общая, ОСН
1 – Упрощенная доход, УСН доход
2 – Упрощенная доход минус расход, УСН доход - расход
3 – Единый налог на вмененный доход, ЕНВД
4 – Единый сельскохозяйственный налог, ЕСН
5 – Патентная система налогообложения, Патент
positions Обязательно array Массив товаров
quantity Обязательно decimal Количество предмета расчета (тэг 1023)
price Обязательно decimal Цена за единицу предмета расчета с учетом скидок и наценок (тэг 1079)
tax Обязательно decimal Ставка НДС (тэг 1199):
1 – ставка НДС 18%
2 – ставка НДС 10%
3 – ставка НДС расч. 18/118
4 – ставка НДС расч. 10/110
5 – ставка НДС 0%
6 – НДС не облагается
description Обязательно string(128) Наименование предмета расчета

Подпись запроса


public String generateSignature(String data, String secret) {
    try {
        byte[] secretBytes = secret.getBytes("UTF-8");
        Mac hmac = Mac.getInstance("HmacSHA256");
        SecretKeySpec secretKey = new SecretKeySpec(secretBytes, "HmacSHA256");
        hmac.init(secretKey);
        byte[] signBytes = hmac.doFinal(data.getBytes("UTF-8"));
        return Utils.bytesToHex(signBytes);
    } catch (NoSuchAlgorithmException | UnsupportedEncodingException | InvalidKeyException e) {
        throw new SignatureException("Cannot calculate signature", e);
    }
}

sign = generateSignature('7.00|643|555|3','secret_key');

Для параметров amount|currency|merchant_site|opcode

<?php
$hmac = hash_hmac('sha256','7.00|643|555|3','secret_key');
?>

Output:
9c878bfbf9baa30c26c8c6206976fc3ed2c036afeabf352f8a045fe331d42d7e
Для параметров amount|currency|merchant_site|opcode

user@server:~$ echo -n "7.00|643|555|3" | openssl dgst -sha256  -hmac "secret_key"
(stdin)= 9c878bfbf9baa30c26c8c6206976fc3ed2c036afeabf352f8a045fe331d42d7e

Все передаваемые параметры каждой операции должны быть подписаны. Подпись помещается в параметр sign в каждом запросе.

Для формирования подписи используется механизм проверки целостности HMAC с хэш-функцией SHA256.

Уведомление о платеже

Существует два метода доставки уведомлений о платеже:

Уведомление доставляется на переданный в запросе параметр callback_url в виде POST запроса с параметрами, указанными ниже.

Параметр Тип данных Участвует в sign Описание
txn_id integer + Идентификатор транзакции
txn_status integer + Статус транзакции
txn_type integer + Тип транзакции
txn_date YYYY-MM-DDThh:mm:ss±hh:mm - Дата транзакции в формате ISO8601 с временной зоной
error_code integer + Код ошибки работы системы
pan string(19) - Номер карты Покупателя в формате 411111XXXXXX1111
amount decimal + Сумма списания
currency integer + Валюта суммы списания в цифровом формате согласно ISO 4217
auth_code string(6) - Код авторизации
eci string(2) - Индикатор E-Commerce операции
card_name string(64) - Имя Покупателя, как указано на карте (латинские буквы)
card_bank string(64) - Банк-эмитент карты
order_id string(256) - Уникальный номер заказа в системе ТСП
ip string(15) + IP-адрес Покупателя
email string(64) + E-mail Покупателя
country string(3) - Страна Покупателя в формате 3-х буквенных кодов согласно ISO 3166-1
city string(64) - Город местонахождения Покупателя
region string(6) - Регион страны формате геокодов согласно ISO 3166-2
address string(64) - Адрес местонахождения Покупателя
phone string(15) - Контактный телефон Покупателя
cf1 string(256) - Поля для ввода произвольной информации, дополняющей данные по операции. Например - описание услуг ТСП.
cf2 string(256) - Поля для ввода произвольной информации, дополняющей данные по операции. Например - описание услуг ТСП.
cf3 string(256) - Поля для ввода произвольной информации, дополняющей данные по операции. Например - описание услуг ТСП.
cf4 string(256) - Поля для ввода произвольной информации, дополняющей данные по операции. Например - описание услуг ТСП.
cf5 string(256) - Поля для ввода произвольной информации, дополняющей данные по операции. Например - описание услуг ТСП.
product_name string(256) - Описание услуги которую получает Плательщик.
card_token string(40) - Токен карты (если функционал токенизации включен для данного сайта)
card_token_expire YYYY-MM-DDThh:mm:ss±hh:mm - Срок истечения токена карты (если функционал токенизации включен для данного сайта)
sign string(64) - Контрольная сумма переданных параметров. Контрольная сумма передается в верхнем регистре.

В параметрах уведомления присутствует подпись запроса (sign), который ТСП необходимо проверять на своей стороне для исключения возможности подделки уведомления.

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

Уведомление считается успешно доставленным если сервер ТСП ответил HTTP с кодом состояния 200 OK. Таким образом, до тех пор пока не будет ответа сервера с кодом состояния 200 OK, система будет осуществлять попытки доставки уведомления через увеличивающиеся интервалы времени в течение суток с момента операции.

Типы транзакций

Возможные типы транзакций, возвращаемые в ответе в поле txn_type, указаны в таблице.

Тип Название Описание
1 Purchase Одношаговая операция оплаты
2 Purchase Операция авторизации при двухшаговом сценарии платежа
6 Purchase Одношаговая операция инициализации рекуррентных платежей
7 Purchase Операция авторизации при двухшаговом сценарии инициализации рекуррентных платежей
4 Reversal Операция отмены
3 Refund Операция возврата
5 Recurring Операция рекуррентного платежа
8 Payout Операция выплаты (OCT)
0 Unknown Неизвестный тип операции

Статусы транзакции

Статус Название Описание Возможные операции
0 Init Пройдена базовая верификация данных и начат процесс проведения операции -
1 Declined Операция отклонена -
2 Authorized Выполнена операция авторизации средств (холдирование) capture, reversal
3 Captured (Complited) Подтвержденная операция reversal
4 Reconciled Полностью завершенная финансовая операция refund
5 Settled За данную операцию средства будут выплачены ТСП refund

Описание ошибок

Запрос
{
    "opcode": 1,
    "pan": "4",
    "expiry": "1010",
    "cvv2": "1",
    "amount": 4678.5,
    "card_name": "cardholder name",
    "merchant_site": 1000,
    "sign": "9FD874BF9D4483854E25D1D3371D01821AA4814CDFA4FE2033B5EDD4D5DE94C9"
}

Ответ
{
  "errors": [
    {
      "field": "pan",
      "message": "length of [pan] cannot be less than 13"
    },
    {
      "field": "expiry",
      "message": "card expired"
    },
    {
      "field": "cvv2",
      "message": "length of [cvv2] cannot be less than 3"
    }
  ],
  "error_message": "Validation errors",
  "error_code": 8019
}


Запрос
{

  "opcode" : 6,
  "merchant_site" : "1234",
  "txn_id" : "",
  "sign" : "sadads",
  "amount" : "1000.01"
}

Ответ
{
  "error_message":"Parsing error",
  "error_code":8018
}

Код ошибки Название Описание
0 No errors Нет ошибок.
8001 Internal error Техническая ошибка банка-эквайера.
8002 Operation not supported Операция не поддерживается.
8004 Temporary error Сервер занят, повторите запрос позднее.
8005 Route not found Не найден маршрут для проведения транзакции.
8006 Card not supported Некорректный номер карты.
8018 Parsing error Ошибка разбора JSON запроса.
8019 Validation error Ошибки валидации входных параметров. Детали отражены в возвращаемом массиве errors.
8020 Amount too big Превышена сумма для операций reversal, refund.
8021 Merchant site not found Неизвестный merchant_site.
8022 Transaction not found Не найдена транзакция из запроса.
8023 Transaction expired Покупатель не смог аутентифицироваться с помощью 3DS в течение 15 минут.
8025 Opcode is not allowed Использование данного opcode запрещено для данного сайта.
8026 Incorrect parent transaction Некорректный статус родительской транзакции.
8027 Incorrect parent transaction Некорректный тип родительской транзакции.
8028 Card expired Срок действия карты истек.
8051 Merchant disabled Данный мерчант не активирован.
8052 Incorrect transaction state Некорретный статус транзакции, попытка сделать capture на finish_3ds или reversal.
8054 Invalid signature Некорректная подпись запроса.
8055 Order already payed Заказ уже оплачен.
8056 In process Транзакция по данной карте/заказу уже в процессе проведения.
8057 Card locked По данной карты уже проводится транзакция.
8058 Access denied  
8059 Currency is not allowed Данная валюта запрещена.
8060 Amount too big Сумма первышает допустимую для выплаты.
8061 Currency mismatch Несовпадение валюты выплаты и оригинальной транзакциию
8151 Authentification failed Покупатель не смог аутентифицироваться с помощью 3DS.
8152 Transaction rejected Транзакция отклонена службой безопасности.
8161 Transaction rejected Ответ эмитента: Платеж отклонен. Попробуйте еще раз.
8162 Transaction rejected Ответ эмитента: Платеж отклонен. Попробуйте еще раз.
8163 Transaction rejected Ответ эмитента: Платеж отклонен. Обратитесь в поддержку QIWI.
8164 Transaction rejected Ответ эмитента: Платеж отклонен. Превышен лимит. Обратитесь в Банк выпустивший карту.
8165 Transaction rejected Ответ эмитента: Платеж отклонен. Проверьте реквизиты платежа.
8168 Transaction rejected Ответ эмитента: Транзакция запрещена. Обратитесь в Банк выпустивший карту.

Данные для тестирования

Для тестирования операций оплаты используются боевые url сервисов оплаты. Для каждого нового ТСП в системе создаются merchant, merchant_site и по-умолчанию включаются в режим тестирования. Также можно запросить переключение в режим тестирования любого своего merchant_site, либо добавление нового merchant_site в тестовом режиме через своего менеджера. В тестовом режиме можно использовать любой номер карты удовлетворяющий алгоритму Luhn.

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

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