Уведомления

Уведомление — HTTP запрос от системы к вашему сайту. Подобные запросы также называют callback или webhook. В системе предусмотрено несколько видов уведомлений: для проверки возможности выполнить оплату, для информирования об успешных и неуспешных платежах, а также для оповещения об изменении подписок на рекуррентные платежи.


Включение и отключение уведомлений, а также настройка адресов и форматов уведомлений выполняется в ЛК.


Если вы используете уведомления для проверки и изменения статусов заказов в вашей системе, мы рекомендуем сверять сумму, номер заказа и идентификатор аккаунта плательщика.

Check

Выполняется после того, как держатель заполнил платежную форму и нажал кнопку «Оплатить».

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


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

Параметр Формат Применение Описание
TransactionId Int64 Обязательный Номер транзакции в системе
Amount Numeric, точка в качестве разделителя, две цифры после точки. Обязательный Сумма оплаты из параметров виджета.
Currency String Обязательный Валюта: KZT/RUB/USD/EUR/GBP из параметров виджета (см. справочник)
DateTime yyyy-MM-dd HH:mm:ss Обязательный Дата/время создания платежа во временной зоне UTC
CardFirstSix String(6) Обязательный Первые 6 цифр номера карты
CardLastFour String(4) Обязательный Последние 4 цифры номера карты
CardType String Обязательный Платежная система карты: Visa или MasterCard или Maestro
CardExpDate String Обязательный Срок действия карты в формате MM/YY
TestMode Bit (1 или 0) Обязательный Признак тестового режима
Status String Обязательный Статус платежа в случае успешного завершения: Completed — для одностадийных платежей, Authorized — для двухстайдиных
InvoiceId String Необязательный Номер заказа из параметров виджета
AccountId String Необязательный Идентификатор пользователя из параметров виджета
SubscriptionId String Необязательный Идентификатор подписки (для рекуррентных платежей)
Name String Необязательный Имя держателя карты
Email String E-mail адрес плательщика
IpAddress String Необязательный IP адрес плательщика
IpCountry String(2) Необязательный Двухбуквенный код страны нахождения плательщика по ISO3166-1
IpCity String Необязательный Город нахождения плательщика
IpRegion String Необязательный Регион нахождения плательщика
IpDistrict String Необязательный Округ нахождения плательщика
Issuer String Необязательный Название банка-эмитента карты
IssuerBankCountry String(2) Необязательный Двухбуквенный код страны эмитента карты по ISO3166-1
Description String Необязательный Назначение оплаты из параметров виджета
Data Json Необязательный Произвольный набор параметров, переданный из виджета

В ответ на запрос система ожидает получить ответ в JSON формате с обязательным параметром code:

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

Код Значение Результат
0 Платеж может быть проведен Система выполнит авторизацию платежа
10 Неверный номер заказа Платеж будет отклонен
11 Неверная сумма Платеж будет отклонен
13 Платеж не может быть принят Платеж будет отклонен
20 Платеж просрочен Платеж будет отклонен, плательщик получит соответствующее уведомление


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

Pay

Выполняется после того, как оплата была успешно проведена — получена авторизация эмитента.

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


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

Параметр Формат Применение Описание
TransactionId Int64 Обязательный Номер транзакции в системе
Amount Numeric, точка в качестве разделителя, две цифры после точки. Обязательный Сумма оплаты из параметров виджета.
Currency String Обязательный Валюта: KZT/RUB/USD/EUR/GBP из параметров виджета (см. справочник)
DateTime yyyy-MM-dd HH:mm:ss Обязательный Дата/время создания платежа во временной зоне UTC
CardFirstSix String(6) Обязательный Первые 6 цифр номера карты
CardLastFour String(4) Обязательный Последние 4 цифры номера карты
CardType String Обязательный Платежная система карты: Visa или MasterCard или Maestro
CardExpDate String Обязательный Срок действия карты в формате MM/YY
TestMode Bit (1 или 0) Обязательный Признак тестового режима
Status String Обязательный Статус платежа после авторизации: Completed — для одностадийных платежей, Authorized — для двухстайдиных
InvoiceId String Необязательный Номер заказа из параметров виджета
AccountId String Необязательный Идентификатор пользователя из параметров виджета
SubscriptionId String Необязательный Идентификатор подписки (для рекуррентных платежей)
Name String Необязательный Имя держателя карты
Email String E-mail адрес плательщика
IpAddress String Необязательный IP адрес плательщика
IpCountry String(2) Необязательный Двухбуквенный код страны нахождения плательщика по ISO3166-1
IpCity String Необязательный Город нахождения плательщика
IpRegion String Необязательный Регион нахождения плательщика
IpDistrict String Необязательный Округ нахождения плательщика
Issuer String Необязательный Название банка-эмитента карты
IssuerBankCountry String(2) Необязательный Двухбуквенный код страны эмитента карты по ISO3166-1
Description String Необязательный Назначение оплаты из параметров виджета
Data Json Необязательный Произвольный набор параметров, переданный из виджета
Token String Необязательный Токен карты для повторных платежей без ввода реквизитов

В ответ на запрос система ожидает получить ответ в JSON формате с обязательным параметром code:

Код определяет результат обработки сервером ТСП уведомления о платеже и может принимать единственное значение:

Код Значение
0 Платеж зарегистрирован


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

Fail

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

Стоит учитывать, что факт отказа в оплате не является конечным — пользователь может оплатить со второго раза.


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

Параметр Формат Применение Описание
TransactionId Int64 Обязательный Номер транзакции в системе
Amount Numeric, точка в качестве разделителя, две цифры после точки. Обязательный Сумма оплаты из параметров виджета.
Currency String Обязательный Валюта: KZT/RUB/USD/EUR/GBP из параметров виджета (см. справочник)
DateTime yyyy-MM-dd HH:mm:ss Обязательный Дата/время создания платежа во временной зоне UTC
CardFirstSix String(6) Обязательный Первые 6 цифр номера карты
CardLastFour String(4) Обязательный Последние 4 цифры номера карты
CardType String Обязательный Платежная система карты: Visa или MasterCard или Maestro
CardExpDate String Обязательный Срок действия карты в формате MM/YY
TestMode Bit (1 или 0) Обязательный Признак тестового режима
Reason String Обязательный Причина отказа
ReasonCode Int Обязательный Код ошибки (см. справочник)
InvoiceId String Необязательный Номер заказа из параметров виджета
AccountId String Необязательный Идентификатор пользователя из параметров виджета
SubscriptionId String Необязательный Идентификатор подписки (для рекуррентных платежей)
Name String Необязательный Имя держателя карты
Email String E-mail адрес плательщика
IpAddress String Необязательный IP адрес плательщика
IpCountry String(2) Необязательный Двухбуквенный код страны нахождения плательщика по ISO3166-1
IpCity String Необязательный Город нахождения плательщика
IpRegion String Необязательный Регион нахождения плательщика
IpDistrict String Необязательный Округ нахождения плательщика
Issuer String Необязательный Название банка-эмитента карты
IssuerBankCountry String(2) Необязательный Двухбуквенный код страны эмитента карты по ISO3166-1
Description String Необязательный Назначение оплаты из параметров виджета
Data Json Необязательный Произвольный набор параметров, переданный из виджета

В ответ на запрос система ожидает получить ответ в JSON формате с обязательным параметром code:

Код определяет результат обработки сервером ТСП уведомления об отклоненном платеже и может принимать единственное значение:

Код Значение
0 Попытка зарегистрирована


Confirm

Выполняется после подтверждения платежа, проведенного по двустадийной схеме.


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

Параметр Формат Применение Описание
TransactionId Целое число Обязательный Номер транзакции в системе
Amount Numeric, точка в качестве разделителя, две цифры после точки. Обязательный Сумма оплаты из параметров виджета.
Currency String Обязательный Валюта: KZT/RUB/USD/EUR/GBP из параметров виджета (см. справочник)
DateTime yyyy-MM-dd HH:mm:ss Обязательный Дата/время создания платежа во временной зоне UTC
CardFirstSix String(6) Обязательный Первые 6 цифр номера карты
CardLastFour String(4) Обязательный Последние 4 цифры номера карты
CardType String Обязательный Платежная система карты: Visa или MasterCard или Maestro
CardExpDate String Обязательный Срок действия карты в формате MM/YY
TestMode Bit (1 или 0) Обязательный Признак тестового режима
Status String Обязательный Статус платежа после авторизации: Completed
InvoiceId String Необязательный Номер заказа из параметров виджета
AccountId String Необязательный Идентификатор пользователя из параметров виджета
SubscriptionId String Необязательный Идентификатор подписки (для рекуррентных платежей)
Name String Необязательный Имя держателя карты
Email String E-mail адрес плательщика
IpAddress String Необязательный IP адрес плательщика
IpCountry String(2) Необязательный Двухбуквенный код страны нахождения плательщика по ISO3166-1
IpCity String Необязательный Город нахождения плательщика
IpRegion String Необязательный Регион нахождения плательщика
IpDistrict String Необязательный Округ нахождения плательщика
Issuer String Необязательный Название банка-эмитента карты
IssuerBankCountry String(2) Необязательный Двухбуквенный код страны эмитента карты по ISO3166-1
Description String Необязательный Назначение оплаты из параметров виджета
Data Json Необязательный Произвольный набор параметров, переданных в транзакцию
Token String Необязательный Токен карты для повторных платежей без ввода реквизитов

В ответ на запрос система ожидает получить ответ в JSON формате с обязательным параметром code:

Код определяет результат обработки сервером ТСП уведомления о платеже и может принимать единственное значение:

Код Значение
0 Платеж зарегистрирован


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

Refund

Выполняется в случае, если платеж был возвращен (полностью или частично) по вашей инициативе через API или личный кабинет.


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

Параметр Формат Применение Описание
TransactionId Int64 Обязательный Номер транзакции возврата в системе
PaymentTransactionId Int Обязательный Номер оригинальной транзакции оплаты в системе
Amount Numeric, точка в качестве разделителя, две цифры после точки. Обязательный Сумма возврата в валюте платежа
DateTime yyyy-MM-dd HH:mm:ss Обязательный Дата/время возврата по временной зоне UTC
InvoiceId String Необязательный Номер заказа оригинальной операции
AccountId String Необязательный Идентификатор пользователя оригинальной операции
Email String Необязательный E-mail адрес плательщика

В ответ на запрос система ожидает получить ответ в JSON формате с обязательным параметром code:

Код определяет результат обработки сервером ТСП уведомления о платеже и может принимать единственное значение:

Код Значение
0 Возврат зарегистрирован


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

Recurrent

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


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

Параметр Формат Применение Описание
Id Int Обязательный Идентификатор подписки
AccountId String Обязательный Идентификатор пользователя
Description String Обязательный Назначение платежа в свободной форме
Email String Обязательный E-mail плательщика
Amount Numeric Обязательный Сумма платежа
Currency String Обязательный Валюта: KZT/RUB/USD/EUR/GBP из параметров виджета. (см. справочник)
RequireConfirmation Bool Обязательный Если значение true — платеж будет выполнен по двустадийной схеме
StartDate DateTime Обязательный Дата и время первого платежа по плану во временной зоне UTC
Interval String Обязательный Интервал. Возможные значения: Week, Month
Period Int Обязательный Период. В комбинации с интервалом 1 Month значит раз в месяц, а 2 Week — раз в две недели.
Status String Обязательный Статус
SuccessfulTransactionsNumber Int Обязательный Количество успешных платежей
FailedTransactionsNumber Int Обязательный Количество неуспешных платежей (обнуляется после каждого успешного)
MaxPeriods Int Необязательный Максимальное количество платежей в подписке
LastTransactionDate yyyy-MM-dd HH:mm:ss Необязательный Дата и время последнего успешного платежа во временной зоне UTC
NextTransactionDate yyyy-MM-dd HH:mm:ss Необязательный Дата и время следующего платежа во временной зоне UTC

В ответ на запрос система ожидает получить ответ в JSON формате с обязательным параметром code:

Код определяет результат обработки сервером ТСП уведомления об изменении подписки и может принимать единственное значение:

Код Значение
0 Изменения зарегистрированы


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

Проверка уведомлений

Все виды уведомлений — check, pay, fail, confirm, refund и recurrent содержат HTTP заголовок Content-HMAC в котором находится проверочное значение запроса, вычисленное с помощью алгоритма HMAC. Если вам необходимо проверять подлинность и целостность уведомлений, вы можете вычислить проверочное значение на своей стороне и сравнить с тем, что пришло в запросе. Совпадение подтверждает, что уведомление было отправлено от нас и пришло к вам в оригинальном виде.

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

  • Для уведомлений, отправленных методом POST, сообщением является тело запроса. Для GET — строка параметров.
  • Хэш вычисляется функцией SHA256.
  • В качестве ключа используется API Secret, который можно получить в личном кабинете.
  • Вычисленное значение передается в кодировке base64.

Примеры вычисления HMAC на разных языках программирования.

Адреса, с которых система отправляет уведомления — это 130.193.70.192 и 185.98.85.109.