REDICEPAY
API v1

Документация REDICE PAY

REDICE PAY API позволяет принимать оплату через Систему быстрых платежей (СБП). Все запросы выполняются по HTTPS, тела запросов и ответов — JSON в кодировке UTF-8. Суммы указываются в рублях.

Базовый URL: https://redicepay.pro/api/v1

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

После одобрения заявки бот выдаёт два набора ключей — тестовый и боевой. Каждый запрос должен содержать заголовки:

ЗаголовокЗначение
X-Merchant-IdИдентификатор мерчанта, например mr_7f3a9c2e1b4d
AuthorizationBearer <secret> — секретный ключ (64 символа)
Content-Typeapplication/json
Секретный ключ используется только на вашем сервере. Никогда не передавайте его в браузер, мобильное приложение или публичный репозиторий. Если ключ утёк — перевыпустите его в боте («Мои ключи»).

Схема оплаты

  1. Ваш сервер создаёт платёж методом POST /payments.
  2. Клиент переходит на payment_url (наша страница оплаты) — либо вы показываете QR по sbp_url у себя.
  3. Клиент оплачивает через приложение своего банка.
  4. REDICE PAY отправляет webhook payment.paid на ваш callback_url.
  5. Вы проверяете подпись и выдаёте товар. При необходимости уточняете статус методом GET /payments/{id}.

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

POST/api/v1/payments
ПолеТипОписание
amount *numberСумма в рублях, до 2 знаков после точки, от 1 до 18 000 ₽ за платёж. Например 1700 или 99.90
order_idstringВаш номер заказа (до 128 символов). Повторный запрос с тем же order_id вернёт уже созданный активный платёж
descriptionstringОписание для клиента на странице оплаты (до 255 символов)
callback_urlstringURL для webhooks по этому платежу (если не задан — используется URL из профиля)
success_urlstringКуда вернуть клиента после успешной оплаты
fail_urlstringКуда вернуть клиента при ошибке или истечении срока
expires_innumberВремя жизни счёта в секундах (300–86400, по умолчанию 1800)
metadataobjectЛюбые ваши данные (до 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. Ставка фиксируется в момент создания платежа и не меняется задним числом.

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

GET/api/v1/payments/{id}

Возвращает объект payment в том же формате. Рекомендуем запрашивать статус не чаще одного раза в 5 секунд и полагаться в первую очередь на webhooks.

Поиск по order_id

GET/api/v1/payments?order_id=A-1001

Возвращает до 20 последних платежей с этим номером заказа: {"ok": true, "payments": [ … ]}.

Профиль мерчанта

GET/api/v1/me

Проверка ключей: возвращает 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": "…"}}.

HTTPcodeПричина
400INVALID_AMOUNTНекорректная сумма
400AMOUNT_OUT_OF_RANGEСумма вне допустимого диапазона (1 – 18 000 ₽)
400INVALID_*_URLНеверный формат URL
401UNAUTHORIZEDНеверные ключи
403MERCHANT_BLOCKEDМерчант заблокирован
404NOT_FOUNDПлатёж не найден
429RATE_LIMITEDПревышен лимит — 300 запросов в минуту
502PAYMENT_UNAVAILABLEВременно не удалось создать платёж — повторите запрос позже

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

С тестовыми ключами платежи создаются в песочнице: страница оплаты и QR работают, но деньги не списываются. Чтобы эмулировать оплату:

POST/api/v1/payments/{id}/simulate
{ "status": "paid" }   // или "failed", "expired"

После вызова придёт webhook — так можно проверить весь цикл интеграции.

Своя страница оплаты

Вместо payment_url можно использовать sbp_url: на компьютере постройте по нему QR-код, на телефоне откройте ссылку — система предложит выбрать приложение банка. Мы рекомендуем нашу страницу: она оптимизирована для всех устройств и автоматически отслеживает статус.

Остались вопросы? Напишите в Telegram-бот — поможем с интеграцией.