Документация REDICE PAY
REDICE PAY API позволяет принимать оплату через Систему быстрых платежей (СБП). Все запросы выполняются по HTTPS, тела запросов и ответов — JSON в кодировке UTF-8. Суммы указываются в рублях.
Аутентификация
После одобрения заявки бот выдаёт два набора ключей — тестовый и боевой. Каждый запрос должен содержать заголовки:
| Заголовок | Значение |
|---|---|
X-Merchant-Id | Идентификатор мерчанта, например mr_7f3a9c2e1b4d |
Authorization | Bearer <secret> — секретный ключ (64 символа) |
Content-Type | application/json |
Схема оплаты
- Ваш сервер создаёт платёж методом
POST /payments. - Клиент переходит на
payment_url(наша страница оплаты) — либо вы показываете QR поsbp_urlу себя. - Клиент оплачивает через приложение своего банка.
- REDICE PAY отправляет webhook
payment.paidна вашcallback_url. - Вы проверяете подпись и выдаёте товар. При необходимости уточняете статус методом
GET /payments/{id}.
Создать платёж
| Поле | Тип | Описание |
|---|---|---|
amount * | number | Сумма в рублях, до 2 знаков после точки, от 1 до 18 000 ₽ за платёж. Например 1700 или 99.90 |
order_id | string | Ваш номер заказа (до 128 символов). Повторный запрос с тем же order_id вернёт уже созданный активный платёж |
description | string | Описание для клиента на странице оплаты (до 255 символов) |
callback_url | string | URL для webhooks по этому платежу (если не задан — используется URL из профиля) |
success_url | string | Куда вернуть клиента после успешной оплаты |
fail_url | string | Куда вернуть клиента при ошибке или истечении срока |
expires_in | number | Время жизни счёта в секундах (300–86400, по умолчанию 1800) |
metadata | object | Любые ваши данные (до 4 КБ). Возвращаются в ответах и webhooks |
curl -X POST https://redicepay.pro/api/v1/payments \
-H "X-Merchant-Id: mr_7f3a9c2e1b4d" \
-H "Authorization: Bearer $REDICE_SECRET" \
-H "Content-Type: application/json" \
-d '{
"amount": 1700,
"order_id": "A-1001",
"description": "Подписка Premium на 1 месяц",
"success_url": "https://shop.ru/thanks",
"callback_url": "https://shop.ru/redice/webhook"
}'
Ответ 201 Created (или 200 OK с "existing": true для повторного order_id):
{
"ok": true,
"existing": false,
"payment": {
"id": "3f1c2a9e-8b7d-4c11-9a51-0e2f6b7c8d90",
"order_id": "A-1001",
"status": "pending",
"amount": "1700.00",
"fee_percent": "0.00",
"fee_amount": "0.00",
"net_amount": "1700.00",
"payer_amount": "1700.00",
"provider_fee_amount": "0.00",
"currency": "RUB",
"method": "sbp",
"description": "Подписка Premium на 1 месяц",
"payment_url": "https://redicepay.pro/pay/3f1c2a9e-8b7d-4c11-9a51-0e2f6b7c8d90",
"sbp_url": "https://qr.nspk.ru/AD10006M…?type=02&…",
"metadata": null,
"created_at": "2026-11-20T12:00:00.000Z",
"expires_at": "2026-11-20T12:30:00.000Z",
"paid_at": null
}
}
payer_amount — итоговая сумма, которую платит клиент. Обычно она равна amount; если комиссию платёжной системы оплачивает покупатель, она больше на provider_fee_amount. Страница оплаты показывает клиенту итоговую сумму и комиссию отдельной строкой. Вам в любом случае причитается сумма заказа amount.
Комиссия REDICE PAY (fee_percent, fee_amount) удерживается из суммы к выплате — net_amount. Ставка фиксируется в момент создания платежа и не меняется задним числом.
Статус платежа
Возвращает объект payment в том же формате. Рекомендуем запрашивать статус не чаще одного раза в 5 секунд и полагаться в первую очередь на webhooks.
Поиск по order_id
Возвращает до 20 последних платежей с этим номером заказа: {"ok": true, "payments": [ … ]}.
Профиль мерчанта
Проверка ключей: возвращает ID, название, режим (live / test) и callback URL по умолчанию.
Webhooks
При каждом изменении статуса платежа мы отправляем POST на ваш callback_url:
POST /redice/webhook
Content-Type: application/json
X-Redice-Signature: 5d0f…c3a1 (HMAC-SHA256 тела запроса вашим секретом, hex)
X-Redice-Merchant: mr_7f3a9c2e1b4d
{
"event": "payment.paid",
"payment": { "id": "3f1c2a9e-…", "order_id": "A-1001", "status": "paid", "amount": "1700.00", … }
}
Ответьте кодом 2xx в течение 10 секунд. Иначе доставка повторится через 1 мин, 5 мин, 15 мин, 1 ч, 3 ч, 12 ч и 24 ч. Обработчик должен быть идемпотентным: одно и то же событие может прийти повторно.
События: payment.paid, payment.expired, payment.failed, payment.canceled.
Проверка подписи
Подпись считается по сырому телу запроса (байты как пришли), без повторной сериализации JSON.
// Node.js (Express)
app.post('/redice/webhook', express.raw({ type: 'application/json' }), (req, res) => {
const sig = crypto.createHmac('sha256', process.env.REDICE_SECRET).update(req.body).digest('hex');
if (!crypto.timingSafeEqual(Buffer.from(sig), Buffer.from(req.get('X-Redice-Signature') || ''))) return res.sendStatus(401);
const { event, payment } = JSON.parse(req.body);
if (event === 'payment.paid') fulfillOrder(payment.order_id);
res.sendStatus(200);
});
# Python (Flask)
sig = hmac.new(SECRET.encode(), request.get_data(), hashlib.sha256).hexdigest()
if not hmac.compare_digest(sig, request.headers.get("X-Redice-Signature", "")):
abort(401)
// PHP
$raw = file_get_contents('php://input');
$sig = hash_hmac('sha256', $raw, getenv('REDICE_SECRET'));
if (!hash_equals($sig, $_SERVER['HTTP_X_REDICE_SIGNATURE'] ?? '')) { http_response_code(401); exit; }
Статусы
| Статус | Описание |
|---|---|
pending | Ожидает оплаты |
paid | Оплачен — финальный статус |
expired | Истёк срок оплаты — финальный |
failed | Ошибка оплаты — финальный |
canceled | Отменён — финальный |
Ошибки
При ошибке возвращается HTTP-код 4xx/5xx и тело {"ok": false, "error": {"code": "…", "message": "…"}}.
| HTTP | code | Причина |
|---|---|---|
| 400 | INVALID_AMOUNT | Некорректная сумма |
| 400 | AMOUNT_OUT_OF_RANGE | Сумма вне допустимого диапазона (1 – 18 000 ₽) |
| 400 | INVALID_*_URL | Неверный формат URL |
| 401 | UNAUTHORIZED | Неверные ключи |
| 403 | MERCHANT_BLOCKED | Мерчант заблокирован |
| 404 | NOT_FOUND | Платёж не найден |
| 429 | RATE_LIMITED | Превышен лимит — 300 запросов в минуту |
| 502 | PAYMENT_UNAVAILABLE | Временно не удалось создать платёж — повторите запрос позже |
Тестовый режим
С тестовыми ключами платежи создаются в песочнице: страница оплаты и QR работают, но деньги не списываются. Чтобы эмулировать оплату:
{ "status": "paid" } // или "failed", "expired"
После вызова придёт webhook — так можно проверить весь цикл интеграции.
Своя страница оплаты
Вместо payment_url можно использовать sbp_url: на компьютере постройте по нему QR-код, на телефоне откройте ссылку — система предложит выбрать приложение банка. Мы рекомендуем нашу страницу: она оптимизирована для всех устройств и автоматически отслеживает статус.