Оповещения

При проведении платежа 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.

Обработка оповещений

При обработке оповещений ваша система должна следовать следующим правилам:

  1. Принимать оповещения только с IP адреса, полученного от службы поддержки ecommpay.
  2. На успешно принятые оповещения ответ вашей системы должен быть HTTP 200 OK.
  3. На оповещения, которые уже ранее были приняты вашей системой, ответ должен быть также HTTP 200 OK.
  4. На оповещения, принятые с ошибкой, ответ вашей системы должен быть HTTP 400 Bad Request (например, если вам не удалось преобразовать строку параметров в массив) или HTTP 500 Internal Server Error (например, если оповещение пришло на неправильный URL-адрес).
  5. Повторные оповещения, которые ранее не были приняты или были приняты с ошибкой, ваша система должна попытаться принять еще раз.
  6. Ваша система не должна ограничивать время на доставку оповещений, доставка оповещений может происходить с задержкой.

Параметры, передаваемые в оповещениях

Набор параметров, передаваемых в оповещении, может отличаться в зависимости от типа операции и конфигурации оповещений. В этом разделе приведены описания параметров, используемых в типовых случаях. Словом default отмечены объекты и параметры, используемые по умолчанию для всех типовых оповещений.

Внимание: Формирование подписи должно осуществляться с учётом всех принятых в конкретном оповещении параметров.
Табл. 1. Объекты и параметры оповещений
Параметр Описание tree

account
object, optional
default

 Объект, содержащий данные банковской карты или учетной записи пользователя 10

card_holder
string, optional

 Имя владельца банковской карты 10-10 10

expiry_month
string, optional

 Месяц срока действия банковской карты 10-20 10

expiry_year
string, optional

 Год срока действия банковской карты 10-30 10

id
integer, optional

 Идентификатор сохраненной карты в Gate 10-40 10

number
string, required
default

Маскированный номер банковской карты или учетной записи пользователя.

Пример: 424242***4242

 10-50 10

token
string, optional
default

 Токен банковской карты пользователя. Токен генерируется автоматически при успешной оплате при условии, что эта возможность была активирована при подключении 10-60 10

type
string, optional

 Тип банковской карты или наименование оператора мобильной связи, который использовался для оплаты. Доступные значения типов карт см. в разделе Общая информация . Доступные значения для мобильных операторов:
  • mBEELINE
  • mMEGAFON
  • mMTS
  • mTELE2
 10-70 10

acs
object, optional

 Объект, содержащий результаты аутентификации пользователя средствами 3‑D Secure, если оплата проводилась с помощью банковской карты, поддерживающей в 3‑D Secure 20

acs_url
string, required

 URL-адрес веб-страницы ACS-сервера банка-эмитента 20-10 20

md
string, required

 Набор технических данных мерчанта в платежной системе 20-20 20

pa_req
string, required

 Запрос аутентификации, который следует отправить в банк-эмитент. Содержит закодированную информацию о владельце карты, мерчанте и платеже 20-30 20

avs_data
object, optional

 Объект, который содержит данные для AVS-проверки (Address Verification Service). Подробнее см. Проверка Address Verification Service 30

avs_post_code
string, optional

 Почтовый индекс пользователя 30-10 30

avs_street_address
string, optional

 Адрес пользователя 30-20 30

avs_result
string, optional

 Результат AVS-проверки (Address Verification Service). Подробнее см. в разделе Проверка Address Verification Service 40

bank
object, optional

 Объект, содержащий данные о банке-эмитенте карты пользователя 50

name
string, optional

 Наименование банка-эмитента карты пользователя 50-10 50

customer
object, optional

default

 Объект, содержащий информацию о пользователе, совершающем платеж 70

billing
object, optional

 Объект, содержащий информацию о платёжном адресе пользователя 70-10 70

address
string, optional

 Платёжный адрес пользователя 70-10-10 70-10

city
string, optional

 Город платёжного адреса пользователя 70-10-20 70-10

country
string, optional

Страна платёжного адреса пользователя в формате ISO 3166-1 alpha-2.

Пример: RU

 70-10-30 70-10

postal
string, optional

 Индекс платёжного адреса пользователя 70-10-40 70-10

region
string, optional

 Район, область, край или республика платёжного адреса пользователя 70-10-50 70-10

city
string, optional

Город пользователя.

Пример: Дубна

70-20 70

country
string, optional

Страна пользователя в формате ISO 3166-1 alpha-2, переданная в начальном запросе.

Пример: RU

70-30 70

day_of_birth
string, optional

Дата рождения пользователя в формате ДД-ММ-ГГГГ.

Пример: 24-12-1978

 70-40 70

first_name
string, optional

Имя пользователя.

Пример: Инна

70-50 70

id

string, optional

default

 Уникальный идентификатор пользователя в проекте 70-60 70

ip_address
string, required

 IP-адрес пользователя, переданный в начальном запросе 70-70 70

last_name
string, optional

Фамилия пользователя.

Пример: Малая

70-80 70

middle_name
string, optional

Отчество пользователя.

Пример: Ивановна

 70-90 70

phone
string, optional
default

 Телефон пользователя. Цифровое значение: от 4 до 24 цифр 70-100 70

decision
string, optional

 Строка, содержащая решение системы Risk Control System о прохождении платежа. 80

decision_message
array, optional

Массив строк, содержащих сообщения от Risk Control System о прохождении платежа.

Пример: reject.message("RCS reject. Amount less than allowed")

 90

display_data
object, optional

 Объект, содержащий переданные от внешней платежной системы данные для отображения QR-кода для оплаты пользователям 100

errors
array, optional
default

 Массив сообщений об ошибках, связанных с проведением платежа 110

ErrorItem
object, required

 Объект, содержащий информацию об одной ошибке 110-10 110

code
integer, optional

 Код ошибки 110-10-10 110-10

description
string, optional

 Параметр, описывающий причину ошибки 110-10-10 110-10

field
string, optional

 Параметр, в котором допущена ошибка, если удалось определить неверный параметр 110-10-20 110-10

message
string, optional

 Сообщение, уточняющее причину ошибки 110-10-30 110-10

interface_type
object, optional

 Объект, содержащий информацию об источнике запроса на проведение платежа 120

id
integer, optional

 Параметр, уточняющий, какой интерфейс использовался для отправки запроса на проведение платежа. Возможные значения:
  • 1 — запрос поступил от API Gate;
  • 2–4 — запрос поступил от ecommpay;
  • 5 — запрос поступил от Dashboard;
  • 6 — запрос поступил от Payment Page в модальном окне;
  • 7 — запрос поступил от Payment Page в iframe
 120-10 120

user
string, optional

Параметр, уточняющий пользователя Dashboard. отправившего запрос на проведение платежа.

Пример: i.ivanov@mail.com

120-20 120

operation
object, optional

 Объект, содержащий информацию об операции, по которой отправлено оповещение 130

code
string, optional

 Унифицированный код ответа Gate. Подробнее см. в Информация об операциях 130-10 130

created_date
string, optional

 Дата и время создания операции 130-20 130

date
string, optional

 Дата и время последнего обновления статуса операции в Gate 130-30 130

eci
string, optional

 Индикатор, отображающий результат аутентификации пользователя с использованием 3‑D Secure. Подробнее см. Индикаторы ECI 130-40 130

id
integer, optional

 Уникальный идентификатор операции в Gate 130-50 130

message
string, optional

 Унифицированное сообщение Gate. Подробнее см. в Информация об операциях 130-60 130

provider
object, optional

 Объект, который содержит информацию внешнего провайдера о результате выполнения платежа 130-70 130

auth_code
string, optional

 Код авторизации, полученный от внешнего провайдера 130-70-10 130-70

date
string, optional

Дата и время завершения обработки платежа внешним провайдером.

Пример: 2017-07-21T03:31:24+0000

130-70-20 130-70

endpoint_id
string*, optional

CRC32-идентификатор платежного шлюза внешнего провайдера.

* В некоторых случаях, с учётом особенностей платёжных систем и провайдеров, у этого параметра может быть тип integer

 130-70-30 130-70

id
integer, optional

 Внешний провайдер, через который была проведена операция 130-70-40 130-70

payment_id
string, optional

 Уникальный идентификатор платежа в системе внешнего провайдера 130-70-50 130-70

request_id
string, required

 Уникальный идентификатор последнего запроса, относящегося к данной операции, в Gate 130-80 130

status
string, required

 Статус проведенной операции 130-90 130

sum_converted
object, optional

 Объект, содержащий валюту платежной системы и сумму операции, переведенной в эту валюту 130-100 130

amount
integer, optional

 Сумма операции в дробных единицах валюты платежной системы 130-100-10 130-100

currency
string, optional

 Валюта платежной системы в формате ISO 4217 alpha-3 130-100-20 130-100

sum_initial
object, optional

 Объект, содержащий сумму и валюту операции, переданные в запросе 130-110 130

amount
integer, required

 Сумма операции, переданная в начальном запросе, в дробных единицах валюты 130-110-10 130-110

currency

string, required

 Валюта операции в формате ISO 4217 alpha-3, переданная в начальном запросе 130-110-20 130-110

type

string, required

 Тип проведенной операции 130-120 130

payment
object, required
default

 Объект, содержащий данные о платеже 140

cascading_with_redirect
boolean, optional

 Необходимость перенаправления пользователя на другой ACS URL для повторной попытки проведения аутентификации 3D-Secure , в случае получения отказа от внешнего провайдера, а также отображение страницы с ошибкой и кнопкой Попробовать еще раз. Доступные значения:
  • true — нужна повторная попытка;
  • false — повторная попытка не нужна
 140-10 140

date
string, optional
default

Дата и время последнего обновления статуса платежа в Gate.

Пример: 2017-07-27T15:19:13+0000

140-20 140

description
string, optional
default

 Описание платежа, переданное в начальном запросе 140-30 140

id
string, required
default

 Уникальный идентификатор платежа в веб-сервисе 140-40 140

is_new_attempts_available
boolean, optional

 Признак возможности проведения повторной оплаты:
  • true — повторная оплата возможна;
  • false — повторная оплата невозможна.
Этот параметр передается при включении повторных оплат при подключении через Payment Page 		140-50 140

method
string, optional
default

Платежный метод.

Пример: card

140-60 140

merchant_refund_id
string, optional

Уникальный идентификатор возврата в системе мерчанта.

Пример: refund_1

140-61 140

OperationFee
object, optional

 Объект, содержащий информацию о комиссии за операцию, начисленной ecommpay 140-70 140

amount
string, optional

 Сумма комиссии за операцию в дробных единицах валюты, если она включена в общую сумму платежа 140-70-10 140-70

currency
string, optional

Валюта, в которой начислена комиссия, в формате ISO 4217 alpha-3.

Пример: EUR

 140-70-20 140-70

sum_with_surcharge
string, optional

 Общая сумма операции и надбавленной комиссии в дробных единицах валюты 140-70-30 140-70

surcharge_amount
string, optional

 Сумма надбавленной к сумме платежа комиссии в дробных единицах валюты. Применяется для МФО 140-70-40 140-70

surcharge_currency
string, optional

 Валюта, в которой начислена надбавленная к сумме платежа комиссия, в формате ISO 4217 alpha-3 140-70-50 140-70

region
string, optional

 Регион страны, где проводится операция по банковской карте. Доступные значения см. в справочнике Коды регионов 140-80 140

status
string, required
default

Cтатус платежа.

Пример: success

140-90 140

sum

object, optional
default

 Объект, содержащий сумму платежа с учетом возвратов и валюту, переданную в начальном запросе 140-100 140

amount
integer, required

 Сумма платежа с учетом возвратов, в дробных единицах валюты 140-100-10 140-100

currency
string, required

Валюта платежа в формате ISO 4217 alpha-3, переданная в начальном запросе.

Пример: USD

 140-100-20 140-100

timeout_attempts
string, optional

 Время (в секундах), оставшееся до окончания периода, в течение которого возможно проведение повторной оплаты. Параметр передается при включении повторных оплат при подключении через Payment Page 140-110 140

type  
string, required
default

Тип проведенного платежа.

Пример: purchase

 140-120 140

project_id
integer, required

 Уникальный идентификатор проекта в Gate 150

provider_extra_fields
object, optional
default

 Объект, содержащий поступившие от внешней платежной системы данные, необходимые для завершения платежа или для отчетности 160

recurring
object, optional
default

 Объект, содержащий данные регистрации платежа как рекуррентного. Объект не передается, если в начальном запросе на оплату было передано значение recurring_register=1 и оплата успешно проведена 170

currency
string, optional
default

Валюта рекуррентного платежа в формате ISO 4217 alpha-3.

Пример: USD

 170-10 170

id
integer, optional
default

 Идентификатор рекуррентного платежа 170-20 170

register_payment_id
string, optional

Идентификатор рекуррентного платежа на стороне мерчанта 170-30 170

status
string, optional

 Статус повторяемой оплаты. Возможные значения:
  • active— повторяемая оплата включена
  • canceled— повторяемая оплата отменена
 170-40 170

type
string, optional

 Тип рекуррентного платежа. Возможные значения:
  • R — регулярная оплата
  • U — автооплата
  • C — экспресс-оплата (OneClick)
170-50 170

valid_thru
string, optional
default

 Дата истечения срока действия идентификатора рекуррентного платежа 170-60 170

redirect_data
object, optional

 Объект, содержащий данные для перенаправления пользователя к платежному методу для проведения платежа 180

body
object, optional

 Набор параметров, содержащих данные для перенаправления 180-10 180

method
string, optional

 Метод отправки запроса: POST или GET 180-20 180

url
string, optional

 URL-адрес для перенаправления пользователя 180-30 180

signature
string, required
default

 Подпись оповещения. Подробнее о проверке подписей оповещений см. Работа с подписью к данным 190