RioPay
RioPay (api.riopay.online) — касса с оплатой картой и СБП. Бот создаёт заказ через POST /v1/orders с токеном в заголовке X-Api-Token, юзер уходит на paymentLink и после оплаты возвращается по successUrl. Валюта — RUB, сумма передаётся строкой в рублях.
В заказ кладётся свой payment_id (externalId) — по нему вебхук привязывается к платежу; дополнительно сохраняется id заказа от RioPay, по которому шлюз умеет опрашивать статус.
Что понадобится
Мерчант-аккаунт в RioPay и API-токен из кабинета. Секрет вебхуков — опционально: если провайдер выдал отдельный, впишите его, иначе подпись проверяется тем же API-токеном.
Настройка в кабинете
| Поле | Что это | Обязательное |
|---|---|---|
api_token | API-токен из кабинета RioPay — заголовок X-Api-Token | да |
webhook_secret | отдельный секрет подписи вебхуков; если пусто — используется api_token | нет |
Ключи хранятся в БД в зашифрованном виде. Включите тумблер активности провайдера. Кнопка Тест у этого шлюза проверочного запроса к API не делает — правильность ключей подтвердит первый платёж. Дополнительно настраиваются отображаемое имя, комиссия для статистики и формы оплаты, которые видит юзер (карта / СБП).
Вебхук
https://ваш-домен/api/v1/payments/riopayУкажите этот URL как адрес уведомлений в кабинете RioPay. Подпись приходит в заголовке X-Signature: HMAC-SHA512 hex по сырому телу запроса с ключом webhook_secret (или api_token, если отдельный секрет не задан). Битая или отсутствующая подпись → HTTP 403.
Маппинг статуса из поля status:
| Статус RioPay | Что делает бот |
|---|---|
COMPLETED | зачисляет платёж |
CANCELED, CANCELLED, FAILED, EXPIRED | закрывает платёж как отменённый |
| остальные | оставляет в ожидании |
Особенности
- Шлюз умеет опрос статуса (
GET /v1/orders/{id}) — реконсилятор сам добивает платежи с потерянным вебхуком. - Возвраты по API, рекурренты и сохранённые карты не поддерживаются — возврат делаете в кабинете RioPay, в боте фиксируете результат: /payments/refunds.
- Сумма из вебхука сверяется со счётом: меньше 90% ожидаемого — платёж бракуется как недоплата.
- Назначение платежа (
purpose) обрезается до 128 символов. - Подпись считается по сырым байтам тела — прокси/CDN, переписывающий JSON, будет ронять вебхуки в 403; такие платежи зачислит реконсилятор.
Платёж прошёл, а подписки нет?
Реконсилятор опрашивает RioPay каждые 5 минут и сам зачисляет зависшие оплаты. Как это работает — /payments/webhooks.