Finance OS / API

Payment Gateway (RUB) — Overview

RUB-канал Finance OS: приём оплат картой и через СБП, многоразовые ссылки и QR, полные и частичные возвраты, фискальные чеки.

Методы канала подключаются к аккаунту по договору. Ниже — контракт: сущности, параметры, статусы и правила обработки ответов.

Сущности

Модель

payment (платёж) object optional
Основная операция. Создаётся сразу и несёт ссылки на форму оплаты и QR-код для плательщика.
refund (возврат) object optional
Обратное движение по конкретному платежу — полностью или на часть суммы.
link (кассовая ссылка) object optional
Постоянный QR или URL без фиксированной суммы: плательщик вводит её сам.
template (шаблон) object optional
Постоянный QR с заранее заданной суммой и основанием платежа.
receipt (чек) object optional
Фискальный документ, формируется по платежу и по возврату.
✦
Отдельного «счёта» нет
Роль счёта играет сам платёж: он создаётся до оплаты и живёт до истечения срока. Если нужна постоянная точка приёма — используйте кассовую ссылку или шаблон.

Валюты и способы оплаты

Справочные значения

Валюта операции enum optional
RUB.
Способ оплаты enum optional
sbp, card. Если не указан — плательщик выбирает сам на форме оплаты.

Статусы

Жизненный цикл

payment enum optional
new → paid → processing → completed. Неуспешные исходы: cancelled (отменён неоплаченным), rejected (отклонён эквайером), error.
refund enum optional
new → in_progress → in_finish → completed. Дополнительно postponed (отложен) и error.
⚠
paid — это ещё не завершение
paid означает, что деньги от плательщика получены, но цикл операции продолжается. Отгружайте товар или услугу по completed, иначе рискуете отработать по платежу, который завершится как rejected.
⚠
Наборы статусов у платежа и возврата разные
Совпадает только completed. Не переиспользуйте один справочник статусов на обе сущности.

Формат ответа

Responses

{
  "ok": true,
  "data": { }
}
{
  "ok": false,
  "error": "Человекочитаемое описание",
  "error_key": "machine_readable_code"
}

Поля конверта

ok boolean required
Итог запроса. Проверяйте его, а не только HTTP-код.
data object optional
Полезная нагрузка успешного ответа. Состав полей может расширяться — игнорируйте незнакомые.
error string optional
Описание ошибки для человека. Не разбирайте текст программно.
error_key string optional
Машинный код ошибки для ветвления логики.
✦
Деньги — строками
Суммы приходят строками с десятичной точкой. Считайте деньги строками и десятичной арифметикой: во float на длинных суммах появляются расхождения в копейках.

order_id обязателен

Ваш идентификатор операции (order_id) обязателен при создании платежа. Он возвращается в ответах и уведомлениях и служит способом сопоставить операцию канала с вашей записью.

⊘
Не повторяйте создание платной операции
Таймаут при создании платежа или возврата — это неизвестный исход, а не отказ: операция могла состояться. Выясните её судьбу запросом по своему order_id и создавайте заново только если операции нет.

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

Доступность операций

Операции, двигающие деньги — создание платежа, возврат, изменение ссылок — могут быть недоступны для аккаунта: тогда запрос возвращает 403. Запросы на чтение при этом работают. Подробнее — Errors & Limits.

Дальше

  • Payments — создание платежа и форма оплаты
  • Payment Links — постоянные ссылки и QR-шаблоны
  • Refunds — возвраты
  • Receipts — фискальные чеки
  • Status Updates — как узнавать об изменениях
  • Errors & Limits — коды ошибок и лимиты