Как получить уведомление об оплате через returnLinks

При интеграции платёжных систем разработчики часто сталкиваются с ситуацией, когда уведомление об оплате не приходит на указанный обработчик. В этой статье мы разберём, как правильно настроить returnLinks с rel='on_completed', методом POST и устранить типичные неполадки.

Что такое returnLinks on_completed?

Параметр returnLinks в платёжном запросе определяет URL, на который система отправляет уведомление о статусе транзакции. Значение on_completed указывает, что callback должен сработать после успешной оплаты. Если на ваш вебхук ничего не приходит, проблема чаще всего кроется в настройках сервера или формате запроса.

Почему не приходит уведомление об оплате?

Рассмотрим основные причины, по которым платёжный коллбек может не доставляться:

• Некорректный URL - ссылка должна быть доступна из интернета, без локальных адресов (127.0.0.1, localhost).
• Метод запроса - укажите 'method': 'POST', так как большинство систем игнорируют GET для уведомлений.
• Блокировка брандмауэром - проверьте, что ваш сервер принимает входящие POST-запросы от IP платёжного шлюза.
• Ошибки в коде обработчика - если скрипт возвращает HTTP-статус, отличный от 200 OK, система может считать доставку неудачной.

Как проверить returnLinks?

Сначала убедитесь, что структура массива соответствует документации платёжного провайдера. Пример правильной настройки:

returnLinks: [
  {
    'rel': 'on_completed',
    'href': 'https://ваш-сайт.ру/handler',
    'method': 'POST'
  }
]

После этого протестируйте вебхук с помощью сервисов вроде RequestBin или Webhook.site - они покажут, приходит ли запрос вообще. Если да, то проблема в вашем обработчике. Если нет - проверьте правильность URL и метод.

Настройка обработчика уведомлений

Чтобы гарантированно получать уведомление об оплате, ваш скрипт должен:

• Принимать POST-запросы с типом содержимого application/json или application/x-www-form-urlencoded (зависит от платёжной системы).
• Логировать входящие данные для отладки.
• Возвращать HTTP 200 с пустым телом в течение 5 секунд, иначе шлюз может повторить отправку.

Пример обработчика на PHP

<?php
$data = file_get_contents('php://input');
file_put_contents('log.txt', $data, FILE_APPEND);
http_response_code(200);
?>

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

Частые ошибки интеграции

Вот что ещё стоит проверить:

• HTTPS - многие платёжные системы требуют защищённое соединение для коллбеков.
• Тайм-ауты - если ваш сервер отвечает дольше 10 секунд, запрос может быть сброшен.
• Дубликаты - иногда уведомление приходит дважды; предусмотрите идемпотентность.

Правильная настройка returnLinks on_completed гарантирует, что вы получите уведомление об оплате и сможете своевременно обработать заказ.