Работа с платежами¶

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

Процесс обработки платежа¶

Клиент оплачивает один или несколько счетов через платёжный шлюз.
Шлюз получает от платёжной системы финальный статус платежа.
Если получен статус COMPLETE, шлюз формирует уведомления для поставщиков услуг.
Для каждой части платежа шлюз отправляет отдельный вебхук поставщику, у которого настроен вебхук-URL.
Поставщик проверяет запрос и сохраняет информацию об оплате.

Если платёж включает несколько частей, во всех уведомлениях передаётся общий идентификатор платежа uuid. Поля account и amount относятся к конкретной части платежа и могут различаться.

Информация о вебхуке¶

Вы самостоятельно указываете администратору R1.pay базовый URL вебхук-эндпоинта. Если URL не настроен, уведомления об успешной оплате отправляться не будут.

Параметр	Значение
Вебхук-URL	`https://ВАШ_BASE_WEBHOOK_URL/payment`
Метод	`POST`
Таймаут	15 секунд

Шлюз автоматически добавляет /payment к базовому вебхук-URL поставщика услуг.

Заголовки запроса¶

Имя заголовка	Значение
`Content-Type`	`application/json`
`R1-Token`	<ваш_секретный_токен>

Аутентификация¶

Если для поставщика услуг настроен токен, шлюз передаёт его в заголовке R1-Token. Проверяйте значение заголовка, чтобы убедиться, что запрос отправлен доверенным шлюзом.

Важно: Храните токен в защищённом виде и не записывайте его в открытые журналы. При подозрении на утечку запросите замену токена.

Вебхук успешной оплаты¶

POST /payment

Уведомление отправляется только после получения от платёжной системы статуса COMPLETE.

Запрос¶

Структура запроса¶

Поле	Тип	Описание
`account`	string	Номер лицевого счёта, к которому относится часть платежа
`uuid`	UUID (string)	Уникальный идентификатор платежа в R1.pay
`payment_date`	string	Дата и время платежа в формате `YYYY-MM-DD HH:mm:ss`, приведённые к локальному часовому поясу шлюза
`final_date`	string	Дата и время завершения платежа в формате `YYYY-MM-DD HH:mm:ss`, приведённые к локальному часовому поясу шлюза. Если платёжная система не передала дату завершения, шлюз указывает дату и время формирования вебхука
`amount`	integer (int64)	Сумма соответствующей части платежа в копейках

Пример запроса¶

{
  "account": "3494988",
  "uuid": "550e8400-e29b-41d4-a716-446655440000",
  "payment_date": "2026-08-11 12:00:00",
  "final_date": "2026-08-11 12:00:05",
  "amount": 150000
}

ℹ️ Примечание: Строки payment_date и final_date не содержат обозначения часового пояса. Значения уже приведены к локальному часовому поясу шлюза.

Обработка вебхука¶

На стороне поставщика услуг:

Проверьте заголовок R1-Token, если токен настроен.
Проверьте формат и обязательные поля JSON-запроса.
Сделайте обработку идемпотентной: повторное уведомление не должно приводить к повторному зачислению платежа.
Используйте сочетание uuid и account для определения части платежа. Один uuid может относиться к нескольким лицевым счетам.
Сохраните информацию об оплате и верните успешный HTTP-ответ без длительной синхронной обработки.

Ответ¶

Рекомендуется вернуть 200 OK сразу после успешного приёма уведомления. Тело ответа шлюзом не используется и может быть пустым.

Пример пустого ответа:

{}

Повторная отправка¶

В текущей реализации автоматические повторные попытки для вебхука успешной оплаты не выполняются. Если endpoint недоступен или не отвечает в течение 30 секунд, ошибка фиксируется в журнале шлюза.

⚠️ Важно: Обеспечьте доступность endpoint и выполняйте длительную обработку асинхронно после приёма уведомления.