API. Общие сведения¶
Раздел API документирует реализацию RESTful API для приёма платежей в рамках продукта Интернет-эквайринг.
Формат взаимодействия¶
API приёма платежей основан на принципах REST-архитектуры. Данные и методы считаются ресурсами, которые доступны через вызов универсальных идентификаторов ресурсов (URI).
Взаимодействие по API совершается по защищённому протоколу (HTTPS). Поддерживаются только HTTPS-запросы. HTTP-запросы по нешифрованному каналу не поддерживаются. Данные в запросах передаются в формате JSON в кодировке UTF-8. В ответах данные возвращаются также в формате JSON в кодировке UTF-8.
Методы API обеспечивают логическую идемпотентность, т. е. многократный вызов метода эквивалентен однократному. Однако ответ сервера может меняться: например, состояние счёта может меняться от запроса к запросу.
URL для вызовов API¶
Постоянная часть URL-адреса для вызова методов API:
https://b2b-api.qiwi.com/partner/payin/
Авторизация¶
Авторизация запросов к API выполняется по стандарту OAuth 2.0 согласно RFC 6750. Указывайте значение ключа доступа к API в HTTP-заголовке Authorization как
Bearer <Ключ API>
Пример запроса с авторизацией:
curl -X PUT \
https://b2b-api.qiwi.com/partner/payin/v1/sites/{site_id}/payments/{payment_id} \
--oauth2-bearer <Ключ API>
Пример заголовка авторизации:
Authorization: Bearer 5c4b25xx93aa435d9cb8cd17480356f9
Формат значений¶
Адрес¶
Данные передаются в объекте address.
| Параметр | Обязательный | Тип | Описание |
|---|---|---|---|
| country | Нет | string(1000) | Страна |
| city | Нет | string(1000) | Город |
| region | Нет | string(1000) | Округ, регион, область, штат |
| details | Нет | string(1000) | Адрес местонахождения (улица, дом) |
Дата и время¶
API принимает и возвращает значения даты и времени в формате ISO 8601 с временной зоной. Пример: 2023-08-13T14:30:00+03:00
Данные для 3D-Secure¶
Данные для аутентификации банковских карт по протоколам 3DS и 3DS2.0 передаются в объекте threeDS.
| Параметр | Обязательный | Тип | Описание | Где используется |
|---|---|---|---|---|
| pareq | Да | string | Аутентификационное сообщение для передачи в ACS банка-эмитента через браузер покупателя | Возвращается в ответах на запросы «Получение информации о счёте», «Создание платежа», «Завершение аутентификации покупателя» и “Проверка карты“ |
| acsUrl | Да | string | URL ACS сервера банка-эмитента, куда следует перенаправить покупателя | Возвращается в ответах на запросы «Получение информации о счёте», «Создание платежа», «Завершение аутентификации покупателя» и “Проверка карты“ |
| pares | Да | string | Результат аутентификации Покупателя, полученный после его возврата с ACS банка-эмитента | Передаётся в теле запроса «Завершение аутентификации покупателя», а также возвращается в ответе на запрос «Завершение аутентификации при проверке карты» |
Данные для генерации платёжного токена¶
Данные для генерации платёжного токена передаются в объекте tokenizationData запроса «Проверка карты».
| Параметр | Обязательный | Тип | Описание |
|---|---|---|---|
| account | Да | string(64) | Уникальный идентификатор покупателя в системе ТСП. Необходим для генерации платежного токена карты |
Информация о возврате по QR-коду¶
Информация о возврате по QR-коду передаётся в объекте refunds ответа на запрос создания QR-кода СБП (только для type=DYNAMIC).
| Параметр | Обязательный | Тип | Описание |
|---|---|---|---|
| refundUid | Да | string | Идентификатор возврата |
| refundStatus | Да | string | Текущий статус возврата |
| gatewayRefundId | Нет | string | Идентификатор возврата шлюза |
| declineReason | Нет | string | Причина отклонения операции |
Информация о платеже по QR-коду¶
Информация о платеже по QR-коду передаётся в объекте payment ответа на запрос создания QR-кода СБП (только для type=DYNAMIC).
| Параметр | Обязательный | Тип | Описание |
|---|---|---|---|
| paymentUid | Да | string | Идентификатор платежа. Данный идентификатор используется для возврата по методу API |
| paymentStatus | Да | string | Текущий статус платежа |
| declineReason | Нет | string | Причина отклонения операции |
Информация о транзакции привязки карты¶
Сведения об идентификаторе транзакции, в которой была привязана карта. Передаются в объекте paymentMethod.firstTransaction.
| Параметр | Обязательный | Тип | Описание |
|---|---|---|---|
| paymentId | Нет | string | Уникальный идентификатор платежа в информационной системе ТСП |
| trnId | Нет | string | Уникальный идентификатор платежа в информационной системе НСПК |
Метод платежа¶
Метод платежа передаётся в объекте paymentMethod.
| Параметр | Обязательный | Тип | Описание |
|---|---|---|---|
| type | Да | string | Тип платежного метода. CARD — Банковская карта TOKEN — Платёжный токен |
| pan | Нет | string(19) | Номер банковской карты.Только для type=CARD |
| maskedPan | Нет | string(19) | Маскированный номер банковской карты.Только для type=CARD |
| expiryDate | Нет | string(5) | Срок действия банковской карты в формате MM/YY.Только для type=CARD |
| cvv2 | Нет | string(4) | CVV2/CVC2 на банковской карте.Только для type=CARD |
| holderName | Нет | string(26) | Имя, указанное на банковской карте (латинские буквы).Только для type=CARD |
| paymentToken | Нет | string | Платёжный токен.Только для type=TOKEN |
| cardTokenPaymentType | Нет | string | Параметр для корректной обработки транзакций в платёжных системах для операций с сохраненными картами. Возможные значения |
| firstTransaction | Нет | object | Сведения об идентификаторе транзакции, в которой была привязана карта.Для type=CARD, TOKEN |
Описание ошибки валидации поля¶
Описание ошибки валидации передаётся в объекте cause.
| Параметр | Обязательный | Тип | Описание |
|---|---|---|---|
| fieldName: [value] | Нет | array of strings | fieldName — название конкретного поля,[value] — список ошибок валидации этого поля |
Параметры QR-кода¶
Параметры QR-кода передаются в объекте qrCode запроса на создание QR-кода СБП и ответа на этот запрос.
| Параметр | Обязательный | Тип | Описание | Где используется |
|---|---|---|---|---|
| type | Да | string | Тип QR-кода | Запрос, ответ |
| status | Да | string | Текущий статус QR-кода | Ответ |
| payload | Нет | string | Строка данных QR-кода | Ответ |
| ttl | Нет | number | Срок действия QR-кода в минутах.Только для type=DYNAMIC. По умолчанию динамический QR-код активен в течение 72 часов, по истечении срока деактивируется. |
Запрос, ответ |
| image | Нет | object | Характеристики изображения QR-кода | Запрос, ответ |
| declineReason | Нет | string | Причина отклонения операции | Ответ |
Платёжная карта¶
Информация о банковской карте, с которой совершён платёж.
| Параметр | Обязательный | Тип | Описание |
|---|---|---|---|
| issuingCountry | Нет | string(3) | Код страны эмитента |
| issuingBank | Нет | string | Банк-эмитент |
| paymentSystem | Нет | string | Тип платёжной системы |
| fundingSource | Нет | string | Тип карты |
| paymentSystemProduct | Нет | string | Категория карты |
Платёжный токен¶
Информация о платёжном токене для банковской карты. Возвращается в объекте createdToken ответа на запросы создания платежа, если запрошен выпуск токена, получения списка платежей по счёту, если токен был использован при оплате, и др.
| Параметр | Обязательный | Тип | Описание |
|---|---|---|---|
| token | Да | string | Платёжный токен карты |
| expiredDate | Да | string | Дата окончания срока действия платёжного токена |
| name | Нет | string | Маскированный номер карты, для которой выпущен платёжный токен |
Платёжный токен СБП¶
Информация о платёжном токене СБП. Возвращается в объекте token ответа на запрос создания QR-кода, если запрошен выпуск токена СБП.
| Параметр | Обязательный | Тип | Описание |
|---|---|---|---|
| status | Да | string | Статус выпуска токена (возможные значения: IN_PROGRESS, CREATED, REJECTED) |
| expiredDate | Да | string | Дата окончания срока действия платёжного токена |
| value | Нет | string | Платёжный токен СБП |
| rejectReason | Нет | string | Причина отклонения операции |
| bankMemberId | Нет | string | Идентификатор банка плательщика в СБП |
Покупатель¶
Информация о покупателе передаётся в объекте customer.
| Параметр | Обязательный | Тип | Описание |
|---|---|---|---|
| account | Да | string(64) | Идентификатор Покупателя в системе ТСП |
| Нет | string(1000) | Город | |
| phone | Нет | string(1000) | Округ, регион, область, штат |
| address | Нет | object | Адрес покупателя |
| lastName | Нет | string | Фамилия заёмщика (для передачи данных МФО) |
| firstName | Нет | string | Имя заёмщика (для передачи данных МФО) |
| middleName | Нет | string | Отчество заёмщика (для передачи данных МФО) |
Получатель платежа¶
Информация о получателе платежа передаётся в объекте receiverData.
| Параметр | Обязательный | Тип | Описание |
|---|---|---|---|
| pan | Нет | string(19) | Номер карты получателя денежного перевода. Указывается для операций денежных переводов |
| phone | Нет | string(15) | Номер телефона получателя платежа. Указывается при пополнении телефона |
| bankAccount | Нет | string(20) | Номер счёта получателя платежа. Указывается для операций денежных переводов |
| bic | Нет | string(9) | БИК кредитной организации получателя платежа. Указывается для операций денежных переводов |
Произвольная информация, дополняющая данные по операции¶
Информация передаётся в параметрах объекта customFields.
| Параметр | Обязательный | Тип | Описание |
|---|---|---|---|
| auto_capture | Да | boolean | Показывает, что платёж был выполнен с автоподтверждением.Возвращается в ответах на запросы «Получение статуса счёта», «Получение списка платежей по счёту» |
| contract_id | Нет | string | Номер договора клиента (для передачи данных МФО).Возвращается в ответе на запрос «Создание счёта» |
| invoice_callback_url | Нет | string(256) | URL отправки уведомления по операции.Возвращается в ответе на запрос «Создание счёта» |
| invoice_creation_type | Да | string | Тип интерфейса, использованного для создания счёта.Возвращается в ответах на запросы «Получение статуса счёта», «Получение списка платежей по счёту» |
| themeCode | Нет | string(256) | Код стиля для применения к платёжной форме.Возвращается в ответе на запрос «Создание счёта» |
| cf1 | Нет | string(256) | Поле для произвольной информации, дополняющей данные по операции |
| cf2 | Нет | string(256) | Поле для произвольной информации, дополняющей данные по операции |
| cf3 | Нет | string(256) | Поле для произвольной информации, дополняющей данные по операции |
| cf4 | Нет | string(256) | Поле для произвольной информации, дополняющей данные по операции |
| cf5 | Нет | string(256) | Поле для произвольной информации, дополняющей данные по операции |
Реквизиты банковской карты¶
Реквизиты банковской карты передаются в объекте cardData запроса «Проверка карты».
| Параметр | Обязательный | Тип | Описание |
|---|---|---|---|
| pan | Да | string(19) | Номер банковской карты |
| expiryDate | Да | string(5) | Срок действия банковской карты в формате MM/YY |
| cvv2 | Да | string(4) | CVV2/CVC2 на банковской карте |
| holderName | Нет | string(26) | Имя держателя карты, как указано на банковской карте (латинские буквы) |
| cardTokenPaymentType | Нет | string | Параметр для корректной обработки транзакций в платежных системах для операций с сохраненными картами.Возможные значения: FIRST_PAYMENT — если после этой операции вы сохраните карту на своей стороне |
Сведения о сохранённой карте¶
Если для платежа используется сохранённая карта, информация о ней передаётся в объекте credentialOnFile.
| Параметр | Обязательный | Тип | Описание |
|---|---|---|---|
| type | Нет | string | Тип операции платежа с использованием сохранённой карты |
| trn | Нет | string | Идентификатор транзакции, в которой была привязана карта |
Список платежей по счёту¶
Список платежей по счёту передаётся в виде массива payments, содержащего объекты с указанными в таблице параметрами.
| Параметр | Обязательный | Тип | Описание |
|---|---|---|---|
| paymentId | Да | string | Идентификатор платежа |
| billId | Да | string | Идентификатор счёта. Такой же, как в запросе |
| createdDateTime | Да | string | Дата создания счёта |
| amount | Да | object | Сумма операции |
| capturedAmount | Да | object | Сумма подтверждений |
| refundedAmount | Да | object | Сумма возвратов |
| paymentMethod | Да | object | Метод платежа |
| status | Да | object | Статус платежа |
| customer | Нет | object | Данные покупателя: account, email, phone, address |
| requirements | Нет | object | Требования для дополнительной аутентификации покупателя, полученные в операции платежа |
| comment | Нет | string | Комментарий к платежу |
| customFields | Нет | object | Поля с производной информацией, дополняющей данные по операции: auto_capture, invoice_creation_type и др. |
Статус операции¶
Статус операции передаётся в объекте status.
| Параметр | Обязательный | Тип | Описание |
|---|---|---|---|
| value | Да | string | Значение статуса операции |
| changedDateTime | Да | string | Дата изменения статуса |
| reason | Нет | string | Причина отклонения. Список возможных причин указан в разделе Ошибки API |
| reasonMessage | Нет | string | Детализация причины отклонения |
| psErrorCode | Нет | string | Причина отклонения операции, полученная от платёжной системы. Список возможных причин указан в разделе Справочник кодов детализации ошибки |
Статус счёта¶
Статус счёта передаётся в объекте status в ответе на запрос «Получение статуса счёта».
| Параметр | Обязательный | Тип | Описание |
|---|---|---|---|
| value | Да | string | Значение статуса счёта |
| changedDateTime | Да | string | Дата изменения статуса счёта |
| reason | Нет | string | Причина отклонения счёта. Список возможных причин указан в разделе Ошибки API |
| reasonMessage | Нет | string | Детализация причины отклонения |
Сумма операции¶
Сумма операции передаётся в объектах amount, capturedAmount, refundedAmount в зависимости от типа операции.
| Параметр | Обязательный | Тип | Описание |
|---|---|---|---|
| value | Да | number(6.2) | Сумма операции, округленная до двух десятичных знаков в меньшую сторону |
| currency | Да | string(3) | Валюта в буквенном формате согласно ISO 4217. |
Требования для дополнительной аутентификации¶
Требования для дополнительной аутентификации покупателя передаются в объекте payments.requirements в ответах на запросы «Получение информации о счёте», «Создание платежа», «Завершение аутентификации покупателя».
| Параметр | Обязательный | Тип | Описание |
|---|---|---|---|
| threeDS | Да | object | Данные для аутентификации банковских карт по протоколам 3DS и 3DS2.0 |
Устройство клиента¶
Информация об устройстве клиента передаётся в объекте deviceData.
| Параметр | Обязательный | Тип | Описание |
|---|---|---|---|
| ip | Да | string(39) | IP-адрес клиента |
| userAgent | Нет | string(256) | Браузер клиента |
| screenResolution | Нет | string(64) | Разрешение экрана терминала клиента |
| fingerprint | Нет | string(64) | Уникальный идентификатор устройства клиента |
| datetime | Нет | string(26) | Локальное время клиента |
| timeOnPage | Нет | integer | Время просмотра веб-страницы браузера |
Характеристики изображения QR-кода¶
Параметры QR-кода передаются в объекте qrCode.image запроса на создание QR-кода СБП и ответа на этот запрос.
| Параметр | Обязательный | Тип | Описание | Где используется |
|---|---|---|---|---|
| content | Да | string | Изображение QR-кода (Base64-encoded) | Ответ |
| mediaType | Нет | string | Тип изображения.Допустимые значения: image/png, image/svg+xml |
Запрос, ответ |
| width | Нет | number | Ширина изображения в пикселях. Целое число в диапазоне 200 - 1000 | Запрос, ответ |
| height | Нет | number | Высота изображения в пикселях. Целое число в диапазоне 200 - 1000 | Запрос, ответ |