PaymentNut может отправлять уведомления на Ваш веб–сайт (URL), которые так же известны как обратные вызовы или вебхуки. Предусмотрены следующие уведомления: при авторизации транзакции оплаты (1), при подтверждении двухстадийной транзакции оплаты (2), при неуспешной транзакции оплаты (3) и при отмене двухстадийной транзакции оплаты (4).

Уведомление об авторизации транзакции оплаты (1) отправляется после того, как оплата была успешно проведена и получена авторизация банка–эмитента карты. При одностадийных транзакциях Вы можете оказывать услуги плательщику после получения данного уведомления. Если транзакция двухстадийная (при вызове страницы оплаты через API для переменной manual_confirmation задано значение "1" или в ЛК была включена опция "заморозка средств на карте" при создании объекта Продукт или Счет), то уведомление об авторизации обозначает успешную заморозку средств на карте плательщика (далее требуется с Вашей стороны выполнить подтверждение или отмену через ЛК или API, автоматическое подтверждение происходит через 7 дней после авторизации).

Уведомление о подтверждении двухстадийной транзакции оплаты (2) отправляется после того, как транзакция была подтверждена (через ЛК, API или автоматически на 7-ой день). Данное уведомление не отправляется для одностадийных транзакций. Данное уведомление обозначает списание ранее замороженных средств на карте плательщика – Вы можете оказывать услуги плательщику после получения данного уведомления. Т.к. при двухстадийных транзакциях сумма подтверждения может отличаться от изначальной суммы платежа в меньшую сторону, при получении уведомления о подтверждении следует дополнительно зафиксировать подтвержденную (финальную) сумму транзакции.

Уведомление о неуспешной транзакции оплаты (3) отправляется после того, как получен отказ авторизации банка–эмитента карты (при одностадийных и двухстадийных транзакциях). Обратите внимание, что неуспешные транзакции в некоторых случаях позднее могут получить статус успешных – это следует учитывать при обработке уведомления о неуспешной транзакции.

Уведомление об отмене двухстадийной транзакции оплаты (4) отправляется после того, как была произведена разблокировка ранее заблокированных средств на карте.

Уведомления о транзакциях возвратов не предусмотрены.

Обратите внимание, что уведомления ставятся в очередь на отправку (очередь обрабатывается раз в 1–2 минуты) и на момент отправки уведомления транзакция может получить другой статус (например, транзакция была авторизована и сразу же подтверждена) – значение переменной status (ниже в таблице) указывает статус транзакции именно на момент отправки уведомления и может отличаться от типа уведомления (например, уведомление об авторизации, однако статус транзакции – подтверждена). В связи с этим следует учитывать тип получаемого уведомления (переменная notification_type)

Включение уведомлений и настройка URL адресов уведомлений осуществляется через раздел настроек Проекта в Личном Кабинете.

Cтатус отправки/получения уведомлений отображен в карточке каждой транзакции в ЛК.

Метод отправки: POST
Параметры уведомления:

Параметр	Значение
notification_type	Тип уведомления: pay – уведомление об авторизации транзакции оплаты (1) confirm – уведомление о подтверждении двухстадийной транзакции оплаты (2) fail – уведомление о неуспешной транзакции оплаты (3) cancel – уведомление об отмене двухстадийной транзакции оплаты (4)
transaction_id	Идентификатор транзакции
payment_method	Метод оплаты: 1 – банковской картой 2 – по QR коду через Систему быстрых платежей в РФ (СБП)
date_created	Время создания (Unix timestamp)
date_last_declined	Время отклонения (Unix timestamp)
date_authorized	Время авторизации (Unix timestamp)
date_completed	Время подтверждения (Unix timestamp)
date_cancelled	Время отмены (Unix timestamp)
two_step_transaction	Признак двухстадийной транзакции: 0 – Нет (одностадийная) 1 – Да (двухстадийная)
status	Статус транзакции на момент отправки уведомления (может отличаться от типа уведомления): 2 – Отклонена 3 – Авторизована (при двухстадийных транзакциях) 4 – Завершена (при одностадийных транзакциях и при двухстадийных транзакциях после их подтверждения) 5 – Отменена (при двухстадийных транзакциях)
failure_reason	Причина отклонения транзакции
description	Назначение платежа
amount	Сумма
currency_code	Код валюты (ISO 4217)
originator_object_type	Связанный объект, которым инициализирована транзакция: 1 – Счет 2 – Продукт 3 – Вызов по API 4 – Подписка
originator_object_id	Идентификатор связанного объекта
subscription_enabled	Транзакция по подписке: 1 – Да 0 – Нет
subscription_initial_transaction	Транзакция по подписке является установочным платежом: 1 – Да 0 – Нет (является регулярным платежом)
subscription_id	Идентификатор подписки
is_subscription_transaction_retry	Транзакция является повторной попыткой неудачного регулярного платежа по подписке: 1 – Да 0 – Нет
subscription_originating_failed_transaction_id	Идентификатор неудачной регулярной транзакции по подписке, которой инициирована настоящая транзакция (если is_subscription_retry=1)
reference_1	Значение поля reference_1 (при вызове по API)
reference_2	Значение поля reference_2 (при вызове по API)
reference_3	Значение поля reference_3 (при вызове по API)
custom_data	Значение поля custom_data (при вызове по API)
coupon_code	Код купона акции
promotion_id	Идентификатор акции кода купона
card_first_six	Первые 6 цифр номера карты
card_last_four	Последние 4 цифры номера карты
card_type	Платежная система карты
card_issuer	Эмитент карты
card_issuer_country	Код страны эмитента карты (ISO 3166-1 alpha-2)
transaction_email	Email введеный при оплате
signature	Значение подписи; составляется на основе значений нескольких вышеуказанных параметров и API ключа проекта, см. ниже

Транзакции по оплатам через СБП

При оплате по QR коду через Систему быстрых платежей в РФ (СБП) (payment_method=2), значения следующих переменных передаются пустыми: card_first_six, card_last_four, card_type, card_issuer, card_issuer_country.


Формирование значения подписи

Подпись в уведомлении нужна для того, что бы третье лицо не могло отправить уведомление от имени PaymentNut, не зная при этом API ключ Вашего Проекта. Значение API ключа доступно в настройках Проекта Личного Кабинета его владельцу. В подпись, кроме API ключа, входят значения некоторых параметров уведомления, финальное значение подписи шифруется по алгоритму MD5.

Для формирования значения подписи, возьмите полученные значения параметров следующим образом: transaction_id, status, amount, currency_code, originator_object_type, originator_object_id, reference_1, reference_2, reference_3, api_key в одну строку (разделяя значения запятой и пробелом) и зашифруйте ее по алгоритму MD5. Далее, сравните вычисленное значение подписи с полученным значением подписи.

Внимание! В случае если значение переменной custom_data задано, то значение подписи следует составить следующим образом: transaction_id, status, amount, currency_code, originator_object_type, originator_object_id, reference_1, reference_2, reference_3, custom_data, api_key

Например (PHP):

$inbound_notification_type=$_POST['notification_type'];
$inbound_transaction_id=$_POST['transaction_id'];
$inbound_payment_method=$_POST['payment_method'];
$inbound_transaction_date_created=$_POST['date_created'];
$inbound_transaction_date_last_declined=$_POST['date_last_declined'];
$inbound_transaction_date_authorized=$_POST['date_authorized'];
$inbound_transaction_date_completed=$_POST['date_completed'];
$inbound_transaction_date_cancelled=$_POST['date_cancelled'];
$inbound_two_step_transaction=$_POST['two_step_transaction'];
$inbound_status=$_POST['status'];
$inbound_failure_reason=$_POST['failure_reason'];
$inbound_description=$_POST['description'];
$inbound_amount=$_POST['amount'];
$inbound_currency_code=$_POST['currency_code'];
$inbound_originator_object_type=$_POST['originator_object_type'];
$inbound_originator_object_id=$_POST['originator_object_id'];
$inbound_subscription_enabled=$_POST['subscription_enabled'];
$inbound_subscription_initial_transaction=$_POST['subscription_initial_transaction'];
$inbound_subscription_id=$_POST['subscription_id'];
$inbound_is_subscription_transaction_retry=$_POST['is_subscription_transaction_retry'];
$inbound_subscription_originating_failed_transaction_id=$_POST['subscription_originating_failed_transaction_id'];
$inbound_reference_1=$_POST['reference_1'];
$inbound_reference_2=$_POST['reference_2'];
$inbound_reference_3=$_POST['reference_3'];
$inbound_custom_data=$_POST['custom_data'];
$inbound_coupon_code=$_POST['coupon_code'];
$inbound_promotion_id=$_POST['promotion_id'];
$inbound_card_first_six=$_POST['card_first_six'];
$inbound_card_last_four=$_POST['card_last_four'];
$inbound_card_type=$_POST['card_type'];
$inbound_card_issuer=$_POST['card_issuer'];
$inbound_card_issuer_country=$_POST['card_issuer_country'];
$inbound_transaction_email=$_POST['transaction_email'];
$inbound_signature=$_POST['signature'];

$api_key='8E4D3A85BC544BB8FB9EC6E4FFCA1582';

if (strlen($inbound_custom_data)==0)
{
$computed_signature=md5("$inbound_transaction_id, $inbound_status, $inbound_amount, $inbound_currency_code, $inbound_originator_object_type, $inbound_originator_object_id, $inbound_reference_1, $inbound_reference_2, $inbound_reference_3, $api_key");
}
else
{
$computed_signature=md5("$inbound_transaction_id, $inbound_status, $inbound_amount, $inbound_currency_code, $inbound_originator_object_type, $inbound_originator_object_id, $inbound_reference_1, $inbound_reference_2, $inbound_reference_3, $inbound_custom_data, $api_key");
}

if ($computed_signature===$inbound_signature)
{
echo 1;

//подпись верна, можно обработать уведомление
}

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

В ответ на прием уведомления, ожидается получить простой строчный ответ с цифрой 1 (один), как показано в примере выше (echo 1;).

В случае невозможности соединения с URL уведомления (таймаут попытки соединения 10 секунд) или при отсутствии ответа 1, будет предпринято еще 48 попыток отправить данное уведомление с интервалом в 90 минут. На 49-ую попытку, на электронную почту владельца проекта, отправляется сообщение о невозможности отправить уведомление (или получить корректный ответ на уведомление). Во избежание избытка писем, за каждые 48 часов отправляется не более трех подобных сообщений. В случае если более десяти уведомлений не может быть отправлено/получено, то уведомления автоматически отключаются. Вы можете решить проблему со стороны Вашего сервера и включить отправку уведомлений повторно (ЛК > Настройки проекта > Уведомления). Cтатус отправки/получения уведомлений отображен в карточке каждой транзакции в ЛК.