Уведомления

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

Обратите внимание

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

На всякий случай

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

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

В случае неуспешной доставки асинхронных уведомлений (или неверного значения в поле code) будет предпринято 10 попыток доставки. С каждой новой попыткой интервал будет увеличен на 10 секунд (начиная с 60).

Валидация уведомлений

Каждый запрос уведомления сопровождается двумя заголовками:

X-Notify-ID
X-Notify-Signature

Эти заголовки позволяют проверить источник входящего запроса.

При этом X-Notify-ID содержит идентификатор самого уведомления - каждый повторный запрос одного и того же уведомления будет иметь одинаковое значение в этом заголовке, что позволяет фиксировать уведомления и не обрабатывать повторные запросы.

Заголовок X-Notify-Signature формируется следующим образом:

sha256(notify_id + site_secret)

Где notify_id - значение из заголовка X-Notify-ID, site_secret - ключ сайта для API полученный в личном кабинете.

Так же дополнительно рекомендуем проверять IP-адрес входящего запроса.

Адреса уведомляющих серверов

109.239.131.224/28

FORM

Выполняется после того, как плательщик заполнил специальную платежную форму и нажал кнопку "Продолжить".

Это уведомление будет отправлено только в том случае, если к виджету была прикреплена специальная платежная форма.

Служит для валидации данных введенных пользователем в форму. В ответ на это уведомление вы можете вернуть некоторые параметры виджета (идентификатор заказа, сумма платежа, описание платежа), которые будут применены для оплаты.

В качестве тела запроса будет отправлен объект с информацией специальной платежной формы. В ответ система ожидает получить JSON в следующем формате:

{
    "code": 0,
    "message": "Widget error info",
    "result": {
        "account": true,
        "amount":  false,
    },
    "details": {
        "amount": "Неверная сумма платежа"
    },
    "options": {
        "amount":      100,
        "orderId":     1000,
        "description": "Оплата телефонии"
    }
}

Любое значение code отличное от 0 будет воспринято как невозможность обработки самой формы, не полей. Поле message является необязательным, но в случае не пустого значения это сообщение будет отображено пользователю. Поле code может принимать любое значение. По умолчанию для следующих значений поля есть сообщения:

Код	Сообщение
30	Неверная форма

Остальные поля ответа описаны в таблице

Поле	Тип	Обязательный	Описание
result	object	Да	Результат обработки формы на стороне продавца. В качестве ключей должен содержать имя поля, а в качестве значения - bool, где true - значение верное, false - значение неверное. Отсутствие поля в этом объекте будет означать, что оно заполнено неверно.
details	object	Нет	Сообщение для полей, которые надо отобразить пользователю, если значение в поле неверное. Если поле заполнено неверно, а в этом объекте нет сообщения для него - сообщение будет "Неверное значение".
options	object	Нет	Новые параметры, которые надо передать или заменить в виджете (доступные параметры - orderId, accountId, email, amount, description)

Обратите внимание

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

Обратите внимание

Это уведомление не отменяет и не заменяет уведомление CHECK.

CHECK

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

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

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

{ "code": 0, "message": "Invalid something" }

Любое значение code отличное от 0 будет воспринято системой как невозможность проведения платежа. Поле message является необязательным, но в случае не пустого значения это сообщение будет отображено пользователю. Поле code может принимать любое значение, которое будет отображено в списке транзакций в личном кабинете продавца. По умолчанию для следующих значений поля есть сообщения:

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

Обратите внимание

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

PAY

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

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

В качестве тела запроса будет отправлен объект с информацией о платежной операции.

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

{ "code": 0 }

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

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

FAIL

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

В качестве тела запроса будет отправлен объект с информацией о платежной операции.

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

{ "code": 0 }

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

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

Обратите внимание

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

CONFIRM

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

В качестве тела запроса будет отправлен объект с информацией о платежной операции.

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

{ "code": 0 }

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

REFUND

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

В качестве тела запроса будет отправлен объект с информацией о платежной операции.

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

{ "code": 0 }

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

CANCEL

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

В качестве тела запроса будет отправлен объект с информацией о платежной операции.

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

{ "code": 0 }

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