Оповещения
При проведении платежа Payment Page отправляет вам оповещение, которое содержит информацию о последней операции при проведении платежа. Формат оповещений может настраиваться в зависимости от ваших предпочтений.
Метод
Оповещение представляет собой HTTP POST запрос, отправляемый на предоставленный URL после завершения обработки платежа. Параметры оповещения передаются в теле ответа, при этом массив параметров в формате JSON сконвертирован в единую строку.
Оповещения подписываются. Дополнительные сведения см. в Работа с подписью к данным.
Условия отправки оповещений
Оповещения отправляются в следующих случаях:
- для дальнейшей обработки платежа требуется аутентификация пользователя в программе 3-D Secure (при получении отказа от внешнего провайдера и при возможности проведения повторной попытки платежа на данном этапе может быть отправлено несколько оповещений со статусом платежа awaiting 3ds result или awaiting redirect result; подробную информацию о функциональности уточняйте у вашего курирующего менеджера);
- завершена обработка операции на стороне платежной платформы;
- сгенерирован токен для банковской карты.
Доставка оповещений
Оповещения отправляются сразу же после проведения операции.
Факт доставки оповещения в вашу систему фиксируется на стороне Gate в ответе от вашей системы. Ответ должен содержать HTTP заголовок с кодом ответа 200 ОК.
В случае если необходимо отложить отправку оповещения, в запросе на проведение платежа передайте параметр delay в объекте callback с необходимым значением в секундах. Максимальное значение задержки отправки 600 секунды.
Если оповещение не было доставлено, Gate отправляет его по следующему расписанию:
- 6 попыток с интервалом в 10 сек.;
- далее 62 попытки в течение четырех часов с увеличивающимся интервалом (интервал увеличивается в соответствии с формулой
70 + 10·1,12n-4
, где n — порядковый номер попытки отправки); - потом каждые 4 часа до достижения максимального количества попыток.
Максимально Gate выполняет 120 попыток доставки оповещения в течение 11 суток. Расписание отправки может незначительно изменяться в зависимости от загрузки системы.
Адреса доставки оповещений
Оповещения отправляются на URL, который указывается отдельно для каждого проекта. Вы можете предоставить одинаковые или различные URL для отправки оповещений в зависимости от статуса платежа и типа операции.
IP-адреса, с которых приходят оповещения, узнавайте в службе поддержки ECommPay.
Обработка оповещений
При обработке оповещений ваша система должна следовать следующим правилам:
- Принимать оповещения только с IP адреса, полученного от службы поддержки ECommPay.
- На успешно принятые оповещения ответ вашей системы должен быть
HTTP 200 OK
. - На оповещения, которые уже ранее были приняты вашей системой, ответ должен быть также
HTTP 200 OK
. - На оповещения, принятые с ошибкой, ответ вашей системы должен быть
HTTP 400 Bad Request
(например, если вам не удалось преобразовать строку параметров в массив) илиHTTP 500 Internal Server Error
(например, если оповещение пришло на неправильный URL-адрес). - Повторные оповещения, которые ранее не были приняты или были приняты с ошибкой, ваша система должна попытаться принять еще раз.
- Ваша система не должна ограничивать время на доставку оповещений, доставка оповещений может происходить с задержкой.
Параметры, передаваемые в оповещениях
Набор параметров, передаваемых в оповещении, может отличаться в зависимости от типа операции и конфигурации оповещений. В этом разделе приведены описания параметров, используемых в типовых случаях. Словом default
отмечены объекты и параметры, используемые по умолчанию для всех типовых оповещений.
Параметр | Описание | tree |
---|---|---|
account |
Объект, содержащий данные банковской карты или учетной записи пользователя | 10 |
card_holder |
Имя владельца банковской карты | 10-10 10 |
expiry_month |
Месяц срока действия банковской карты | 10-20 10 |
expiry_year |
Год срока действия банковской карты | 10-30 10 |
id |
Идентификатор сохраненной карты в Gate | 10-40 10 |
number |
Маскированный номер банковской карты или учетной записи пользователя. Пример: |
10-50 10 |
token |
Токен банковской карты пользователя. Токен генерируется автоматически при успешной оплате при условии, что эта возможность была активирована при подключении | 10-60 10 |
type |
Тип банковской карты или наименование оператора мобильной связи, который использовался для оплаты. Доступные значения типов карт см. в разделе Общая информация
. Доступные значения для мобильных операторов:
|
10-70 10 |
acs |
Объект, содержащий результаты аутентификации пользователя средствами 3‑D Secure, если оплата проводилась с помощью банковской карты, поддерживающей в 3‑D Secure | 20 |
acs_url |
URL-адрес веб-страницы ACS-сервера банка-эмитента | 20-10 20 |
md |
Набор технических данных мерчанта в платежной системе | 20-20 20 |
pa_req |
Запрос аутентификации, который следует отправить в банк-эмитент. Содержит закодированную информацию о владельце карты, мерчанте и платеже | 20-30 20 |
avs_data |
Объект, который содержит данные для AVS-проверки (Address Verification Service). Подробнее см. Проверка Address Verification Service | 30 |
avs_post_code |
Почтовый индекс пользователя | 30-10 30 |
avs_street_address |
Адрес пользователя | 30-20 30 |
avs_result |
Результат AVS-проверки (Address Verification Service). Подробнее см. в разделе Проверка Address Verification Service | 40 |
bank |
Объект, содержащий данные о банке-эмитенте карты пользователя | 50 |
name |
Наименование банка-эмитента карты пользователя | 50-10 50 |
customer |
Объект, содержащий информацию о пользователе, совершающем платеж | 70 |
billing |
Объект, содержащий информацию о платёжном адресе пользователя | 70-10 70 |
address |
Платёжный адрес пользователя | 70-10-10 70-10 |
city |
Город платёжного адреса пользователя | 70-10-20 70-10 |
country |
Страна платёжного адреса пользователя в формате ISO 3166-1 alpha-2. Пример: |
70-10-30 70-10 |
postal |
Индекс платёжного адреса пользователя | 70-10-40 70-10 |
region |
Район, область, край или республика платёжного адреса пользователя | 70-10-50 70-10 |
city |
Город пользователя. Пример: |
70-20 70 |
country |
Страна пользователя в формате ISO 3166-1 alpha-2, переданная в начальном запросе. Пример: |
70-30 70 |
day_of_birth |
Дата рождения пользователя в формате ДД-ММ-ГГГГ. Пример: |
70-40 70 |
first_name |
Имя пользователя. Пример: |
70-50 70 |
id |
Уникальный идентификатор пользователя в проекте | 70-60 70 |
ip_address |
IP-адрес пользователя, переданный в начальном запросе | 70-70 70 |
last_name |
Фамилия пользователя. Пример: |
70-80 70 |
middle_name |
Отчество пользователя. Пример: |
70-90 70 |
phone |
Телефон пользователя. Цифровое значение: от 4 до 24 цифр | 70-100 70 |
decision |
Строка, содержащая решение системы Risk Control System о прохождении платежа. | 80 |
decision_message |
Массив строк, содержащих сообщения от Risk Control System о прохождении платежа. Пример: |
90 |
display_data |
Объект, содержащий переданные от внешней платежной системы данные для отображения QR-кода для оплаты пользователям | 100 |
errors |
Массив сообщений об ошибках, связанных с проведением платежа | 110 |
ErrorItem |
Объект, содержащий информацию об одной ошибке | 110-10 110 |
code |
Код ошибки | 110-10-10 110-10 |
description |
Параметр, описывающий причину ошибки | 110-10-10 110-10 |
field |
Параметр, в котором допущена ошибка, если удалось определить неверный параметр | 110-10-20 110-10 |
message |
Сообщение, уточняющее причину ошибки | 110-10-30 110-10 |
interface_type |
Объект, содержащий информацию об источнике запроса на проведение платежа | 120 |
id |
Параметр, уточняющий, какой интерфейс использовался для отправки запроса на проведение платежа. Возможные значения:
|
120-10 120 |
user |
Параметр, уточняющий пользователя Dashboard. отправившего запрос на проведение платежа. Пример: |
120-20 120 |
operation |
Объект, содержащий информацию об операции, по которой отправлено оповещение | 130 |
code |
Унифицированный код ответа Gate. Подробнее см. в Информация об операциях | 130-10 130 |
created_date |
Дата и время создания операции | 130-20 130 |
date |
Дата и время последнего обновления статуса операции в Gate | 130-30 130 |
eci |
Индикатор, отображающий результат аутентификации пользователя с использованием 3‑D Secure. Подробнее см. Индикаторы ECI | 130-40 130 |
id |
Уникальный идентификатор операции в Gate | 130-50 130 |
message |
Унифицированное сообщение Gate. Подробнее см. в Информация об операциях | 130-60 130 |
provider |
Объект, который содержит информацию внешнего провайдера о результате выполнения платежа | 130-70 130 |
auth_code |
Код авторизации, полученный от внешнего провайдера | 130-70-10 130-70 |
date |
Дата и время завершения обработки платежа внешним провайдером. Пример: |
130-70-20 130-70 |
endpoint_id |
CRC32-идентификатор платежного шлюза внешнего провайдера. * В некоторых случаях, с учётом особенностей платёжных систем и провайдеров, у этого параметра может быть тип integer |
130-70-30 130-70 |
id |
Внешний провайдер, через который была проведена операция | 130-70-40 130-70 |
payment_id |
Уникальный идентификатор платежа в системе внешнего провайдера | 130-70-50 130-70 |
request_id |
Уникальный идентификатор последнего запроса, относящегося к данной операции, в Gate | 130-80 130 |
status |
Статус проведенной операции | 130-90 130 |
sum_converted |
Объект, содержащий валюту платежной системы и сумму операции, переведенной в эту валюту | 130-100 130 |
amount |
Сумма операции в дробных единицах валюты платежной системы | 130-100-10 130-100 |
currency |
Валюта платежной системы в формате ISO 4217 alpha-3 | 130-100-20 130-100 |
sum_initial |
Объект, содержащий сумму и валюту операции, переданные в запросе | 130-110 130 |
amount |
Сумма операции, переданная в начальном запросе, в дробных единицах валюты | 130-110-10 130-110 |
currency |
Валюта операции в формате ISO 4217 alpha-3, переданная в начальном запросе | 130-110-20 130-110 |
type |
Тип проведенной операции | 130-120 130 |
payment |
Объект, содержащий данные о платеже | 140 |
cascading_with_redirect |
Необходимость перенаправления пользователя на другой ACS URL для повторной попытки проведения аутентификации 3D-Secure , в случае получения отказа от внешнего провайдера, а также отображение страницы с ошибкой и кнопкой Попробовать еще раз. Доступные значения:
|
140-10 140 |
date |
Дата и время последнего обновления статуса платежа в Gate. Пример: |
140-20 140 |
description |
Описание платежа, переданное в начальном запросе | 140-30 140 |
id |
Уникальный идентификатор платежа в веб-сервисе | 140-40 140 |
is_new_attempts_available |
Признак возможности проведения повторной оплаты:
|
140-50 140 |
method |
Платежный метод. Пример: |
140-60 140 |
merchant_refund_id |
Уникальный идентификатор возврата в системе мерчанта. Пример: |
140-61 140 |
OperationFee |
Объект, содержащий информацию о комиссии за операцию, начисленной ECommPay | 140-70 140 |
amount |
Сумма комиссии за операцию в дробных единицах валюты, если она включена в общую сумму платежа | 140-70-10 140-70 |
currency |
Валюта, в которой начислена комиссия, в формате ISO 4217 alpha-3. Пример: |
140-70-20 140-70 |
sum_with_surcharge |
Общая сумма операции и надбавленной комиссии в дробных единицах валюты | 140-70-30 140-70 |
surcharge_amount |
Сумма надбавленной к сумме платежа комиссии в дробных единицах валюты. Применяется для МФО | 140-70-40 140-70 |
surcharge_currency |
Валюта, в которой начислена надбавленная к сумме платежа комиссия, в формате ISO 4217 alpha-3 | 140-70-50 140-70 |
region |
Регион страны, где проводится операция по банковской карте. Доступные значения см. в справочнике Коды регионов | 140-80 140 |
status |
Cтатус платежа. Пример: |
140-90 140 |
sum |
Объект, содержащий сумму платежа с учетом возвратов и валюту, переданную в начальном запросе | 140-100 140 |
amount |
Сумма платежа с учетом возвратов, в дробных единицах валюты | 140-100-10 140-100 |
currency |
Валюта платежа в формате ISO 4217 alpha-3, переданная в начальном запросе. Пример: |
140-100-20 140-100 |
timeout_attempts |
Время (в секундах), оставшееся до окончания периода, в течение которого возможно проведение повторной оплаты. Параметр передается при включении повторных оплат при подключении через Payment Page | 140-110 140 |
type |
Тип проведенного платежа. Пример: |
140-120 140 |
project_id |
Уникальный идентификатор проекта в Gate | 150 |
provider_extra_fields |
Объект, содержащий поступившие от внешней платежной системы данные, необходимые для завершения платежа или для отчетности | 160 |
recurring |
Объект, содержащий данные регистрации платежа как рекуррентного. Объект не передается, если в начальном запросе на оплату было передано значение recurring_register=1 и оплата успешно проведена | 170 |
currency |
Валюта рекуррентного платежа в формате ISO 4217 alpha-3. Пример: |
170-10 170 |
id |
Идентификатор рекуррентного платежа | 170-20 170 |
register_payment_id |
Идентификатор рекуррентного платежа на стороне мерчанта | 170-30 170 |
status |
Статус повторяемой оплаты. Возможные значения:
|
170-40 170 |
type |
Тип рекуррентного платежа. Возможные значения:
|
170-50 170 |
valid_thru |
Дата истечения срока действия идентификатора рекуррентного платежа | 170-60 170 |
redirect_data |
Объект, содержащий данные для перенаправления пользователя к платежному методу для проведения платежа | 180 |
body |
Набор параметров, содержащих данные для перенаправления | 180-10 180 |
method |
Метод отправки запроса: POST или GET
|
180-20 180 |
url |
URL-адрес для перенаправления пользователя | 180-30 180 |
signature |
Подпись оповещения. Подробнее о проверке подписей оповещений см. Работа с подписью к данным | 190 |