Перейти к содержимому

Callback-уведомления

Типы callback АТОЛ Pay - оплата, отмена/возврат, вторая стадия, фискализация и подписки, с примерами полезной нагрузки.

Callback - HTTP POST-запрос от АТОЛ Pay на ваш URL при смене статуса. Передается в результате вызова и обработки методов /payments, /cancel, /deposit и по событиям подписок.

Куда приходят уведомления

URL для callback задается одним из способов:

  1. В настройках ЛК - Настройки > Настройки заказов.
  2. При регистрации платежа - additionalProps.notificationUrl (имеет приоритет над настройками ЛК).

Преимущества передачи notificationUrl при регистрации платежа:

  1. Единая ссылка на получение всех событий - тип события определяется по полю type в теле входящего запроса.
  2. В ссылку можно добавлять query-параметры с любой информацией по заказу - callback будет вызван с этими параметрами (https://example.com?userId=111&orderId=222&info=someInfo).

Виды callback для обычных платежей

  1. Информирование о статусе оплаты (type: "payment") - после успешной/неуспешной оплаты, независимо от чеков. Статусы: success / fail.
  2. Информирование о статусе отмены/возврата (type: "cancel" / "refund").
  3. Информирование о статусе фискализации (type: "fiscal") - если платеж зарегистрирован с чеком (поле receipt) и оплата совершена успешно.
  4. Вторая стадия (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
sessionTypeoneStep / twoStepДаstring
paidAtВремя оплатыНетstring, ISO 8601
canceledAtВремя отмены/возвратаНетstring, ISO 8601
depositedAtВремя проведения второй стадииНетstring, ISO 8601
subscriptionIdID подписки (для платежей по подписке)Нетstring
subscriptionPlanIdID плана подпискиНетstring
permanentLinkIdID постоянной ссылкиНетstring
bindingIdИдентификатор привязки карты (если карта была сохранена)Нетstring, uuid
mitПризнак платежа, инициированного продавцом (Merchant Initiated Transaction) - рекуррентное списание без участия покупателяНетboolean
errorMessage / errorCodeДанные ошибки (при status: "fail")Нетstring
json
{
  "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 присутствуют только у платежей по подписке и по постоянной ссылке.

json
{
  "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)

ПараметрОписаниеОбяз.Формат
statussuccess / failДаstring
orderIdИдентификатор заказаДаstring
typefiscalДаstring
receiptIdИдентификатор чекаДаstring, uuid
amountСуммаДаnumber
receiptTypeТип чека: sell - «Приход», sell_refund - «Возврат прихода» (отправляется при отмене/возврате платежа с чеком)Даstring
sessionTypeoneStep / twoStepДаstring
paidAt / canceledAt / depositedAtВремя оплаты / отмены или возврата / второй стадииНетstring, ISO 8601
subscriptionId / subscriptionPlanId / permanentLinkIdID подписки, плана и постоянной ссылки - для соответствующих платежейНетstring
bindingIdИдентификатор привязки карты (если карта сохранена)Нетstring, uuid
errorMessage / errorCodeДанные ошибки (при status: "fail")Нетstring
json
{
  "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)

ПараметрОписаниеОбяз.Формат
typesubscriptionДаstring
statussuccess / failДаstring
subscriptionStatusnew, trial, prolongation, retry, error, canceled, paused - см. жизненный циклДаstring
nextPaymentAtДата следующей оплаты (ISO 8601)Нетstring
subscriptionIdУникальный ID подпискиДаstring
retryNumНомер попытки оплаты (при subscriptionStatus: "retry")Нетnumber
errorCode / errorMessageДанные ошибки (при status: "fail")Нетstring
json
{
  "type": "subscription",
  "status": "success",
  "subscriptionStatus": "new",
  "subscriptionId": "sub_abc123def456",
  "nextPaymentAt": "2025-07-10T10:00:00Z"
}
json
{
  "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).