Платежи

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

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`. Значение `EUR` допускается только для `payment_method: "intl_card"` (см. «Международные платежи» ниже)
`payment_method`	string	нет	Метод оплаты (например, `sbp`, `card`, `intl_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	нет	Произвольные данные, возвращаются в колбэках
`test`	boolean	нет	`true` — создать тестовый (sandbox) платёж. См. Тестовый режим

Международные платежи (EUR)

Для приёма оплат международными картами (Visa/Mastercard вне РФ) укажите способ оплаты intl_card. Сумму можно задавать сразу в евро — это удобно, если ваши цены в EUR:

{
  "amount": "5.00",
  "payment_currency": "EUR",
  "payment_method": "intl_card",
  "order_id": "order_12345",
  "description": "Top up balance"
}

Правила:

payment_currency: "EUR" разрешено только вместе с payment_method: "intl_card". Для остальных методов валюта — RUB.
Минимальная сумма EUR-платежа — 1 EUR.
Можно по-прежнему создавать intl_card и в рублях (payment_currency: "RUB") — тогда сумма конвертируется в EUR по текущему курсу на стороне RollyPay.
При оплате средства зачисляются на ваш баланс в USDT (баланс единый, в USDT) по курсу EUR→USDT на момент конвертации. Отдельного баланса в евро нет.
В статистике такие платежи отражаются и в обороте (рублёвый эквивалент), и отдельной метрикой «Оборот EUR».

Ответ 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	Валюта платежа должна быть RUB (EUR допустим только для `intl_card`)
400	Сумма слишком мала для выбранного способа оплаты (для EUR — минимум 1 EUR)
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 СБП или другой способ).

Сценарий:

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

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

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

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

Тестовый режим

Интеграцию можно проверить на той же кассе и с тем же API-ключом, без реальных денег — достаточно добавить "test": true в запрос создания платежа. Тестовые платежи не влияют на баланс и аналитику.

Подробности, пример запроса, симуляция оплаты на pay-форме и формат тестовых колбэков — в разделе Тестовый режим (Sandbox).

Платежи

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

Запрос​

Международные платежи (EUR)​

Ответ 200 OK​

Ошибки​

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

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

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

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

Тестовый режим​