Платежи

Создание платежа

POST /api/v1/payments

Создаёт платёж и возвращает ссылку на страницу оплаты для клиента.

Запрос

{
  "amount": "1500.00",
  "payment_currency": "RUB",
  "payment_method": "sbp",
  "order_id": "order_12345",
  "terminal_id": "d290f1ee-6c54-4b01-90e6-d701748f0851",
  "description": "Оплата заказа #12345",
  "customer_id": "cust_001",
  "success_redirect_url": "https://myshop.com/payment/success",
  "fail_redirect_url": "https://myshop.com/payment/fail",
  "metadata": {
    "internal_ref": "INV-2026-0042"
  }
}

Поле	Тип	Обязательное	Описание
amount	string	да	Сумма в фиате (например "1500.00")
payment_currency	string	да	Код валюты. Сейчас только RUB
payment_method	string	нет	Метод оплаты (например, sbp, card, crypto). Если не передан, будет предложен выбор на платежной форме
order_id	string	да	Ваш уникальный идентификатор заказа
terminal_id	string	нет*	UUID кассы. Не обязателен при аутентификации по API key
description	string	нет	Описание платежа для клиента
customer_id	string	нет	Ваш идентификатор плательщика
redirect_url	string	нет	URL для перенаправления клиента после оплаты (общий). Если не указан — берётся из настроек кассы
success_redirect_url	string	нет	URL перенаправления при успешной оплате. Приоритет: параметр платежа → настройка кассы
fail_redirect_url	string	нет	URL перенаправления при неуспешной оплате (expired/canceled). Приоритет: параметр платежа → настройка кассы
metadata	object	нет	Произвольные данные, возвращаются в колбэках

Ответ 200 OK

{
  "payment_id": "pay_a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "order_id": "order_12345",
  "status": "created",
  "token": "tok_9f8e7d6c5b4a3210",
  "pay_url": "https://pay.rollypay.io/pay/tok_9f8e7d6c5b4a3210",
  "amount": "1500.00",
  "payment_currency": "RUB",
  "qr_content": "",
  "h2h_enabled": false,
  "qr_activated": false,
  "created_at": "2026-02-23T12:00:00Z",
  "expires_at": "2026-02-23T12:30:00Z"
}

Клиента нужно перенаправить по pay_url. Поле qr_content может быть заполнено сразу (например, для H2H) или после активации QR на странице оплаты.

Ошибки

Код	Сообщение
400	terminal not found
400	payment_currency must be RUB
400	amount must be positive
400	payment cap exceeded
500	unable to create payment

---

Получение платежа

GET /api/v1/payments/{paymentID}

Возвращает объект платежа: статус, сумма, итоговый курс, комиссия, время оплаты и другие данные по платежу.

Пример ответа (фрагмент):

{
  "payment_id": "pay_...",
  "order_id": "order_12345",
  "amount": "1500.00",
  "payment_currency": "RUB",
  "status": "paid",
  "pay_url": "https://pay.rollypay.io/pay/tok_...",
  "rate_final": "93.89",
  "amount_usdt_net": "15.50",
  "platform_fee_percent": "3.00",
  "platform_fee_usdt": "0.48",
  "paid_at": "2026-02-23T12:05:32Z",
  "created_at": "2026-02-23T12:00:00Z",
  "expires_at": "2026-02-23T12:30:00Z"
}

Поля rate_final, amount_usdt_net, platform_fee_percent и platform_fee_usdt заполняются после завершения конвертации. Если конвертация выполняется не сразу, например по сценарию T+1, эти поля могут временно отсутствовать до её завершения.

---

Список платежей

GET /api/v1/payments

Параметр	Описание
terminal_id	Фильтр по UUID кассы
status	Фильтр по статусу: created, paid, expired и т.д.

Ответ: объект с полями items (массив платежей) и total.

Пример: GET /api/v1/payments?terminal_id=d290f1ee-...&status=paid

---

Статусы платежа

Цепочка состояний:

created ──→ processing ──→ paid
  │                          │
  ├──→ expired               ├──→ chargeback
  │                          └──→ refunded
  │
  └──→ canceled

Статус	Описание
created	Платёж создан, ожидается действие клиента
processing	QR активирован, клиент инициировал оплату
paid	Платёж успешно подтверждён
expired	Время жизни платежа истекло
canceled	Платёж отменён
chargeback	Отмена после успешной оплаты
refunded	Возврат средств по оплаченному платежу успешно завершён (заявка на возврат в статусе completed после автоматического возврата у провайдера или после ручного подтверждения админом). В API и в колбэках status = refunded

После финализации возврата на callback_url уходят два события подряд — refund_request.completed и payment.refunded (одинаковое тело по платежу, различается только event_type; так сохранена совместимость со старыми интеграциями). Подробнее — Колбэки.

---

Страница оплаты (PayForm)

После создания платежа в ответе приходит pay_url — страница, на которой клиент видит сумму и реквизиты и может оплатить (QR СБП или другой способ).

Сценарий:

1. Создать платёж через API → получить pay_url
2. Перенаправить клиента на pay_url
3. Клиент видит страницу с суммой и названием мерчанта
4. Клиент нажимает «Оплатить» → генерируется QR (СБП) или показывается выбор способа (общая пейформа)
5. Клиент сканирует QR или выбирает способ оплаты
6. Платёж получает финальный успешный статус paid
7. На ваш callback_url уходит уведомление
8. Клиент перенаправляется на success_redirect_url (если передан при создании платежа или настроен в кассе)

Публичные эндпоинты (без авторизации, для виджета оплаты):

Метод	Путь	Назначение
GET	/public/payments/{token}	Данные платежа для отображения формы
GET	/public/payments/{token}/status	Опрос статуса
POST	/public/payments/{token}/activate	Активация генерации QR

Использовать их нужно только если вы делаете свою страницу оплаты; в типовом сценарии достаточно редиректа на pay_url.