Finance OS / API

Status Updates — как узнавать об изменениях

Операции канала асинхронны: ответ на создание сообщает, что операция принята, а не что она завершена. Конечное состояние определяет статус операции.

⚠
Успешный ответ ≠ успешная операция
Платёж может остаться неоплаченным или уйти в rejected, возврат — в error. Ориентируйтесь на статус, а не на код ответа при создании.

Два способа

Механизмы

Webhooks Finance OS push optional
Основной способ: платформа уведомляет вас об изменениях по вашим операциям. Настройка, формат и проверка подписи — в разделе Webhooks.
Запрос статуса pull optional
Вспомогательный: разрешить неопределённость после таймаута или пропущенного уведомления, сверить состояние перед действием.

Формат уведомлений и проверка подписи описаны в общем разделе Webhooks и в Merchant API → Webhooks. Отдельного формата у RUB-канала нет — события приходят тем же механизмом, что и остальные события платформы.

О чём приходят уведомления

События канала

Оплата получена payment optional
Плательщик оплатил. Цикл операции ещё продолжается.
Платёж завершён payment optional
Успешный финал. Отгружайте по этому событию.
Платёж отклонён payment optional
Отказ эквайера. Финальное состояние.
Платёж отменён payment optional
Неоплаченный платёж отменён или истёк.
Ошибка платежа payment optional
Сбой в процессе. В данных есть код отказа.
Возврат завершён refund optional
Деньги вернулись плательщику.
Чек сформирован receipt optional
Готов фискальный документ по платежу или возврату.

Требования к обработчику

  • отвечайте быстро: долгую работу выносите в очередь, а не выполняйте в обработчике;
  • отвечайте успехом только после того, как событие сохранено — иначе оно будет считаться доставленным и потеряется;
  • не полагайтесь на порядок: события могут прийти не в том порядке, в котором происходили;
  • считайте неизвестный тип события безопасным для игнорирования, но фиксируйте его в своём журнале.

Идемпотентность на вашей стороне

Одно и то же изменение может дойти до вас дважды — уведомлением и запросом статуса, либо повторной доставкой уведомления. Обрабатывайте события идемпотентно: ключом служит ваш order_id вместе со статусом операции. Повторная обработка не должна приводить к повторному зачислению или повторной отправке денег.

⊘
Дубликаты приходят обязательно
Повторная доставка — штатное поведение, а не сбой. Обработчик без защиты от дублей рано или поздно проведёт одну операцию дважды.

Если опрашиваете статус

  • не опрашивайте в плотном цикле — используйте растущий интервал;
  • прекращайте опрос по достижении конечного статуса: у платежа это completed, cancelled, rejected, error; у возврата — completed и error;
  • ищите операцию по своему order_id, а не по времени создания;
  • помните, что paid — не конечный статус, см. Payments.