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

Общая информация

Последнее обновление: 2020-06-19 | Редактировать на GitHub

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

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

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

Токен 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 - протокол защиты, используемый для аутентификации держателя банковской карты во время совершения платежной операции посредством сети Интернет.
ТСП: Торгово-сервисное предприятие
MPI: Merchant Plug-In - модуль системы, выполняющий 3DS аутентификацию.
PCI DSS: Payment Card Industry Data Security Standard - стандарт безопасности данных индустрии платёжных карт, учреждённым международными платёжными системами Visa, MasterCard, American Express, JCB и Discover.

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

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

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

Метод API Checkout
Одношаговая авторизация средств + +
Двухшаговая авторизация средств + +
Выпуск платежного токена + +
Оплата платежным токеном + -
Оплата с баланса КИВИ Кошелька - +

Начало работы

Для того, чтобы начать работу с протоколом, необходимо выполнить 3 простых шага.

Шаг 1. Оставить заявку на подключение b2b.qiwi.com

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

Шаг 2. Получить доступ к личному кабинету

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

Шаг 3. Выпустить токен API для взаимодействия

Для взаимодействия с API используется токен API. Значение токена указывается в заголовке Authorization, который формируется как Bearer "Token".

Тестовый и производственный режим

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

https://api.qiwi.com/partner{API_REQUESTS}

Далее при описании всех запросов указывается только часть пути {API_REQUESTS}.

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

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

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

Checkout

Быстрый старт

1. Выставите счет покупателю

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

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

PUT /partner/bill/v1/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"
}

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

/bill/v1/bills/{billId}

с параметрами:

Подробнее о возможных параметрах запроса

В ответ вы получите сообщение со следующими данными:

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

HTTP/1.1 200 OK
Content-Type: application/json

{
    "siteId": "23044",
    "billId": "893794793973",
    "amount": {
      "value": 100.00,
      "currency": "RUB"
    },
    "status": {
      "value": "WAITING",
      "changedDateTime": "2018-03-05T11:27:41+03:00"
    },
    "comment": "Test",
    "creationDateTime": "2018-03-05T11:27:41",
    "expirationDateTime": "2018-04-13T14:30:00+03:00",
    "payUrl": "https://oplata.qiwi.com/form/?invoice_uid=d875277b-6f0f-445d-8a83-f62c7c07be77"
}
Поле ответа Тип Описание
billId String Уникальный идентификатор счета в вашей системе
siteId String Идентификатор вашего сайта в QIWI Кассе
amount Object Информация о сумме счета
amount.value Number Сумма счета, округленная до 2 знаков после запятой в меньшую сторону
amount.currency String Идентификатор валюты счета (Alpha-3 ISO 4217 код: RUB, USD, EUR)
status Object Информация о статусе счета
status.value String Текущий статус счета
status.changedDateTime String Дата обновления статуса. Формат даты:
YYYY-MM-DDThh:mm:ss±hh
customFields Object Дополнительные поля
customer Object Идентификаторы пользователя. Возможные опции: email, phone, account
comment String Комментарий к счету
creationDateTime String Системная дата создания счета. Формат даты:
YYYY-MM-DDThh:mm:ss
payUrl String Ссылка на созданную платежную форму
expirationDateTime String Срок действия созданной формы для оплаты. Формат даты:
YYYY-MM-DDThh:mm:ss+\-hh:mm

Перенаправьте покупателя по ссылке, указанной в поле payUrl ответа.

2. Дождитесь уведомления об оплате

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

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

{
  "payment": {
    "paymentId":"9999999",
    "type":"PAYMENT",
    "createdDateTime":"2019-06-03T08:19:16+03:00",
    "status": {
      "value":"SUCCESS",
      "changedDateTime":"2019-06-03T08:19:16+03:00"
    },
    "amount": {
      "value":111.11,
      "currency":"RUB"},
    "paymentMethod": {
      "type":"CARD",
      "cardHolder":"CARD HOLDER",
      "cardExpireDate":"1/2025",
      "maskedPan":"411111******0001"},
    "gatewayData": {
      "type":"ACQUIRING",
      "authCode":"181218",
      "rrn":"123"
    },
    "customer": {},
    "billId":"f1e1a1f11ae111a11a111111e1111111",
    "flags": ["SALE"]
  },
  "type":"PAYMENT",
  "version":"1"
}
Поле уведомления Тип Описание
paymentId String Уникальный идентификатор платежа в вашей системе
type String Тип операции PAYMENT
createdDateTime String Системная дата создания платежа. Формат даты:
YYYY-MM-DDThh:mm:ss±hh
amount Object Информация о сумме платежа
amount.value Number Сумма платежа, округленная до 2 знаков после запятой в меньшую сторону
amount.currency String Валюта платежа (Alpha-3 ISO 4217 код: RUB, USD, EUR)
status Object Информация о статусе платежа
status.value String Текущий статус платежа
status.changedDateTime String Дата обновления статуса. Формат даты:
YYYY-MM-DDThh:mm:ss±hh
paymentMethod Object Информация о средстве платежа
paymentMethod.type String Тип средства платежа. Возможные значения: TOKEN,CARD
paymentMethod.maskedPan String Маскированный PAN карты
paymentMethod.cardHolder String Имя владельца карты
paymentMethod.expityDate String Дата истечения действия срока карты
gatewayData String Данные платежного шлюза
gatewayData.type String Тип шлюза. Возможные значения: ACQUIRING
gatewayData.authcode String Код авторизации
gatewayData.rrn String Значение RRN (ISO 8583)
customFields Object Дополнительные поля
customer Object Идентификаторы пользователя. Возможные опции: email, phone, account, ip
billId String Идентификатор счета
flags Array of strings Флаги операции: SALE - одношаговый сценарий

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

Платежная форма

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

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

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

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

https://oplata.qiwi.com/form?invoiceUid=606a5f75-4f8e-4ce2-b400-967179502275&successUrl=https://developer.qiwi.com/ru/payments/#introduction
Параметр Описание Тип
successUrl URL для переадресации в случае успешной оплаты. Переадресация произойдет после успешной 3DS аутентификации. Ссылку необходимо зашифровать в utf-8 формат. URL-закодированная строка

Персонализация

Персонализация позволяет адаптировать платежную форму под ваш стиль. Настраивается лого, фон и цвет кнопок.

Создать стили можно обратившись в поддержку по адресу payin@qiwi.com. При настройке задается имя параметра (например, кодСтиля), привязанное к стилю.

Для использования стиля на платежной форме необходимо передать в параметре customFields запроса создания счета переменную с заданным именем параметра: "themeCode":"кодСтиля".

Пример передачи параметра

PUT /partner/bill/v1/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":"кодСтиля"}
}

Customer form

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

Как использовать Popup SDK:

  1. Выставить счет
  2. Открыть счет с помощью Checkout Popup SDK

Скачать библиотеку QIWI Checkout Popup

Установка и подключение SDK:

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

Открытие счета

Метод QiwiCheckout.openInvoice

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

params = {
    payUrl: 'https://oplata.qiwi.com/form?invoiceUid=06df838c-0f86-4be3-aced-a950c244b5b1'
}

QiwiCheckout.openInvoice(params)
    .then(data => {
        // ...
    })
    .catch(error => {
        // ...
    })
Параметр Описание Тип Обязательное
payUrl URL счета, указанная в поле payUrl ответа на запрос выставления счета String +

Дополнительно

Двухшаговый сценарий

Двухшаговый сценарий платежа включает в себя следующие шаги: (1) холдирование средств на карте и (2) подтверждение платежа.

1. Выполните холдирование средств

Пример запроса на холдирование:

PUT /partner/bill/v1/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
   },
   "comment": "Spasibo",
   "expirationDateTime": "2019-09-13T14:30:00+03:00",
   "customFields": {},
   "paymentFlags":["AUTH"]
}

Отправьте запрос выставления счета с дополнительным параметром:

"paymentFlags":["AUTH"]

на URL:

/bill/v1/bills/{billId}

Параметр запроса:

Параметры JSON-тела запроса:

Название Тип Описание
amount Object Информация о сумме счета
amount.value Number(6.2) Сумма, на которую выставляется счет, округленная в меньшую сторону до 2 десятичных знаков
amount.currency String Идентификатор валюты счета (Alpha-3 ISO 4217 код: RUB, USD, EUR)
expirationDateTime URL-закодированная строка
YYYY-MM-DDThh:mm:ss±hh		 Дата, до которой счет будет доступен для оплаты. Если счет не будет оплачен до этой даты, ему присваивается финальный статус EXPIRED и последующая оплата станет невозможна
paymentFlags Array of strings Дополнительные платежные флаги
Доступные значения: "AUTH" - выполнить двухшаговый сценарий авторизации средств

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

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": {
        "AUTH": "true"
    },
    "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 ответа вы получите ссылку на платежную форму.

1а. Получите id транзакции для подтверждения

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

{
  "payment":{
    "paymentId":"804900",  <==paymentId, необходимый для capture
    "type":"PAYMENT",
    "createdDateTime":"2019-08-28T12:58:49+03:00",
    "status":{
        "value":"SUCCESS",
        "changedDateTime":"2019-08-28T12:58:53+03:00"
    },
    "amount":{
      "value":1.00,
      "currency":"RUB"
    },
    "paymentMethod":{
      "type":"CARD",
      "maskedPan":"444444XXXXXX4444",
      "rrn":null,
      "authCode":null,
      "type":"CARD"
    },
    "customer":{
      "phone":"75167693659"
    },
    "gatewayData":{
      "type":"ACQUIRING",
      "eci":"6",
      "authCode":"181218"
    },
    "billId":"autogenerated-a51d0d2c-6c50-405d-9305-bf1c13a5aecd",
    "flags":[]
  },
  "type":"PAYMENT",
  "version":"1"
}

После того, как платеж успешно совершен, вам придет серверное уведомление.

Для подтверждения операции (capture) вам необходим параметр paymentId из уведомления.

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

2. Подтвердите операцию

Используя номер операции (paymentId), выполните capture - подтверждение операции.

Отправьте PUT-запрос c пустым телом на URL:

/payin/v1/sites/{siteId}/payments/{paymentId}/captures/{captureId}

где:

Подробнее о возможных параметрах запроса

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

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

1. Авторизуйте платеж

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

/payin/v1/sites/{siteId}/payments/{paymentId}

с параметрами:

Подробнее о возможных параметрах запроса

В ответе вы получите следующие данные:

Пример тела ответа с требованием 3DS

{
    "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"
        }
    }
}
Поле ответа Тип Описание
paymentId String Уникальный идентификатор платежа в вашей системе, такой же как в запросе
createdDateTime String Системная дата создания платежа. Формат даты:
YYYY-MM-DDThh:mm:ss+hh:ss
amount Object Информация о сумме платежа
amount.value Number Сумма платежа, округленная до 2 знаков после запятой в меньшую сторону
amount.currency String Валюта платежа (Alpha-3 ISO 4217 код)
status Object Информация о статусе платежа
status.value String Текущий статус платежа
status.changedDateTime String Дата обновления статуса. Формат даты:
YYYY-MM-DDThh:mm:ss±hh

Чаще всего для создания платежа вам понадобится пройти дополнительную аутентификацию. Такое может произойти, если:

Если необходима дополнительная аутентификация клиента, в ответе вы получите дополнительный объект requirements c полями:

2. (опционально) Завершите аутентификацию клиента

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

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

/payin/v1/sites/{siteId}/payments/{paymentId}/complete

и укажите параметры:

Подробнее о возможных параметрах запроса

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

Используя номер операции (paymentId), выполните capture - подтверждение операции.

Отправьте PUT-запрос c пустым телом на URL:

/payin/v1/sites/{siteId}/payments/{paymentId}/captures/{captureId}

где:

Подробнее о возможных параметрах запроса

Пример подтверждения

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

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

Протокол поддерживает 3 типа уведомлений о событиях API: PAYMENT, CAPTURE и REFUND. Уведомления отправляются при совершении операций платежа, подтверждения платежа и возврата платежа, соответственно.

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

Укажите адрес сервера для обработки уведомлений в Личном Кабинете на сайте kassa.qiwi.com в разделе "Настройки". Можно также указывать адрес сервера в опциональном параметре callbackUrl в запросах к API.

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

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

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

Авторизация уведомлений

HTTP-заголовок Signature уведомлений содержит цифровую подпись, которую вам необходимо проверить.

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

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

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

    parameters = {amount.currency}|{amount.value}|{billId}|{siteId}|{status.value}

    где {*} – значение параметра уведомления. Все значения при проверке подписи должны трактоваться как строки. Параметры для расчета подписи указаны ниже в описании формата уведомлений.

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

    hash = HMAС(SHA256, token, parameters) Где:

    • token – ключ функции (UTF-8), который можно получить в Личном Кабинете на сайте kassa.qiwi.com в разделе "Настройки";
    • parameters – строка из п.1 (UTF-8);

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

Уведомления PAYMENT, CAPTURE, REFUND

Тип уведомления указан в поле type.

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

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

{
   "payment/refund/capture":{
      "paymentId/refundId/captureId":"4504751",
      "tokenData":{
         "paymentToken":"4cc975be-483f-8d29-2b7de3e60c2f",
         "expiredDate":"2021-12-31T00:00:00+03:00"
      },
      "type":"PAYMENT",
      "createdDateTime":"2019-10-08T11:31:37+03:00",
      "status":{
         "value":"SUCCESS",
         "changedDateTime":"2019-10-08T11:31:37+03:00"
      },
      "amount":{
         "value":2211.24,
         "currency":"RUB"
      },
      "paymentMethod":{
         "type":"CARD",
         "maskedPan":"220024/*/*/*/*/*/*5036",
         "rrn":null,
         "authCode":null,
         "type":"CARD"
      },
      "paymentCardInfo": {
         "issuingCountry": "810",
         "issuingBank": "QiwiBank",
         "paymentSystem": "VISA",
         "fundingSource": "CREDIT",
         "paymentSystemProduct": "P|Visa Gold"
      },
      "customer":{
         "ip":"79.142.20.248",
         "account":"token32",
         "phone":"0"
      },
      "billId":"testing122",
      "customFields":{},
      "flags":[
         "SALE"
      ]
   },
   "type":"PAYMENT",
   "version":"1"
}
Полле уведомления Описание Тип
paymentId/refundId/captureId Уникальный идентификатор платежа/возврата/подтверждения в системе ТСП String(200)
type Тип уведомления String(200)
createdDatetime Дата создания операции URL-закодированная строка
ГГГГ-ММ-ДДTЧЧ:ММ:ССZ
amount Информация о сумме операции Object
amount.value Сумма операции, округленная до двух десятичных знаков в меньшую сторону Number(6.2)
amount.currency Идентификатор валюты операции (Alpha-3 ISO 4217 код) String(3)
billId ID счета, соответствующего операции String(200)
status Информация о статусе операции Object
status.value Строковое значение статуса String
status.changedDatetime Дата обновления статуса URL-закодированная строка
ГГГГ-ММ-ДДTЧЧ:ММ:ССZ
status.reasonCode Код причины отклонения String(200)
status.reasonMessage Описание причины отклонения String(200)
status.errorCode Код ошибки Number
paymentMethod Информация о средстве платежа Object
paymentMethod.type Тип метода оплаты String
paymentMethod.maskedPan Маскированный PAN карты String
paymentMethod.rrn RRN платежа (по ISO 8583) Number
paymentMethod.authCode Auth-code платежа Number
paymentCardInfo Информация о карте. Приходит только в уведомлениях PAYMENT Object
paymentCardInfo.issuingCountry Код страны эмитента String(3)
paymentCardInfo.issuingBank Банк-эмитент String
paymentCardInfo.paymentSystem Тип платежной системы String
paymentCardInfo.fundingSource Тип карты String
paymentCardInfo.paymentSystemProduct Категория карты String
customer Информация о пользователе, на которого был выставлен счет Object
customer.phone Номер телефона, на который был выставлен счет (если был указан при выставлении счета) String
customer.email E-mail пользователя (если был указан при выставлении счета) String
customer.account Идентификатор пользователя в системе ТСП (если был указан при выставлении счета) String
customer.ip IP адрес пользователя String
customer.country страна адрес пользователя String
customFields Поля с произвольной информацией, дополняющей данные по операции Object
customFields.cf1 Поле с произвольной информацией, дополняющей данные по операции String(256)
customFields.cf2 Поле с произвольной информацией, дополняющей данные по операции String(256)
customFields.cf3 Поле с произвольной информацией, дополняющей данные по операции String(256)
customFields.cf4 Поле с произвольной информацией, дополняющей данные по операции String(256)
customFields.cf5 Поле с произвольной информацией, дополняющей данные по операции String(256)
tokenData Объект, содержащий данные о выпущенном платежном токене Object
tokenData.paymentToken Строка платежного токена для использования при оплате String
tokenData.expiredDate Дата окончания срока действия платежного токена. Формат даты:
YYYY-MM-DDThh:mm:ss±hh:mm		 String
flags Дополнительные команды для API Массив. Доступные значения - SALE/REVERSAL
version Версия уведомлений String

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

тип PAYMENT: payment.paymentId|payment.createdDateTime|payment.amount.value

тип REFUND: refund.refundId|refund.createdDateTime|refund.amount.value

тип CAPTURE: capture.captureId|capture.createdDateTime|capture.amount.value

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

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

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

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

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

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

Сплитование платежей

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

Как использовать

В тело платежного запроса добавьте JSON-массив paymentSplits, используемый для передачи данных о поставщиках.

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

{
 "paymentMethod": "...",
 "customer": "....",
 "deviceData": "...",
 "paymentSplits": [
   {
     "type":"MERCHANT_DETAILS",
     "siteUid":"shop_mst-01",
     "splitAmount": {
       "value":300.00,
       "currency":643
     },
     "orderId":"dasdad444ll4ll",
     "comment":"flowers for my girlfriend"
  },
  {
    "type":"MERCHANT_DETAILS",
    "siteUid":"shop_mst-02",
    "splitAmount": {
      "value":200.00,
      "currency":643
      },
      "orderId":"sdadada887sdDDDDd",
      "comment":"watermelon"
    }
  ]
}

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

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

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

{
  "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": {
    "type": "CARD",
    "maskedPan": "40000******1111",
    "rrn": "001281453012",
    "authCode": "4EC4W7",
    "type": "CARD"
  },
  "status": {
    "value": "COMPLETED",
    "changedDateTime": "2020-10-12T15:29:14+03:00"
  },
  "paymentCardInfo": {
    "issuingCountry": "643",
    "issuingBank": "Альфа-банк",
    "paymentSystem": "MASTERCARD",
    "fundingSource": "PREPAID",
    "paymentSystemProduct": "Debit"
  },
  "paymentSplits": [
    {
      "type": "MERCHANT_DETAILS",
      "siteUid": "shop_mst-01",
      "splitAmount": {
        "currency": "RUB",
        "value": "30.00",
      },
      "splitCommissions": {
        "merchantCms": {
          "currency": "RUB",
          "value": "10.00"
        }
      },
      "orderId": "313fh1f23j13k1k",
      "comment": "i want to buy some goods"
    },
    {
      "type": "MERCHANT_DETAILS",
      "siteUid": "shop_mst-02",
      "splitAmount": {
        "currency": "RUB",
        "value": "20.00"
      },
      "splitCommissions": {
        "merchantCms": {
          "currency": "RUB",
          "value": "10.00"
        }
      },
      "orderId": "sdadada887sdDDDDd",
      "comment": "watermelon"
    },
    {
      "type": "MERCHANT_DETAILS",
      "siteUid": "shop_mst-03",
      "splitAmount": {
        "currency": "RUB",
        "value": "50.00"
      },
      "splitCommissions": {
        "merchantCms": {
          "currency": "RUB",
          "value": "10.00"
        }
      },
      "orderId": "dasdad444ll4ll",
      "comment": "flowers for my girlfriend"
    }
  ]
 }

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

Поле ответа Тип Описание
paymentSplits Array Массив с данными о принятых платежах
type String Тип передаваемых данных. Всегда возвращается строка MERCHANT_DETAILS
siteUid String ID поставщика
splitAmount Object Данные о возмещении поставщику
value Number Сумма возмещения
currency Number Код валюты возмещения по ISO
splitCommissions Object Данные о комиссии (необязательный)
merchantCms Object Данные о комиссии с поставщика
value Number Сумма комиссии
currency Number Код валюты комиссии по 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": "watermelon"
  },
  {
    "type": "MERCHANT_DETAILS",
    "siteUid": "shop_mst-02",
    "splitAmount": {
      "value": 20.00,
      "currency": "RUB"
    },
   
    "orderId": "313fh1f23j13k1k",
    "comment": "i want to buy some goods"
  },
  {
    "type": "MERCHANT_DETAILS",
    "siteUid": "shop_mst-03",
    "splitAmount": {
      "value": 50.00,
      "currency": "RUB"
    },
    "orderId": "dasdad444ll4ll",
    "comment": "flowers for my girlfriend"
  }
  ]
}

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

{
    "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": "watermelon"
        },
        {
            "type": "MERCHANT_DETAILS",
            "siteUid": "shop_mst-01",
            "splitAmount": {
                "currency": "RUB",
                "value": "30.00"
            },
            "splitCommissions": {
                "merchantCms": {
                    "currency": "RUB",
                    "value": "10.00"
                }
            },
            "orderId": "313fh1f23j13k1k",
            "comment": "i want to buy some goods"
        },
        {
            "type": "MERCHANT_DETAILS",
            "siteUid": "shop_mst-03",
            "splitAmount": {
                "currency": "RUB",
                "value": "50.00"
            },
            "splitCommissions": {
                "merchantCms": {
                    "currency": "RUB",
                    "value": "10.00"
                }
            },
            "orderId": "dasdad444ll4ll",
            "comment": "flowers for my girlfriend"
        }
    ]
}

В тело запроса на создание возврата добавьте JSON-массив refundSplits, используемый для передачи данных о возвратах поставщикам.

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

Название Тип Описание
refundSplits Array Массив данных о возвратах поставщикам
type String Тип передаваемых данных. Доступные значения - MERCHANT_DETAILS (данные поставщика)
siteUid String ID поставщика
splitAmount Object Данные об отмене возмещения поставщику
value Number Сумма отмены возмещения
currency Number Код валюты отмены возмещения по ISO. Доступен только 643
orderId String Номер заказа (необязательный)
comment String Комментарий к заказу (необязательный)

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

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

Apple Pay

Apple Pay позволяет покупателям оплачивать покупки на сайте в одно касание, без ввода данных карты. Технология работает в мобильных приложениях и браузере Safari на iPhone, iPad, Apple Watch и MacBook. Для включения метода оплаты Apple Pay необходимо обратиться к вашему сопровождающему менеджеру.

Вам понадобится самостоятельно выполнить интеграцию с Apple. Это позволит верифицировать сайт ТСП и получать платежные данные пользователя. Требования к ТСП для интеграции Apple Pay на веб-странице:

Более подробно об интеграции можно узнать на сайте Apple.

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

Пример объекта external3dSecData

"external3dSecData": {
  "cavv": "AOLqt9wP++/WAzN+is7YAoABFA==",
  "eci": "05"
}

Пример платежного запроса с передачей криптограммы Apple

{
  "paymentMethod": {
    "type": "CARD",
    "pan": "4444443616621049",
    "expiryDate": "12/19",
    "holderName": "Apple pay",
    "external3dSecData": {
      "cavv": "AOLqt9wP++YAoABFA==",
      "eci": "05"
    }
  },
  "amount": {
    "value": "5900.00",
    "currency": "RUB"
  },
  "flags": [
    "SALE"
  ],
  "customer": {
    "account": "79111111111",
    "email": "test@qiwi.com",
    "phone": "79111111111"
  }
}

Процесс выполнения платежа Apple Pay в API состоит из четырех этапов:

  1. Создание платежной сессии Apple Pay и валидация ТСП в Apple Pay
  2. Получение зашифрованных платежных данных из Apple Pay
  3. Расшифровка платежных данных на стороне ТСП
  4. Отправка запроса на списание средств с добавленной криптограммой Apple в QIWI

Для отправки платежных данных в QIWI необходимо в платежном запросе передать в объекте paymentMethod тела запроса дополнительный JSON-объект external3dSecData, содержащий платежные данные от Apple:

Оплата по токену карты

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

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

Для использования платежных токенов вам необходимо два идентификатора siteId и токена API - один для выпуска платежных токенов (как правило, с поддержкой 3DS), второй для оплаты платежным токеном.

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

Чтобы выпустить платежный токен, используйте идентификаторы сайта (siteId, токен API), зарегистрированного для выпуска платежных токенов.

Если вы используете Платежную форму

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

PUT /partner/bill/v1/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": {}, 
   "paymentFlags":["BIND_PAYMENT_TOKEN"] 
}

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

{
  "payment":
  {
    "paymentId":"9790769",
    "tokenData": {
      "paymentToken":"66aebf5f-098e-4e36-922a-a4107b349a96",
      "expiredDate":"2021-12-31T00:00:00+03:00"
    },
    "type":"PAYMENT",
    "createdDateTime":"2020-01-23T15:07:35+03:00",
    "status": {
      "value":"SUCCESS",
      "changedDateTime":"2020-01-23T15:07:36+03:00"
    },
    "amount": {
      "value":2211.24,
      "currency":"RUB"
    },
    "paymentMethod": {
      "type":"CARD",
      "maskedPan":"4111111111",
      "cardHolder":"CARD HOLDER",
      "cardExpireDate":"12/2021",
      "type":"CARD"
    },
    "customer": {
      "ip":"79.142.20.248",
      "account":"token324",
      "phone":"0"
    },
    "billId":"testing1222213",
    "flags":["SALE"]
  },
  "type":"PAYMENT",
  "version":"1"
}

Укажите в запросе выставления счета дополнительные параметры:

После оплаты счета в уведомлении PAYMENT вы получите данные платежного токена:

Поле уведомления Тип данных Описание
tokenData Object Объект, содержащий данные о выпущенном платежном токене
tokenData.paymentToken String Строка платежного токена для использования при оплате
tokenData.expiredDate String Дата окончания срока действия платежного токена. Формат даты:
YYYY-MM-DDThh:mm:ss±hh:mm

Если вы используете 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": 2211.24
   },
   "customer": {
   	"account":"token324"
   },
   "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": "10.00"
    },
    "capturedAmount": {
        "currency": "RUB",
        "value": "0.00"
    },
    "refundedAmount": {
        "currency": "RUB",
        "value": "0.00"
    },
    "paymentMethod": {
        "type": "CARD",
        "maskedPan": "411111******1111",
        "rrn": "123",
        "authCode": "181218",
        "type": "CARD"
    },
    "createdToken": {
        "token": "27e61f2f-19e1-4fd7-a3c8-fd84508d21ab",
        "name": "411111******1111"
    },
    "customer": {
        "account": "1",
        "phone": "79022222222"
    },
    "status": {
        "value": "COMPLETED",
        "changedDateTime": "2020-03-26T12:22:12+03:00"
    },
    "customFields": {
        "customer_account": "1",
        "customer_phone": "79022222222"
    },
    "flags": [
        "TEST"
    ]
}

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

В ответе на запрос вы получите данные платежного токена:

Поле Тип данных Описание
createdToken Object Данные платежного токена
createdToken.token String Строка платежного токена для использования при оплате
createdToken.name String Маскированный номер карты, для которой выпущен платежный токен

Также данные платежного токена придут в уведомлении PAYMENT (см. описание выше).

Процесс оплаты токеном

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

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" : "f42abb6c-4b6b-464e-adcc-fbdc197bd24d"
  },
  "customer": {
        "account": "token324"
  }
}

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

Для этого в платежном запросе:

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

Оплата с баланса КИВИ Кошелька

Создание платежа с баланса КИВИ Кошелька возможно только с помощью платежной формы КИВИ.

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

{
   "amount": {  
     "currency": "RUB",  
     "value": 1.00
   },
   "expirationDateTime": "2020-10-16T14:30:00+03:00"
}

Возможность приема платежей с КИВИ Кошелька должна быть настроена технически на стороне КИВИ. Данные настройки можно произвести при подключении либо через вашего менеджера по сопровождению.

Для приема платежей с КИВИ Кошелька используйте метод Создание счета. Отправьте PUT-запрос на URL:

/bill/v1/bills/{billId}

Ответ сервера

{
    "siteId": "site-01",
    "billId": "89379",
    "amount": {
        "currency": "RUB",
        "value": "1.00"
    },
    "status": {
        "value": "WAITING",
        "changedDateTime": "2020-10-12T12:46:29.452+03:00"
    },
    "creationDateTime": "2020-10-12T12:46:29.452+03:00",
    "expirationDateTime": "2020-10-16T14:30:00+03:00",
    "payUrl": "https://oplata.qiwi.com/form/?invoice_uid=d875277b-6f0f-445d-8a83-f62c7c07be77"
}

В ответе придет ссылка на платежную форму (см. поле payUrl). На платежной форме пользователю будет доступен способ оплаты с баланса КИВИ Кошелька.

Процесс оплаты выглядит следующим образом:

  1. Пользователь открывает форму.

    Wallet Invoice

  2. Пользователь авторизуется в КИВИ Кошельке.

    Wallet Auth

  3. Пользователь оплачивает счет.

    Wallet Pay

Уведомление REFUND

{
  "refund":
  {
    "refundId":"1",
    "type":"REFUND",
    "createdDateTime":"2020-10-12T13:08:13+03:00",
    "status":{
      "value":"SUCCESS",
      "changedDateTime":"2020-10-12T13:08:14+03:00"
    },
    "amount":{
      "value":1.00,
      "currency":"RUB"
    },
    "paymentMethod":{
      "type":"QIWI_WALLET",
      "phone":"79022672222"
    },
    "customer":{
      "phone":"0"
    },
    "gatewayData":{
      "type":"QW",
      "walletTxnId":"19990706195"
    },
    "billId":"89379",
    "flags":[]
  },
  "type":"REFUND",
  "version":"1"
}

Возвраты выполняются с помощью метода API Операция возврата. В случае успешного возврата вам придет уведомление REFUND.

Возмещение

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

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

Тестовые данные

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

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

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

В режиме тестирования из валют (параметр currency) разрешен только рубль РФ (643).

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

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

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

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

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

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

{
   "amount": {  
     "currency": "RUB",  
     "value": 100.00
   },
   "comment": "Text comment",
   "expirationDateTime": "2018-04-13T14:30:00+03:00",
   "customer": {},
   "customFields": {}  
   }
}

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

{
  "serviceName" : "payin-core",
  "errorCode" : "validation.error",
  "description" : "Validation error",
  "userMessage" : "Validation error",
  "dateTime" : "2018-11-13T16:49:59.166+03:00",
  "traceId" : "fd0e2a08c63ace83"
  }
}

Статус счета

[
    {
        "paymentId": "12600406",
        "billId": "d35cf63943e54f50badc75f49a5aac7c",
        "createdDateTime": "2020-03-26T19:31:49+03:00",
        "amount": {
            "currency": "RUB",
            "value": 10.00
        },
        "capturedAmount": {
            "currency": "RUB",
            "value": 10.00
        },
        "refundedAmount": {
            "currency": "RUB",
            "value": 0.00
        },
        "paymentMethod": {
            "type": "CARD",
            "maskedPan": "427638******1410",
            "type": "CARD"
        },
        "createdToken": {
            "token": "c5ba4a05-21c9-4a36-af7a-b709b4caa4d6",
            "name": "427638******1410"
        },
        "customer": {
            "account": "1",
            "phone": "0",
            "address": {}
        },
        "requirements": {
            "threeDS": {
                "pareq": "eJxVUWFvgjAQX7gM3fq+hNqO0oI5prexilN1UDEMwl6FcHZZ19m7v63DtRY=",
                "acsUrl": "https://ds1.mirconnect.ru:443/vbv/pareq"
            }
        },
        "status": {
            "value": "DECLINED",
            "changedDateTime": "2020-03-26T19:32:09+03:00",
            "reason": "ACQUIRING_NOT_PERMITTED"
        },
        "customFields": {
            "customer_account": "1",
            "customer_phone": "0"
        }
    },
    {
        "paymentId": "12600433",
        "billId": "d35cf63943e54f50badc75f49a5aac7c",
        "createdDateTime": "2020-03-26T19:32:22+03:00",
        "amount": {
            "currency": "RUB",
            "value": 10.00
        },
        "capturedAmount": {
            "currency": "RUB",
            "value": 10.00
        },
        "refundedAmount": {
            "currency": "RUB",
            "value": 0.00
        },
        "paymentMethod": {
            "type": "CARD",
            "maskedPan": "427638******1410",
            "type": "CARD"
        },
        "createdToken": {
            "token": "c5ba4a05-21c9-4a36-af7a-b709b4caa4d6",
            "name": "427638******1410"
        },
        "customer": {
            "account": "1",
            "phone": "0",
            "address": {}
        },
        "requirements": {
            "threeDS": {
                "pareq": "eJxVUWFvgjAQ52lBUtjD3M9++qFgCxl0i/OtJv2WT/tv8LXqG0vw==",
                "acsUrl": "https://ds1.mirconnect.ru:443/vbv/pareq"
            }
        },
        "status": {
            "value": "DECLINED",
            "changedDateTime": "2020-03-26T19:32:54+03:00",
            "reason": "ACQUIRING_NOT_PERMITTED"
        },
        "customFields": {
            "customer_account": "1",
            "customer_phone": "0"
        }
    },
    {
        "paymentId": "12601084",
        "billId": "d35cf63943e54f50badc75f49a5aac7c",
        "createdDateTime": "2020-03-26T19:46:21+03:00",
        "amount": {
            "currency": "RUB",
            "value": 10.00
        },
        "capturedAmount": {
            "currency": "RUB",
            "value": 10.00
        },
        "refundedAmount": {
            "currency": "RUB",
            "value": 0.00
        },
        "paymentMethod": {
            "type": "CARD",
            "maskedPan": "427638******1410",
            "rrn": "008692274763",
            "authCode": "242847",
            "type": "CARD"
        },
        "createdToken": {
            "token": "c5ba4a05-21c9-4a36-af7a-b709b4caa4d6",
            "name": "427638******1410"
        },
        "customer": {
            "account": "1",
            "phone": "0",
            "address": {}
        },
        "requirements": {
            "threeDS": {
                "pareq": "eJxVUdtuwjAM7b6t/1fcku04w==",
                "acsUrl": "https://ds1.mirconnect.ru:443/vbv/pareq"
            }
        },
        "status": {
            "value": "COMPLETED",
            "changedDateTime": "2020-03-26T19:46:43+03:00"
        },
        "customFields": {
            "customer_account": "1",
            "customer_phone": "0"
        },
        "flags": [
            "AFT"
        ]
    }
]

{
  "serviceName" : "payin-core",
  "errorCode" : "validation.error",
  "description" : "Validation error",
  "userMessage" : "Validation error",
  "dateTime" : "2018-11-13T16:49:59.166+03:00",
  "traceId" : "fd0e2a08c63ace83"
}

Платеж

{
  "billId": "string",
  "amount": {
    "currency": "RUB",
    "value": 200.00
  },
  "paymentMethod" : {
    "type" : "CARD",
    "pan" : "4444443616621049",
    "expiryDate" : "12/19",
    "cvv2" : "123",
    "holderName" : "CARDHOLDER NAME"
  },
  "callbackUrl": "https://example.com/callbacks",
  "comment": "Example payment",
  "customer": {
    "account": "string",
    "address": {
      "city": "Moscow",
      "country": "Russian Federation",
      "details": "Severnoe chertanovo microdistrict 1a 1",
      "region": "Moscow city"
    },
    "email": "customer@example.com",
    "phone": "+79991234567"
  },
  "deviceData": {
    "datetime": "2017-09-03T14:30:00+03:00",
    "fingerprint": "TW96aWxsYS81LjAgKHBsYXRmb3JtOyBydjpnZWNrb3ZlcnNpb24p",
    "ip": "127.0.0.1",
    "screenResolution": "1280x1024",
    "timeOnPage": 1440,
    "userAgent": "Mozilla/5.0 (platform; rv:geckoversion) Gecko/geckotrail Firefox/firefoxversion"
  },
  "customFields": {},
  "flags": [
    "SALE"
  ]
}

{
  "paymentId" : "223E",
  "createdDatetime" : "2018-11-01T17:10:31.284+03:00",
  "amount" : {
    "currency" : "RUB",
    "value" : 200.00
  },
  "capturedAmount" : {
    "currency" : "RUB",
    "value" : 0.00
  },
  "refundedAmount" : {
    "currency" : "RUB",
    "value" : 0.00
  },
  "paymentMethod" : {
    "type" : "CARD",
    "maskedPan" : "444444******1049"
  },
  "customer" : { },
  "deviceData" : { },
  "requirements" : {
    "threeDS" : {
      "pareq" : "eJyrrgUAAXUA+Q==",
      "acsUrl" : "https://test.paymentgate.ru/acs/auth/start.do"
    }
  },
  "status" : {
    "value" : "WAITING",
    "changedDateTime" : "2018-11-01T17:10:32.607+03:00"
  },
  "paymentCardInfo": {
    "issuingCountry": "810",
    "issuingBank": "QiwiBank",
    "paymentSystem": "VISA",
    "fundingSource": "CREDIT",
    "paymentSystemProduct": "P|Visa Gold"
  },
  "customFields" : { },
  "flags" : [ ]
}

{
  "serviceName" : "payin-core",
  "errorCode" : "validation.error",
  "description" : "Validation error",
  "userMessage" : "Validation error",
  "dateTime" : "2018-11-13T16:49:59.166+03:00",
  "traceId" : "fd0e2a08c63ace83"
}

{
  "serviceName":"payin-core",
  "errorCode":"internal.error",
  "userMessage":"Internal error",
  "description":"Internal error",
  "traceId":"3fb3420ee1795dcf",
  "dateTime":"2020-02-12T21:28:01.813+03:00"
}

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

{
  "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"
  },
  "customFields" : { },
  "flags" : [ ]
}

{
  "serviceName" : "payin-core",
  "errorCode" : "validation.error",
  "description" : "Validation error",
  "userMessage" : "Validation error",
  "dateTime" : "2018-11-13T16:49:59.166+03:00",
  "traceId" : "fd0e2a08c63ace83"
}

{
  "serviceName":"payin-core",
  "errorCode":"internal.error",
  "userMessage":"Internal error",
  "description":"Internal error",
  "traceId":"3fb3420ee1795dcf",
  "dateTime":"2020-02-12T21:28:01.813+03:00"

}

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

{
  "threeDS": {
    "pares": "eJzVWFevo9iyfu9fMZrzaM0QjWHk3tIiGptgooE3cgabYMKvv3jvTurTc3XOfbkaJMuL...."
  },
  "cvv2": {
    "cvv2": "string"
  }
}

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

{
  "serviceName" : "payin-core",
  "errorCode" : "validation.error",
  "description" : "Validation error",
  "userMessage" : "Validation error",
  "dateTime" : "2018-11-13T16:49:59.166+03:00",
  "traceId" : "fd0e2a08c63ace83"
}

{
  "serviceName":"payin-core",
  "errorCode":"internal.error",
  "userMessage":"Internal error",
  "description":"Internal error",
  "traceId":"3fb3420ee1795dcf",
  "dateTime":"2020-02-12T21:28:01.813+03:00"

}

Подтверждение покупки

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

{
  "serviceName" : "payin-core",
  "errorCode" : "validation.error",
  "description" : "Validation error",
  "userMessage" : "Validation error",
  "dateTime" : "2018-11-13T16:49:59.166+03:00",
  "traceId" : "fd0e2a08c63ace83"
}

{
  "serviceName":"payin-core",
  "errorCode":"internal.error",
  "userMessage":"Internal error",
  "description":"Internal error",
  "traceId":"3fb3420ee1795dcf",
  "dateTime":"2020-02-12T21:28:01.813+03:00"

}

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

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

{
  "serviceName" : "payin-core",
  "errorCode" : "validation.error",
  "description" : "Validation error",
  "userMessage" : "Validation error",
  "dateTime" : "2018-11-13T16:49:59.166+03:00",
  "traceId" : "fd0e2a08c63ace83"
}

{
  "serviceName":"payin-core",
  "errorCode":"internal.error",
  "userMessage":"Internal error",
  "description":"Internal error",
  "traceId":"3fb3420ee1795dcf",
  "dateTime":"2020-02-12T21:28:01.813+03:00"
}

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

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

{
  "serviceName" : "payin-core",
  "errorCode" : "validation.error",
  "description" : "Validation error",
  "userMessage" : "Validation error",
  "dateTime" : "2018-11-13T16:49:59.166+03:00",
  "traceId" : "fd0e2a08c63ace83"
}

{
  "serviceName":"payin-core",
  "errorCode":"internal.error",
  "userMessage":"Internal error",
  "description":"Internal error",
  "traceId":"3fb3420ee1795dcf",
  "dateTime":"2020-02-12T21:28:01.813+03:00"

}

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

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

{
  "serviceName" : "payin-core",
  "errorCode" : "validation.error",
  "description" : "Validation error",
  "userMessage" : "Validation error",
  "dateTime" : "2018-11-13T16:49:59.166+03:00",
  "traceId" : "fd0e2a08c63ace83"
}

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

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

{
  "serviceName" : "payin-core",
  "errorCode" : "validation.error",
  "description" : "Validation error",
  "userMessage" : "Validation error",
  "dateTime" : "2018-11-13T16:49:59.166+03:00",
  "traceId" : "fd0e2a08c63ace83"
}

{
  "serviceName":"payin-core",
  "errorCode":"internal.error",
  "userMessage":"Internal error",
  "description":"Internal error",
  "traceId":"3fb3420ee1795dcf",
  "dateTime":"2020-02-12T21:28:01.813+03:00"
}

Причины отклонения

Причины отклонения передаются в ответах на запросы в поле status.reason и в поле status.reasonCode уведомления.

Причина отклонения Описание
INVALID_STATE Некорректный статус транзакции
INVALID_AMOUNT Некорректная сумма
DECLINED_BY_MPI Отклонено MPI
DECLINED_BY_FRAUD Отклонено fraud-мониторингом
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 Ошибка при проведении платежа

Коды ошибок

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