Skip to content

Latest commit

 

History

History
845 lines (777 loc) · 50.3 KB

_notifications_ru.html.md

File metadata and controls

845 lines (777 loc) · 50.3 KB

Серверные уведомления {#callback}

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

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

  • PAYMENT — отправляются при совершении операций платежа;
  • CAPTURE — отправляются при совершении операций подтверждения платежа;
  • REFUND — отправляются при совершении операций возврата платежа;
  • CHECK_CARD — отправляются при совершении операций проверки карты;
  • TOKEN — отправляются при выпуске токена СБП и совершении платежных операций с его использованием;
  • PAYOUT — отправляются при совершении операций выплаты.
Не установлено единого порядка отправки уведомлений разного типа в ходе выполнения одной и той же операции. Порядок может отличаться для разных операций.

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

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

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

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

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

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

  • 79.142.16.0/20
  • 195.189.100.0/22
  • 91.232.230.0/23
  • 91.213.51.0/24

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

Если по какой-либо причине ваш сервер успешно обработал уведомление по транзакции, но не вернул 200 OK, то при повторной попытке доставки не нужно обрабатывать такую транзакцию как новую.

Авторизация уведомлений {#notifications-auth}

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

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

Цифровая подпись уведомления помещается в HTTP-заголовок Signature.

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

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

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

    parameters = {payment.paymentId}|{payment.createdDateTime}|{payment.amount.value}

    где {*} – значение параметра уведомления. Все значения предварительно приводятся к строковому представлению (UTF-8).

    Набор полей уведомления для проверки подписи зависит от типа уведомления:

    • тип PAYMENT: payment.paymentId|payment.createdDateTime|payment.amount.value
    • тип REFUND: refund.refundId|refund.createdDateTime|refund.amount.value
    • тип CAPTURE: capture.captureId|capture.createdDateTime|capture.amount.value
    • тип CHECK_CARD: checkPaymentMethod.requestUid|checkPaymentMethod.checkOperationDate
    • тип TOKEN: token.merchantSiteUid|token.account|token.status.value|token.status.changedDateTime
    • тип PAYOUT: payout.payoutId|payout.createdDateTime|payout.amount.value

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

    hash = HMAC(SHA256, secret, parameters)

    Где:

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

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

Частота отправки уведомлений {#notification-rate}

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

  • 1 попытка с отложенным временем 5 секунд
  • 1 попытка с отложенным временем 1 минута
  • 3 попытки с отложенным временем по 5 минут

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

Формат уведомления PAYMENT {#payment-callback}

  • HEADERS

    • Signature: XXX
    • Accept: application/json
    • Content-type: application/json

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

POST /qiwi-notify.php HTTP/1.1
Accept: application/json
Content-type: application/json
Signature: J4WNfNZd***V5mv2w=
Host: example.com
{
  "payment": {
    "paymentId": "A22170834426031500000733E625FCB3",
    "customFields": {},
    "type": "PAYMENT",
    "createdDateTime": "2022-08-05T11:34:42+03:00",
    "status": {
      "value": "SUCCESS",
      "changedDateTime": "2022-08-05T11:34:44+03:00"
    },
    "amount": {
      "value": 5,
      "currency": "RUB"
    },
    "paymentMethod": {
      "type": "SBP",
      "phone": "79111112233"
    },
    "customer": {
      "phone": "0",
      "bankAccountNumber": "4081710809561219555",
      "bic": "044525974",
      "lastName": "ИВАНОВ",
      "firstName": "ИВАН",
      "middleName": "ИВАНОВИЧ",
      "simpleAddress": "",
      "bankMemberId": "100000000008"
    },
    "billId": "autogenerated-6cd20922-b1d0-4e67-ba61-e2b7310c4006",
    "flags": [
      "SALE"
    ],
    "qrCodeUid": "acfd9"
  },
  "type": "PAYMENT",
  "version": "1"
}

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

{
    "payment": {
        "paymentId": "134d707d-fec4-4a84-93f3-781b4f8c24ac",
        "customFields": {
            "comment": "Мой комментарий"
        },
        "paymentCardInfo": {
            "issuingCountry": "643",
            "issuingBank": "Unknown",
            "paymentSystem": "VISA",
            "fundingSource": "UNKNOWN",
            "paymentSystemProduct": "Unknown"
        },
        "type": "PAYMENT",
        "createdDateTime": "2021-02-05T11:29:38+03:00",
        "status": {
            "value": "SUCCESS",
            "changedDateTime": "2021-02-05T11:29:39+03:00"
        },
        "amount": {
            "value": 3,
            "currency": "RUB"
        },
        "paymentMethod": {
            "type": "TOKEN",
            "paymentToken": "1620161e-d498-431b-b006-c52bb78c6bf2",
            "maskedPan": "425600******0003",
            "cardHolder": "CARD HOLDER",
            "cardExpireDate": "11/2022"
        },
        "customer": {
            "email": "[email protected]",
            "account": "sbderxuftsrt",
            "phone": "13387571067",
            "country": "yccsnnfjgthu",
            "city": "sqdvseezbpzo",
            "region": "shbvyjgspjvu"
        },
        "gatewayData": {
            "type": "ACQUIRING",
            "authCode": "181218",
            "rrn": "123"
        },
        "billId": "autogenerated-19cf2596-62a8-47f2-8721-b8791e9598d0",
        "flags": [],
        "paymentSplits": [
            {
                "type": "MERCHANT_DETAILS",
                "siteUid": "Obuc-00",
                "splitAmount": {
                    "value": 2,
                    "currency": "RUB"
                },
                "splitCommissions": {
                    "merchantCms": {
                        "value": 0.2,
                        "currency": "RUB"
                    },
                    "userCms": null
                },
                "orderId": "dressesforwhite",
                "comment": "Платье"
            },
            {
                "type": "MERCHANT_DETAILS",
                "siteUid": "Obuc-01",
                "splitAmount": {
                    "value": 1,
                    "currency": "RUB"
                },
                "splitCommissions": {
                    "merchantCms": {
                        "value": 0.02,
                        "currency": "RUB"
                    },
                    "userCms": null
                },
                "orderId": "shoesforvalya",
                "comment": "Туфли"
            }
        ]
    },
    "type": "PAYMENT",
    "version": "1"
}
Поле Описание Тип В каких случаях используется
payment Описание платежа. Object Всегда
---- ------ ------- --------
payment.
type		 Тип операции — только PAYMENT String(200) Всегда
payment.
paymentId		 Уникальный идентификатор платежа в системе ТСП. String(200) Всегда
payment.
createdDateTime		 Дата создания операции URL-закодированная строка
ГГГГ-ММ-ДДTЧЧ:ММ:ССZ		 Всегда
payment.
billId		 Идентификатор счета, соответствующего операции String(200) Всегда
payment.
qrCodeUid		 Идентификатор операции выпуска QR-кода в системе ТСП String Если операция была выполнена через СБП
payment.
amount		 Информация о сумме операции Object Всегда
-- -- ---- ---
payment.
amount.
value		 Сумма операции, округленная до двух десятичных знаков в меньшую сторону Number(6.2) Всегда
payment.
amount.
currency		 Идентификатор валюты операции (Alpha-3 ISO 4217 код) String(3) Всегда
--- --- --- ----
payment.
status		 Информация о статусе операции Object Всегда
--- --- --- ------
payment.
status.
value		 Строковое значение статуса String Всегда
payment.
status.
changedDateTime		 Дата обновления статуса URL-закодированная строка
ГГГГ-ММ-ДДTЧЧ:ММ:ССZ		 Всегда
payment.
status.
reasonCode		 Код причины отклонения String(200) В случае отклонения операции
payment.
status.
reasonMessage		 Описание причины отклонения String(200) В случае отклонения операции
payment.
status.
errorCode		 Код ошибки Number В случае ошибки
payment.
status.
psErrorCode		 Оригинальный код ошибки, полученный от платежной системы String В случае отклонения операции
--- --- --- ------
payment.
paymentMethod		 Информация о средстве платежа Object Всегда
--- --- --- ------
payment.
paymentMethod.
type		 Тип метода оплаты: CARD — банковская карта, TOKEN — платежный токен, SBP — Система Быстрых Платежей, QIWI_WALLET — баланс QIWI Кошелька String Всегда
payment.
paymentMethod.
paymentToken		 Платежный токен карты. String При оплате платежным токеном
payment.
paymentMethod.
maskedPan		 Маскированный PAN карты String При оплате платежным токеном или картой
payment.
paymentMethod.
rrn		 RRN платежа (по ISO 8583) Number При оплате платежным токеном или картой
payment.
paymentMethod.
authCode		 Auth-code платежа Number При оплате платежным токеном или картой
payment.
paymentMethod.
phone		 Телефон, с которого выполнялась оплата через СБП, или номер QIWI Кошелька String При оплате через СБП или с баланса QIWI Кошелька
--- --- --- -------
payment.
paymentCardInfo		 Информация о карте. Object Всегда
--- --- --- -------
payment.
paymentCardInfo.
issuingCountry		 Код страны эмитента String(3) Всегда
payment.
paymentCardInfo.
issuingBank		 Банк-эмитент String Всегда
payment.
paymentCardInfo.
paymentSystem		 Тип платежной системы String Всегда
payment.
paymentCardInfo.
fundingSource		 Тип карты String Всегда
payment.
paymentCardInfo.
paymentSystemProduct		 Категория карты String Всегда
--- --- --- -----
payment.
customer		 Информация о покупателе Object Всегда
--- --- --- ------
payment.
customer.
phone		 Номер телефона покупателя String Всегда
payment.
customer.
email		 E-mail покупателя String Всегда
payment.
customer.
account		 Идентификатор покупателя в системе ТСП String Всегда
payment.
customer.
ip		 IP адрес покупателя String Всегда
payment.
customer.
country		 Страна адреса покупателя String Всегда
payment.
customer.
bankAccountNumber		 Номер счета плательщика String Только для платежей через СБП
payment.
customer.
bic		 БИК банка, выпустившего карту String Только для платежей через СБП
payment.
customer.
lastName		 Фамилия покупателя String Только для платежей через СБП
payment.
customer.
firstName		 Имя покупателя String Только для платежей через СБП
payment.
customer.
middleName		 Отчество покупателя String Только для платежей через СБП
payment.
customer.
simpleAddress		 Адрес покупателя String Только для платежей через СБП
payment.
customer.
inn		 ИНН покупателя String Только для платежей через СБП
payment.
customer.
bankMemberId		 Идентификатор банка покупателя String Только для платежей через СБП
--- --- --- ----
payment.
customFields		 Поля с произвольной информацией, дополняющей данные по операции Object Всегда
--- --- --- -----
payment.
customFields.
cf1		 Поле с произвольной информацией, дополняющей данные по операции String(256) Всегда
payment.
customFields.
cf2		 Поле с произвольной информацией, дополняющей данные по операции String(256) Всегда
payment.
customFields.
cf3		 Поле с произвольной информацией, дополняющей данные по операции String(256) Всегда
payment.
customFields.
cf4		 Поле с произвольной информацией, дополняющей данные по операции String(256) Всегда
payment.
customFields.
cf5		 Поле с произвольной информацией, дополняющей данные по операции String(256) Всегда
--- --- --- ------
payment.
flags		 Дополнительные команды, переданные в API Массив. Возможные элементы - SALE/REVERSAL Всегда
payment.
tokenData		 Объект с информацией о выпущенном платежном токене Object Если в платеже был запрошен выпуск платежного токена
--- --- --- -----
payment.
tokenData.
paymentToken		 Строка платежного токена String Если в платеже был запрошен выпуск платежного токена
payment.
tokenData.
expiredDate		 Дата окончания срока действия платежного токена. Формат даты соответствует стандарту ISO-8601:
ГГГГ-ММ-ДДTчч:мм:сс±чч:мм		 String Если в платеже был запрошен выпуск платежного токена
--- --- --- -----
payment.
chequeData		 Описание фискального чека ChequeData Если в операции были отправлены данные для формирования фискального чека
payment.
paymentSplits		 Описание сплитованных платежей. Array(Objects) Для сплитованных платежей
----- ------ ------ -----
payment.
paymentSplits.
type		 Тип передаваемых данных. Всегда строка MERCHANT_DETAILS String Для сплитованных платежей
payment.
paymentSplits.
siteUid		 ID поставщика String Для сплитованных платежей
payment.
paymentSplits.
splitAmount		 Информация о возмещении поставщику Object Для сплитованных платежей
---- ---- ----- -----
payment.
paymentSplits.
splitAmount.
value		 Сумма возмещения Number Для сплитованных платежей
payment.
paymentSplits.
splitAmount.
currency		 Буквенный код валюты возмещения по ISO String(3) Для сплитованных платежей
---- ---- ----- -----
payment.
paymentSplits.
splitCommissions		 Информация о комиссии Object Для сплитованных платежей
----- ---- ----- -----
payment.
paymentSplits.
splitCommissions.
merchantCms		 Информация о комиссии с поставщика Object Для сплитованных платежей
---- ----- ---- -----
payment.
paymentSplits.
splitCommissions.
merchantCms.
value		 Сумма комиссии Number Для сплитованных платежей
payment.
paymentSplits.
splitCommissions.
merchantCms.
currency		 Буквенный код валюты комиссии по ISO String(3) Для сплитованных платежей
----- ----- ----- -----
payment.
paymentSplits.
orderId		 Номер заказа String Для сплитованных платежей
payment.
paymentSplits.
comment		 Комментарий к заказу String Для сплитованных платежей
----- ----- ----- -----
type Тип уведомления — только PAYMENT String Всегда
version Версия уведомлений String Всегда

Формат уведомления CAPTURE {#capture-callback}

  • HEADERS

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

Формат уведомления REFUND {#refund-callback}

  • HEADERS

    • Signature: XXX
    • Accept: application/json
    • Content-type: application/json

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

{
    "refund": {
        "refundId": "42f5ca91-965e-4cd0-bb30-3b64d9284048",
        "type": "REFUND",
        "createdDateTime": "2021-02-05T11:31:40+03:00",
        "status": {
            "value": "SUCCESS",
            "changedDateTime": "2021-02-05T11:31:40+03:00"
        },
        "amount": {
            "value": 3,
            "currency": "RUB"
        },
        "paymentMethod": {
            "type": "TOKEN",
            "paymentToken": "1620161e-d498-431b-b006-c52bb78c6bf2",
            "maskedPan": null,
            "cardHolder": null,
            "cardExpireDate": null
        },
        "customer": {
            "email": "[email protected]",
            "account": "sbderxuftsrt",
            "phone": "13387571067",
            "country": "yccsnnfjgthu",
            "city": "sqdvseezbpzo",
            "region": "shbvyjgspjvu"
        },
        "gatewayData": {
            "type": "ACQUIRING",
            "authCode": "181218",
            "rrn": "123"
        },
        "billId": "autogenerated-19cf2596-62a8-47f2-8721-b8791e9598d0",
        "flags": [
            "REVERSAL"
        ],
        "refundSplits": [
            {
                "type": "MERCHANT_DETAILS",
                "siteUid": "Obuc-00",
                "splitAmount": {
                    "value": 2,
                    "currency": "RUB"
                },
                "splitCommissions": {
                    "merchantCms": {
                        "value": 0,
                        "currency": "RUB"
                    },
                    "userCms": null
                },
                "orderId": "dressesforwhite",
                "comment": "Покупка 1"
            },
            {
                "type": "MERCHANT_DETAILS",
                "siteUid": "Obuc-01",
                "splitAmount": {
                    "value": 1,
                    "currency": "RUB"
                },
                "splitCommissions": {
                    "merchantCms": {
                        "value": 0.02,
                        "currency": "RUB"
                    },
                    "userCms": null
                },
                "orderId": "shoesforvalya",
                "comment": "Покупка 2"
            }
        ]
    },
    "type": "REFUND",
    "version": "1"
}
Поле Описание Тип В каких случаях используется
refund Описание возврата. Object Всегда
---- ------ ------- --------
refund.
type		 Тип операции — только REFUND String(200) Всегда
refund.
refundId		 Уникальный идентификатор возврата в системе ТСП. String(200) Всегда
refund.
createdDateTime		 Дата создания операции URL-закодированная строка
ГГГГ-ММ-ДДTЧЧ:ММ:ССZ		 Всегда
refund.
amount		 Информация о сумме операции Object Всегда
-- -- ---- ---
refund.
amount.
value		 Сумма операции, округленная до двух десятичных знаков в меньшую сторону Number(6.2) Всегда
refund.
amount.
currency		 Идентификатор валюты операции (Alpha-3 ISO 4217 код) String(3) Всегда
--- --- --- ----
refund.
billId		 ID счета, соответствующего операции String(200) Всегда
refund.
status		 Информация о статусе операции Object Всегда
--- --- --- ------
refund.
status.
value		 Строковое значение статуса String Всегда
refund.
status.
changedDateTime		 Дата обновления статуса URL-закодированная строка
ГГГГ-ММ-ДДTЧЧ:ММ:ССZ		 Всегда
refund.
status.
reasonCode		 Код причины отклонения String(200) В случае отклонения операции
refund.
status.
reasonMessage		 Описание причины отклонения String(200) В случае отклонения операции
refund.
status.
errorCode		 Код ошибки Number В случае ошибки
--- --- --- ------
refund.
paymentMethod		 Информация о средстве платежа Object Всегда
--- --- --- ------
refund.
paymentMethod.
type		 Тип метода оплаты String Всегда
refund.
paymentMethod.
maskedPan		 Маскированный PAN карты String Всегда
refund.
paymentMethod.
rrn		 RRN платежа (по ISO 8583) Number Всегда
refund.
paymentMethod.
authCode		 Auth-code платежа Number Всегда
--- --- --- -----
refund.
customer		 Информация о покупателе Object Всегда
--- --- --- ------
refund.
customer.
phone		 Номер телефона покупателя String Всегда
refund.
customer.
email		 E-mail покупателя String Всегда
refund.
customer.
account		 Идентификатор покупателя в системе ТСП String Всегда
refund.
customer.
ip		 IP адрес покупателя String Всегда
refund.
customer.
country		 Страна адреса покупателя String Всегда
--- --- --- ----
refund.
customFields		 Поля с произвольной информацией, дополняющей данные по операции Object Всегда
--- --- --- -----
refund.
customFields.
cf1		 Поле с произвольной информацией, дополняющей данные по операции String(256) Всегда
refund.
customFields.
cf2		 Поле с произвольной информацией, дополняющей данные по операции String(256) Всегда
refund.
customFields.
cf3		 Поле с произвольной информацией, дополняющей данные по операции String(256) Всегда
refund.
customFields.
cf4		 Поле с произвольной информацией, дополняющей данные по операции String(256) Всегда
refund.
customFields.
cf5		 Поле с произвольной информацией, дополняющей данные по операции String(256) Всегда
--- --- --- ------
refund.
flags		 Дополнительные команды, переданные в API Array(Strings). Возможные элементы: SALE, REVERSAL Всегда
refund.
chequeData		 Описание фискального чека ChequeData Если в операции был отправлены данные для формирования фискального чека
refund.
refundSplits		 Описание возвратов по сплитованным платежам. Array(Objects) При возвратах сплитованных платежей
----- ------ ------ -----
refund.
refundSplits.
type		 Тип передаваемых данных. Всегда строка MERCHANT_DETAILS String При возвратах сплитованных платежей
refund.
refundSplits.
siteUid		 ID поставщика String При возвратах сплитованных платежей
refund.
refundSplits.
splitAmount		 Информация об отмене возмещения поставщику Object При возвратах сплитованных платежей
---- ---- ----- -----
refund.
refundSplits.
splitAmount.
value		 Сумма отмены возмещения Number При возвратах сплитованных платежей
refund.
refundSplits.
splitAmount.
currency		 Буквенный код валюты отмены возмещения по ISO String(3) При возвратах сплитованных платежей
---- ---- ----- -----
refund.
refundSplits.
splitCommissions		 Информация о комиссии Object При возвратах сплитованных платежей
----- ---- ----- -----
refund.
refundSplits.
splitCommissions.
merchantCms		 Информация о комиссии с поставщика Object При возвратах сплитованных платежей
---- ----- ---- -----
refund.
refundSplits.
splitCommissions.
merchantCms.
value		 Сумма комиссии Number При возвратах сплитованных платежей
refund.
refundSplits.
splitCommissions.
merchantCms.
currency		 Буквенный код валюты комиссии по ISO String(3) При возвратах сплитованных платежей
----- ----- ----- -----
refund.
refundSplits.
orderId		 Номер заказа String При возвратах сплитованных платежей
refund.
refundSplits.
comment		 Комментарий к заказу String При возвратах сплитованных платежей
----- ----- ----- -----
type Тип уведомления — только REFUND String Всегда
version Версия уведомлений String Всегда

Формат уведомления CHECK_CARD {#check-card-callback}

  • HEADERS

    • Signature: XXX
    • Accept: application/json
    • Content-type: application/json

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

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

Формат уведомления TOKEN {#token-callback}

  • HEADERS

    • Signature: XXX
    • Accept: application/json
    • Content-type: application/json

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

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

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

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

Формат уведомления PAYOUT {#payout-callback}

  • HEADERS

    • Signature: XXX
    • Accept: application/json
    • Content-type: application/json

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

POST <callback-path> HTTP/1.1
Accept: application/json
Content-type: application/json
Signature: J4WNfNZd***V5mv2w=
Host: <callback-url>
{
  "payout": {
    "payoutId":"kxnawm631754",
    "createdDateTime":"2022-12-22T16:20:30+03:00",
    "amount": {
      "value":200.00,
      "currency":"RUB"
    },
    "status":{
      "value":"SUCCESS",
      "changedDateTime":"2022-12-22T16:34:44+03:00"
    },
    "receiverData": {
      "type":"CARD",
      "maskedPan":"400000******0002"
    },
    "flags":["TEST"],
    "payoutSplits" : [ 
      {
        "type" : "MERCHANT_DETAILS",
        "siteUid" : "Obuc-00",
        "splitAmount" : {
          "value" : "150.00",
          "currency" : "RUB"
        },
        "splitCommissions" : {
          "merchantCms" : {
            "value" : "1.50",
            "currency" : "RUB"
          }
        }
      }, 
      {
        "type" : "MERCHANT_DETAILS",
        "siteUid" : "Obuc-01",
        "splitAmount" : {
          "value" : "50.00",
          "currency" : "RUB"
        },
        "splitCommissions" : {
          "merchantCms" : {
            "value" : "0.50",
            "currency" : "RUB"
          }
        }
      } 
    ]
  },
  "type":"PAYOUT",
  "version":"1"
}
Поле Описание Тип В каких случаях используется
payout Описание выплаты Object Всегда
---- ------ ------- --------
payout.
payoutId		 Уникальный идентификатор выплаты в системе ТСП String(200) Всегда
payout.
createdDateTime		 Дата создания операции URL-закодированная строка
ГГГГ-ММ-ДДTЧЧ:ММ:ССZ		 Всегда
payout.
amount		 Информация о сумме операции Object Всегда
-- -- ---- ---
payout.
amount.
value		 Сумма операции, округленная до двух десятичных знаков в меньшую сторону Number(6.2) Всегда
payout.
amount.
currency		 Идентификатор валюты операции (Alpha-3 ISO 4217 код) String(3) Всегда
--- --- --- ----
payout.
status		 Информация о статусе операции Object Всегда
--- --- --- ------
payout.
status.
value		 Строковое значение статуса String Всегда
payout.
status.
changedDateTime		 Дата обновления статуса URL-закодированная строка
ГГГГ-ММ-ДДTЧЧ:ММ:ССZ		 Всегда
payout.
status.
reasonCode		 Код причины отклонения String(200) В случае отклонения операции
payout.
status.
reasonMessage		 Описание причины отклонения String(200) В случае отклонения операции
payout.
status.
errorCode		 Код ошибки Number В случае ошибки
--- --- --- ------
payout.
receiverData		 Информация о получателе PayoutReceiverDataCallback Всегда
payout.
flags		 Дополнительные флаги операции Array(Strings). Возможные элементы: TEST При необходимости
payout.
payoutSplits		 Описание сплитованных выплат. Array(Objects) Всегда
----- ------ ------ -----
payout.
payoutSplits.
type		 Тип передаваемых данных. Всегда строка MERCHANT_DETAILS String Всегда
payout.
payoutSplits.
siteUid		 ID поставщика String Всегда
payout.
payoutSplits.
splitAmount		 Информация о списании с поставщика Object Всегда
---- ---- ----- -----
payout.
payoutSplits.
splitAmount.
value		 Сумма списания Number Всегда
payout.
payoutSplits.
splitAmount.
currency		 Буквенный код валюты списания по ISO String(3) Всегда
---- ---- ----- -----
payout.
payoutSplits.
splitCommissions		 Информация о комиссии Object При необходимости
----- ---- ----- -----
payout.
payoutSplits.
splitCommissions.
merchantCms		 Информация о комиссии с поставщика Object При необходимости
---- ----- ---- -----
payout.
payoutSplits.
splitCommissions.
merchantCms.
value		 Сумма комиссии Number При необходимости
payout.
payoutSplits.
splitCommissions.
merchantCms.
currency		 Буквенный код валюты комиссии по ISO String(3) При необходимости
----- ----- ----- -----
payout.
payoutSplits.
orderId		 Номер заказа String При необходимости
payout.
payoutSplits.
comment		 Комментарий к заказу String При необходимости
----- ----- ----- -----
type Тип уведомления — только PAYOUT String Всегда
version Версия уведомлений String Всегда