Платежи

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

POST /api/v1/payments

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

Запрос

{
  "amount": "1500.00",
  "payment_currency": "RUB",
  "order_id": "order_12345",
  "terminal_id": "d290f1ee-6c54-4b01-90e6-d701748f0851",
  "description": "Оплата заказа #12345",
  "customer_id": "cust_001",
  "metadata": {
    "internal_ref": "INV-2026-0042"
  }
}

Поле	Тип	Обязательное	Описание
amount	string	да	Сумма в фиате (например "1500.00")
payment_currency	string	да	Код валюты. Сейчас только RUB
order_id	string	да	Ваш уникальный идентификатор заказа
terminal_id	string	нет*	UUID кассы. Не обязателен при аутентификации по API key
description	string	нет	Описание платежа для клиента
customer_id	string	нет	Ваш идентификатор плательщика
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"
}

---

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

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
  │
  └──→ canceled

Статус	Описание
created	Платёж создан, ожидается действие клиента
processing	QR активирован, клиент инициировал оплату
paid	Оплата подтверждена провайдером
expired	Время жизни платежа истекло
canceled	Платёж отменён
chargeback	Отмена после успешной оплаты

---

Страница оплаты (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.