Документация для мерчантов

Интегрируйте RolliePay в свой проект за несколько часов. Принимайте P2P-платежи через карты, СБП и переводы.

REST APIWebhooksJSONHTTPS

Введение

RolliePay — процессинговая платформа для приёма P2P-платежей. Мерчант создаёт платёж через API, система автоматически назначает оператора с подходящими реквизитами. Покупатель переводит деньги напрямую оператору, после чего оператор подтверждает получение.

Создайте платёж

POST /api/payments/create с суммой и методом

Перенаправьте

Покупатель оплачивает по реквизитам оператора

Получите webhook

Уведомление об успехе или неуспехе

Аутентификация

Все запросы к API должны содержать ваш API-ключ в заголовке X-Api-Key. Ключ выдаётся администратором и начинается с mk_.

X-Api-Key: mk_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

Храните API-ключ в переменных окружения. Никогда не публикуйте его в клиентском коде или репозитории.

Создать платёж

Основная операция — создание платежа. В ответ получаете объект платежа с реквизитами оператора.

POST

/api/payments/create

Создать новый платёж

Параметры запроса

Поле	Тип	Обяз.	Описание
amount	number	✓	Сумма платежа в рублях
currency	string	✓	"RUB"
method	string	✓	"card" \| "sbp" \| "c2c"
order_id	string		Ваш внутренний ID заказа
callback_url	string		URL для webhook-уведомлений
success_url	string		Редирект при успешной оплате
fail_url	string		Редирект при неуспешной оплате
customer_email	string		Email покупателя
description	string		Описание платежа

Пример запроса

curl -X POST https://merch-production-f1cb.up.railway.app/api/payments/create \
  -H "Content-Type: application/json" \
  -H "X-Api-Key: mk_ваш_ключ" \
  -d '{
    "amount": 1000,
    "currency": "RUB",
    "method": "card",
    "order_id": "ORDER-123",
    "callback_url": "https://yoursite.com/webhook",
    "success_url": "https://yoursite.com/success",
    "fail_url": "https://yoursite.com/fail"
  }'

Ответ

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "amount": 1000,
  "currency": "RUB",
  "method": "card",
  "status": "pending",
  "order_id": "ORDER-123",
  "expires_at": "2024-01-15T12:30:00Z",
  "created_at": "2024-01-15T12:00:00Z",
  "requisite": {
    "type": "card",
    "bank": "sberbank",
    "value": "4276 **** **** 1234",
    "owner_name": "Иван И."
  }
}

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

Получить текущий статус платежа по его UUID (без авторизации — для страницы покупателя).

GET

/api/payments/:id/public

Публичный статус платежа (без авторизации)

curl https://merch-production-f1cb.up.railway.app/api/payments/550e8400-e29b-41d4-a716-446655440000/public

Используйте этот эндпоинт для страницы ожидания оплаты — опрашивайте каждые 5 секунд и редиректьте при статусе success или failed.

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

Статус	Описание	Финальный
pending	Ожидает оплаты от покупателя
success	Оплата подтверждена оператором	✓
failed	Платёж не прошёл / открыт спор	✓
expired	Истекло время ожидания (30 мин)	✓
cancelled	Отменён	✓

Webhook

При изменении статуса платежа RolliePay отправляет POST-запрос на ваш callback_url. Ваш сервер должен вернуть 200 OK.

События

payment.successpayment.failedpayment.expired

POST https://yoursite.com/webhook
Content-Type: application/json

{
  "event": "payment.success",
  "payment": {
    "id": "uuid",
    "order_id": "ORDER-123",
    "amount": 1000,
    "currency": "RUB",
    "method": "card",
    "status": "success",
    "created_at": "2024-01-15T12:00:00Z"
  }
}

Дополнительно проверяйте статус через GET /api/payments/:id/public — webhook может не дойти при временных сетевых сбоях.

Примеры интеграции

Node.js / Express — обработка webhook

app.post('/webhook', express.json(), async (req, res) => {
  const { event, payment } = req.body;

  if (event === 'payment.success') {
    // Зачислить баланс пользователю
    await creditsService.add(payment.order_id, payment.amount);
  }

  res.sendStatus(200); // обязательно вернуть 200
});

Методы оплаты

method	Описание	Валюта
card	Перевод на банковскую карту	RUB
sbp	СБП — Система быстрых платежей	RUB
c2c	Card2Card перевод	RUB

Ошибки

HTTP	message	Причина
401	Invalid API key	Неверный или отсутствующий X-Api-Key
400	Validation failed	Неверные параметры запроса
404	Payment not found	Платёж с таким ID не существует
503	No operators available	Нет доступных операторов для суммы/метода

Нужна помощь с интеграцией?

Наш менеджер ответит на все вопросы по API и настройке

Написать в Telegram