Уведомления обратного вызова

API банков позволяет получать уведомления обратного вызова (callback-уведомления) об изменении статусов платежей.

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

События, о которых могут приходить уведомления

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

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

списание средств
удержание (холдирование) средств
отмена платежа
возврат средств

Более сложные интеграции могут подразумевать дополнительные триггеры обратного вызова, такие как:

сохранение карты (т.е. создание связки)
включение/выключение существующей связки
отклонение платежей и т.д.

Тип триггера передается в параметре operation уведомления обратного вызова (см. подробности ниже). Для удобства уведомления для дополнительных триггеров могут быть направлены на другой URL-адрес с помощью параметра dynamicCallbackUrl в запросах на регистрацию заказа.

Требования к SSL-сертификатам на сайте Партнера

Если уведомление о состоянии заказа приходит через HTTPS-соединение, необходимо удостоверить подлинность сайта с помощью SSL-сертификата, выпущенного и подписанного доверенным центром сертификации (см. таблицу ниже). Использование самозаверенных сертификатов не допускается.

Требование	Описание
Алгоритм подписи	Не ниже SHA-256.
Поддерживаемые центры сертификации	Ниже приведены примеры организаций, которые регистрируют цифровые сертификаты: Thawte Consulting cc; VeriSign; DigiCert Inc; COMODO CA Limited; GeoTrust Inc.; GlobalSign; Trustis Limited; UniTrust; GoDaddy.

Формат URL-адресов уведомлений

Поддерживаются запросы POST и GET.

Ниже приведен пример GET-запроса по умолчанию, без дополнительных параметров. Параметры получены в запросе.

https://mybestmerchantreturnurl.com/callback/?mdOrder=
1234567890-098776-234-522&orderNumber=0987&operation=deposited&
callbackCreationDate=Mon Jan 31 21:46:52 UTC 2022&status=0

Для POST-коллбэков вы получите те же параметры в теле HTTP (вместо параметров запроса).

https://mybestmerchantreturnurl.com/callback/
mdOrder=
1234567890-098776-234-522&orderNumber=0987&operation=deposited&
callbackCreationDate=Mon Jan 31 21:46:52 UTC 2022&status=0

Передаваемые параметры представлены в таблице ниже.

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

Параметр	Описание
`mdOrder`	Уникальный номер заказа, хранящийся в банке.
`orderNumber`	Уникальный номер заказа (идентификатор) в системе Партнера.
`operation`	Тип события, вызвавшего уведомление: `approved` - холдирование (удержание) средств на счете покупателя; `deposited` - операция завершения; `reversed` - платеж был отменен; `refunded` - деньги за заказ возвращены; `bindingCreated` - карта плательщика сохранена (cвязка создана); `bindingActivityChanged` - существующая связка была отключена/включена. `declinedByTimeout` - платеж был отклонен из-за истечения времени ожидания; `declinedCardPresent` - отклоненная транзакция с предъявлением карты (оплата физической картой).
`status`	Индикатор успешности операции, указанной в параметре `operation`: `1` - успех; `0` - ошибка.

Пользовательские заголовки callback уведомлений

Пользовательские заголовки callback уведомлений можно задать, обратившись в службу технической поддержки. Например:

'http://mybestmerchantreturnurl.com/callback.php', headers={Authorization=token, Content-type=plain
/text}, params={orderNumber=349002, mdOrder=5ffb1899-cd1e-7c1e-8750-e98500093c43, operation=deposited, status=1}

где {Authorization=token, Content-type=plain/text} – это настраиваемый заголовок.

Примеры

https://mybestmerchantreturnurl.com/callback/?mdOrder=1234567890-098776-234-522&orderNumber=0987&operation=deposited&status=0

Алгоритм обработки уведомлений о состоянии заказов

Платежный шлюз отправляет на сервер продавца следующий запрос.
https://mybestmerchantreturnurl.com/callback/?mdOrder=1234567890-098776-234-522&orderNumber=0987&operation=deposited&status=0
Сервер продавца возвращает HTTP-сообщение 200 OK платежному шлюзу.

Неуспешные уведомления

Если в платежный шлюз возвращается ответ, отличный от HTTP-кода 200 OK, отправка уведомления считается неуспешной. В этом случае платежный шлюз повторяет уведомление с интервалом в 30 секунд до тех пор, пока не будет выполнено одно из следующих условий:

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

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

Дополнительные параметры уведомлений обратного вызова

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

Параметр	Описание	Тип события
`bindingId`	UUIID созданных/обновленных сохраненных учетных данных (связки).	BINDING_CREATED, BINDING_ACTIVITY_CHANGED
`email`	Электронная почта клиента.	BINDING_CREATED
`phone`	Телефон клиента.	BINDING_CREATED
`panMasked`	Маскированный PAN карты клиента.	BINDING_CREATED
`panCountryCode`	Код страны клиента.	BINDING_CREATED
`enabled`	Активна ли связка (`true`/`false`).	BINDING_ACTIVITY_CHANGED
`templateId`	Идентификатор QR-кода для СБП.	DEPOSITED
`currentDepositAmountFormatted`	Отформатированная сумма операции завершения.	DEPOSITED
`currentReverseAmountFormatted`	Форматированная сумма операции отмены.	REVERSED
`currentRefundAmountFormatted`	Отформатированная сумма операции возврата.	REFUNDED
`operationRefundedAmountFormatted`	Отформатированная сумма операции возврата.	REFUNDED
`operationRefundedAmount`	Сумма возврата в минимальных денежных единицах (например, в центах).	REFUNDED
`externalRefundId`	Внешний идентификатор операции возврата.	REFUNDED
`callbackCreationDate`	Дата создания уведомления обратного вызова. Требуется специальная настройка продавца.	DEPOSITED, APPROVED, REVERSED, REFUNDED, DECLINED_BY_TIMEOUT, BINDING_CREATED, BINDING_ACTIVITY_CHANGED, DECLINED_CARDPRESENT
`status`	Статус операции: 1 - успех, 0 - неудача	DEPOSITED, APPROVED, REVERSED, REFUNDED, DECLINED_BY_TIMEOUT, DECLINED_CARDPRESENT
`operation`	Тип callback-а Possible values: `deposited`, `approved`, `reversed`, `refunded`, `bindingCreated`, `bindingActivityChanged`, `declinedByTimeout`, `declinedCardpresent`	DEPOSITED, APPROVED, REVERSED, REFUNDED, DECLINED_BY_TIMEOUT, DECLINED_CARDPRESENT, BINDING_CREATED, BINDING_ACTIVITY_CHANGED
`finishCheckUrl`	URL для генерации чека	DEPOSITED, APPROVED, REVERSED, REFUNDED, DECLINED_BY_TIMEOUT, DECLINED_CARDPRESENT
`cardholderName`	Имя держателя карты.	DEPOSITED, APPROVED, REVERSED, REFUNDED, DECLINED_BY_TIMEOUT, DECLINED_CARDPRESENT
`amount`	Сумма зарегистрированного заказа в минимальных денежных единицах.	DEPOSITED, APPROVED, REVERSED, REFUNDED, DECLINED_BY_TIMEOUT, DECLINED_CARDPRESENT
`paymentAmount`	Сумма зарегистрированного заказа в минимальных денежных единицах.	DEPOSITED, APPROVED, REVERSED, REFUNDED, DECLINED_BY_TIMEOUT, DECLINED_CARDPRESENT
`amountFormatted`	Отформатированная сумма зарегистрированного заказа.	DEPOSITED, APPROVED, REVERSED, REFUNDED, DECLINED_BY_TIMEOUT, DECLINED_CARDPRESENT
`feeAmount`	Сумма комиссии в минимальных единицах валюты.	DEPOSITED, APPROVED, REVERSED, REFUNDED, DECLINED_BY_TIMEOUT, DECLINED_CARDPRESENT
`approvedAmount`	Предварительно авторизованная сумма в минимальных денежных единицах.	DEPOSITED, APPROVED, REVERSED, REFUNDED, DECLINED_BY_TIMEOUT, DECLINED_CARDPRESENT
`depositedAmount`	Сумма завершения в минимальных денежных единицах.	DEPOSITED, APPROVED, REVERSED, REFUNDED, DECLINED_BY_TIMEOUT, DECLINED_CARDPRESENT
`refundedAmount`	Сумма возмещения в минимальных единицах валюты.	DEPOSITED, APPROVED, REVERSED, REFUNDED, DECLINED_BY_TIMEOUT, DECLINED_CARDPRESENT
`approvedAmountFormatted`	Отформатированная предварительно авторизованная сумма.	DEPOSITED, APPROVED, REVERSED, REFUNDED, DECLINED_BY_TIMEOUT, DECLINED_CARDPRESENT
`depositedAmountFormatted`	Отформатированная сумма зачисления.	DEPOSITED, APPROVED, REVERSED, REFUNDED, DECLINED_BY_TIMEOUT, DECLINED_CARDPRESENT
`refundedAmountFormatted`	Отформатированная сумма возврата.	DEPOSITED, APPROVED, REVERSED, REFUNDED, DECLINED_BY_TIMEOUT, DECLINED_CARDPRESENT
`totalAmountFormatted`	Отформатированная общая сумма заказа (зарегистрированная сумма + комиссия).	DEPOSITED, APPROVED, REVERSED, REFUNDED, DECLINED_BY_TIMEOUT, DECLINED_CARDPRESENT
`depositedTotalAmountFormatted`	Отформатированная общая сумма завершения (все суммы завершения + все суммы возврата + комиссия).	DEPOSITED, APPROVED, REVERSED, REFUNDED, DECLINED_BY_TIMEOUT, DECLINED_CARDPRESENT
`approvalCode`	Код авторизации платежа, полученный от процессинга.	DEPOSITED, APPROVED, REVERSED, REFUNDED, DECLINED_BY_TIMEOUT, DECLINED_CARDPRESENT
`authCode`	Код авторизации	DEPOSITED, APPROVED, REVERSED, REFUNDED, DECLINED_BY_TIMEOUT, DECLINED_CARDPRESENT
`bankName`	Наименование банка, выпустившего карту клиента.	DEPOSITED, APPROVED, REVERSED, REFUNDED, DECLINED_BY_TIMEOUT, DECLINED_CARDPRESENT
`currency`	Валюта заказа.	DEPOSITED, APPROVED, REVERSED, REFUNDED, DECLINED_BY_TIMEOUT, DECLINED_CARDPRESENT
`depositFlag`	Флаг, указывающий тип операции. `1` - покупка `2` - преавторизация	DEPOSITED, APPROVED, REVERSED, REFUNDED, DECLINED_BY_TIMEOUT, DECLINED_CARDPRESENT
`eci`	Электронный коммерческий индикатор.	DEPOSITED, APPROVED, REVERSED, REFUNDED, DECLINED_BY_TIMEOUT, DECLINED_CARDPRESENT
`ip`	IP адрес плательщика.	DEPOSITED, APPROVED, REVERSED, REFUNDED, DECLINED_BY_TIMEOUT, DECLINED_CARDPRESENT
`ipCountryCode`	Код страны банка-эмитента.	DEPOSITED, APPROVED, REVERSED, REFUNDED, DECLINED_BY_TIMEOUT, DECLINED_CARDPRESENT
`maskedPan`	Маскированный номер карты клиента.	DEPOSITED, APPROVED, REVERSED, REFUNDED, DECLINED_BY_TIMEOUT, DECLINED_CARDPRESENT
`mdOrder`	Номер заказа в платежном шлюзе. Уникален в пределах платежного шлюза.	DEPOSITED, APPROVED, REVERSED, REFUNDED, DECLINED_BY_TIMEOUT, DECLINED_CARDPRESENT
`mdorder`	Номер заказа в платежном шлюзе. Уникален в пределах платежного шлюза.	DEPOSITED, APPROVED, REVERSED, REFUNDED, DECLINED_BY_TIMEOUT, DECLINED_CARDPRESENT
`merchantFullName`	ФИО продавца.	DEPOSITED, APPROVED, REVERSED, REFUNDED, DECLINED_BY_TIMEOUT, DECLINED_CARDPRESENT
`merchantLogin`	Логин продавца.	DEPOSITED, APPROVED, REVERSED, REFUNDED, DECLINED_BY_TIMEOUT, DECLINED_CARDPRESENT
`orderDescription`	Описание заказа.	DEPOSITED, APPROVED, REVERSED, REFUNDED, DECLINED_BY_TIMEOUT, DECLINED_CARDPRESENT
`orderNumber`	Номер заказа (ID) в системе мерчанта.	DEPOSITED, APPROVED, REVERSED, REFUNDED, DECLINED_BY_TIMEOUT, DECLINED_CARDPRESENT
`threeDSType`	Вид транзакции (3DS). Возможные значения: `SSL`, `THREE_DS1_FULL`, `THREE_DS1_ATTEMPT`, `THREE_DS2_FULL`, `THREE_DS2_FRICTIONLESS`, `THREE_DS2_ATTEMPT`, `THREE_DS2_EXEMPTION_GRANTED`, `THREE_DS2_3RI`, `THREE_DS2_3RI_ATTEMPT`	DEPOSITED, APPROVED, REVERSED, REFUNDED, DECLINED_BY_TIMEOUT, DECLINED_CARDPRESENT
`date`	Дата создания заказа.	DEPOSITED, APPROVED, REVERSED, REFUNDED, DECLINED_BY_TIMEOUT, DECLINED_CARDPRESENT
`clientId`	Номер клиента (ID) в системе мерчанта.	DEPOSITED, APPROVED, REVERSED, REFUNDED, DECLINED_BY_TIMEOUT, DECLINED_CARDPRESENT,BINDING_CREATED, BINDING_ACTIVITY_CHANGED
`actionCode`	Код результата выполнения операции.	DEPOSITED, APPROVED, REVERSED, REFUNDED, DECLINED_BY_TIMEOUT, DECLINED_CARDPRESENT
`actionCodeDescription`	Описание кода результата выполнения операции.	DEPOSITED, APPROVED, REVERSED, REFUNDED, DECLINED_BY_TIMEOUT, DECLINED_CARDPRESENT
`paymentRefNum`	Reference Retrieval Number - идентификатор транзакции, присвоенный банком-эквайером.	DEPOSITED, APPROVED, REVERSED, REFUNDED, DECLINED_BY_TIMEOUT, DECLINED_CARDPRESENT
`paymentState`	Статус заказа. Possible values: `started`, `payment_approved`, `payment_declined`, `payment_void`, `payment_deposited`, `refunded`, `pending`, `partly_deposited`	DEPOSITED, APPROVED, REVERSED, REFUNDED, DECLINED_BY_TIMEOUT, DECLINED_CARDPRESENT
`paymentWay`	Способ оплаты заказа. Дополнительные возможные значения параметра приведены здесь.	DEPOSITED, APPROVED, REVERSED, REFUNDED, DECLINED_BY_TIMEOUT, DECLINED_CARDPRESENT
`processingId`	Идентификатор клиента в процессинге.	DEPOSITED, APPROVED, REVERSED, REFUNDED, DECLINED_BY_TIMEOUT, DECLINED_CARDPRESENT
`refNum`	Reference Retrieval Number - идентификатор транзакции, присвоенный банком-эквайером.	DEPOSITED, APPROVED, REVERSED, REFUNDED, DECLINED_BY_TIMEOUT, DECLINED_CARDPRESENT
`refnum`	Reference Retrieval Number - идентификатор транзакции, присвоенный банком-эквайером.	DEPOSITED, APPROVED, REVERSED, REFUNDED, DECLINED_BY_TIMEOUT, DECLINED_CARDPRESENT
`terminalId`	Идентификатор терминала в системе, обрабатывающей платеж.	DEPOSITED, APPROVED, REVERSED, REFUNDED, DECLINED_BY_TIMEOUT, DECLINED_CARDPRESENT
`paymentSystem`	Наименование платежной системы.	DEPOSITED, APPROVED, REVERSED, REFUNDED, DECLINED_BY_TIMEOUT, DECLINED_CARDPRESENT
`currencyName`	Трехбуквенный ISO-код валюты.	DEPOSITED, APPROVED, REVERSED, REFUNDED, DECLINED_BY_TIMEOUT, DECLINED_CARDPRESENT
`transactionAttributes`	Атрибуты заказа.	DEPOSITED, APPROVED, REVERSED, REFUNDED, DECLINED_BY_TIMEOUT, DECLINED_CARDPRESENT
`paymentDate`	Дата оплаты заказа.	DEPOSITED, APPROVED, REVERSED, REFUNDED
`depositedDate`	Дата операции завершения по заказу.	DEPOSITED, APPROVED, REVERSED, REFUNDED
`refundedDate`	Дата операции возврата по заказу.	REFUNDED
`reversedDate`	Дата операции отмены заказа.	DEPOSITED, REVERSED, REFUNDED
`declineDate`	Дата отмены заказа.	DECLINED_BY_TIMEOUT, DECLINED_CARDPRESENT
`xid`	Индикатор электронной коммерции транзакции, определяемый продавцом.	DEPOSITED, APPROVED, REVERSED, REFUNDED, DECLINED_BY_TIMEOUT, DECLINED_CARDPRESENT
`cavv`	Значение проверки аутентификации владельца карты.	DEPOSITED, APPROVED, REVERSED, REFUNDED, DECLINED_BY_TIMEOUT, DECLINED_CARDPRESENT
`authValue`	Значение проверки аутентификации владельца карты.	DEPOSITED, APPROVED, REVERSED, REFUNDED, DECLINED_BY_TIMEOUT, DECLINED_CARDPRESENT
`sessionExpiredDate`	Дата и время истечения срока действия заказа.	DEPOSITED, APPROVED, REVERSED, REFUNDED, DECLINED_BY_TIMEOUT, DECLINED_CARDPRESENT
`creditBankName`	Название банка, выпустившего карту для зачисления (в P2P).	DEPOSITED, REVERSED, REFUNDED, DECLINED_BY_TIMEOUT
`creditPanCountryCode`	Код страны карты получателя (в P2P).	DEPOSITED, REVERSED, REFUNDED, DECLINED_BY_TIMEOUT
`isInternationalP2P`	Является ли P2P-транзакция межстрановой.	DEPOSITED, REVERSED, REFUNDED, DECLINED_BY_TIMEOUT
`recipientData`	Информация о получателе P2P.	DEPOSITED, REVERSED, REFUNDED, DECLINED_BY_TIMEOUT
`transactionTypeIndicator`	Информация о получателе P2P. Возможные значения: `A` - перевод денег без смены владельца денег `B` - Business-to-business `D` - перевод для целей выплат.	DEPOSITED, REVERSED, REFUNDED, DECLINED_BY_TIMEOUT
`operationType`	Тип операции P2P: AFT/OCT.	DEPOSITED, REVERSED, REFUNDED, DECLINED_BY_TIMEOUT
`debitBankName`	Название банка, выпустившего карту для списания (в P2P).	DEPOSITED, REVERSED, REFUNDED, DECLINED_BY_TIMEOUT
`debitPanCountryCode`	Код страны карты для списания (в P2P).	DEPOSITED, REVERSED, REFUNDED, DECLINED_BY_TIMEOUT
`p2pDebitRrn`	RRN (Reference Retrieval Number) операции списания P2P.	DEPOSITED, REVERSED, REFUNDED, DECLINED_BY_TIMEOUT
`taxSystem`	Система налогообложения, доступны следующие значения:: `0` - общая; `1` - упрощенная, доход; `2` - упрощенная, доходы минус расходы; `3` - единый налог на вмененный доход; `4` - единый сельскохозяйственный налог; `5` - патентная система налогообложения.	DEPOSITED, APPROVED, REVERSED, REFUNDED, DECLINED_BY_TIMEOUT, DECLINED_CARDPRESENT
`inn`	ИНН продавца.	DEPOSITED, APPROVED, REVERSED, REFUNDED, DECLINED_BY_TIMEOUT, DECLINED_CARDPRESENT
`orgName`	Полное наименование продавца на русском языке.	DEPOSITED, APPROVED, REVERSED, REFUNDED, DECLINED_BY_TIMEOUT, DECLINED_CARDPRESENT