Callback-уведомления
Типы callback АТОЛ Pay - оплата, отмена/возврат, вторая стадия, фискализация и подписки, с примерами полезной нагрузки.
Callback - HTTP POST-запрос от АТОЛ Pay на ваш URL при смене статуса.
Передается в результате вызова и обработки методов /payments, /cancel,
/deposit и по событиям подписок.
Куда приходят уведомления
URL для callback задается одним из способов:
- В настройках ЛК - Настройки > Настройки заказов.
- При регистрации платежа -
additionalProps.notificationUrl(имеет приоритет над настройками ЛК).
Преимущества передачи notificationUrl при регистрации платежа:
- Единая ссылка на получение всех событий - тип события определяется по полю
typeв теле входящего запроса. - В ссылку можно добавлять query-параметры с любой информацией по заказу -
callback будет вызван с этими параметрами
(
https://example.com?userId=111&orderId=222&info=someInfo).
Виды callback для обычных платежей
- Информирование о статусе оплаты (
type: "payment") - после успешной/неуспешной оплаты, независимо от чеков. Статусы:success/fail. - Информирование о статусе отмены/возврата (
type: "cancel"/"refund"). - Информирование о статусе фискализации (
type: "fiscal") - если платеж зарегистрирован с чеком (полеreceipt) и оплата совершена успешно. - Вторая стадия (
type: "deposit") - для двухстадийных платежей.
При двухстадийном платеже отправляются две нотификации:
- на первую стадию - callback оплаты (при успехе
paymentStatus: 11,awaitingDeposit); - на вторую стадию - callback второй стадии (при успехе
paymentStatus: 1,success).
Чтобы определить успешное проведение платежа, достаточно callback оплаты (в том числе для двухстадийного платежа) - нотификация второй стадии может прийти спустя несколько дней.
Транзакция не отменяется при ошибке фискализации: если оплата успешна, а чек не отправился, платеж все равно проведен.
Параметры callback (payment, deposit, cancel, refund)
| Параметр | Описание | Обяз. | Формат |
|---|---|---|---|
status | Статус обработки запроса: success / fail | Да | string |
orderId | Идентификатор заказа | Да | string |
amount | Сумма операции в копейках | Да | number |
type | Тип нотификации: payment, deposit, cancel, refund | Да | string |
paymentStatus | Числовой статус платежа - см. Статусы платежа | Да | number |
sessionType | oneStep / twoStep | Да | string |
paidAt | Время оплаты | Нет | string, ISO 8601 |
canceledAt | Время отмены/возврата | Нет | string, ISO 8601 |
depositedAt | Время проведения второй стадии | Нет | string, ISO 8601 |
subscriptionId | ID подписки (для платежей по подписке) | Нет | string |
subscriptionPlanId | ID плана подписки | Нет | string |
permanentLinkId | ID постоянной ссылки | Нет | string |
bindingId | Идентификатор привязки карты (если карта была сохранена) | Нет | string, uuid |
mit | Признак платежа, инициированного продавцом (Merchant Initiated Transaction) - рекуррентное списание без участия покупателя | Нет | boolean |
errorMessage / errorCode | Данные ошибки (при status: "fail") | Нет | string |
{
"status": "success",
"orderId": "fcae8e64-972c-4012-b763-b139d88eae05",
"amount": 10000,
"type": "payment",
"paymentStatus": 1,
"sessionType": "oneStep",
"paidAt": "2025-06-04T13:21:00+03:00",
"canceledAt": null,
"depositedAt": null
}Для двухстадийного платежа callback первой стадии приходит с
paymentStatus: 11 (awaitingDeposit), а callback второй стадии -
с type: "deposit", paymentStatus: 1 и заполненным depositedAt.
Поля subscriptionId, subscriptionPlanId и permanentLinkId присутствуют
только у платежей по подписке и по постоянной ссылке.
{
"status": "fail",
"orderId": "fcae8e64-972c-4012-b763-b139d88eae05",
"amount": 10000,
"type": "payment",
"paymentStatus": 3,
"sessionType": "oneStep",
"errorMessage": "Ошибка 3-D Secure авторизации.",
"errorCode": "PROCESSING_ERROR"
}Различайте paymentStatus: 3 (error - повтор невозможен, регистрируйте
заказ заново) и 12 (retryError - покупатель может повторить попытку
оплаты по той же ссылке).
Callback фискализации (type: fiscal)
| Параметр | Описание | Обяз. | Формат |
|---|---|---|---|
status | success / fail | Да | string |
orderId | Идентификатор заказа | Да | string |
type | fiscal | Да | string |
receiptId | Идентификатор чека | Да | string, uuid |
amount | Сумма | Да | number |
receiptType | Тип чека: sell - «Приход», sell_refund - «Возврат прихода» (отправляется при отмене/возврате платежа с чеком) | Да | string |
sessionType | oneStep / twoStep | Да | string |
paidAt / canceledAt / depositedAt | Время оплаты / отмены или возврата / второй стадии | Нет | string, ISO 8601 |
subscriptionId / subscriptionPlanId / permanentLinkId | ID подписки, плана и постоянной ссылки - для соответствующих платежей | Нет | string |
bindingId | Идентификатор привязки карты (если карта сохранена) | Нет | string, uuid |
errorMessage / errorCode | Данные ошибки (при status: "fail") | Нет | string |
{
"status": "success",
"orderId": "fcae8e64-972c-4012-b763-b139d88eae05",
"amount": 10000,
"type": "fiscal",
"receiptId": "855bcdf3-bb31-44b6-8230-744d1a440df4",
"receiptType": "sell",
"sessionType": "oneStep",
"paidAt": "2025-06-04T13:21:00+03:00"
}Callback подписок (type: subscription)
| Параметр | Описание | Обяз. | Формат |
|---|---|---|---|
type | subscription | Да | string |
status | success / fail | Да | string |
subscriptionStatus | new, trial, prolongation, retry, error, canceled, paused - см. жизненный цикл | Да | string |
nextPaymentAt | Дата следующей оплаты (ISO 8601) | Нет | string |
subscriptionId | Уникальный ID подписки | Да | string |
retryNum | Номер попытки оплаты (при subscriptionStatus: "retry") | Нет | number |
errorCode / errorMessage | Данные ошибки (при status: "fail") | Нет | string |
{
"type": "subscription",
"status": "success",
"subscriptionStatus": "new",
"subscriptionId": "sub_abc123def456",
"nextPaymentAt": "2025-07-10T10:00:00Z"
}{
"type": "subscription",
"status": "fail",
"subscriptionStatus": "retry",
"subscriptionId": "sub_abc123def456",
"retryNum": 3,
"errorCode": "PAYMENT_DECLINED",
"errorMessage": "Недостаточно средств на карте"
}Коды ошибок в callback
errorCode в callback - это символьный код из общего
справочника ошибок АТОЛ Pay (например PROCESSING_ERROR,
PAYMENT_DECLINED), а errorMessage содержит текст, полученный от
банка-эквайера.
Отдельного списка кодов отказа банка нет
В документе «Интеграция c API АТОЛ Pay Ecom» консолидированного перечня кодов
отказа банка-эквайера нет - таблица «Коды ошибок» в нем совпадает со
справочником ошибок портала. Причина отказа передается
текстом в errorMessage и зависит от конкретного эквайера, поэтому не стройте
бизнес-логику на разборе этой строки: различайте случаи по paymentStatus
(3 - повтор невозможен, 12 - попытку можно повторить).
Рекомендации по обработке
- Отвечайте на callback HTTP-статусом
200сразу после сохранения события; тяжелую обработку выполняйте асинхронно. - Делайте обработчик идемпотентным - одно и то же событие может прийти повторно.
- Не полагайтесь только на callback: если уведомление не пришло, опрашивайте
GET /payments/{orderId}/status. - Ключ сопоставления -
orderId(плюс query-параметры, которые вы добавили вnotificationUrl).