Merchant API Reference

Интеграционный API для приема быстрых платежей. Базовый адрес шлюза:https://api.cispay.app. Все денежные значения передаются в копейках для исключения погрешностей вычислений.

Открыть Swagger / OpenAPI

1. Создайте счет

2. Перенаправьте на чекаут

3. Получите результат

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

Все запросы к нашему шлюзу авторизуются с помощью заголовков:

Поле	Тип	Описание
X-Shop-ID	UUID	Уникальный идентификатор вашего магазина.
X-Api-Key	string	Секретный ключ авторизации (формат cis_sec_...). Должен храниться строго на вашем сервере.

cURL

curl https://api.cispay.app/balance \
  -H "X-Shop-ID: c56d9539-7814-4112-9c44-59e55728a3bd" \
  -H "X-Api-Key: cis_sec_live_9b2e04f32a76cc89"

Справочники системы

payment_method (Метод оплаты)

Поле	Тип	Описание
CARD	string	Оплата банковской картой РФ.
SBP	string	Оплата по Системе Быстрых Платежей (СБП) через QR-код.

status (Статус транзакции)

Поле	Тип	Описание
PENDING	string	Платеж зарегистрирован и ожидает оплаты (время жизни — 30 минут).
PAID	string	Средства успешно списаны с плательщика.
FAILED	string	Платеж отменен банком или провайдером.
EXPIRED	string	Время жизни платежа истекло без оплаты.
REFUNDED	string	Выполнен полный возврат средств.

JSON

// Справочные форматы статусов и методов
{
  "payment_method": "CARD | SBP",
  "status": "PENDING | PAID | FAILED | EXPIRED | REFUNDED",
  "customer_fee_share_percent": "0-10000 (basis points; 0 = merchant absorbs the fee, 10000 = fully passed to the customer)"
}

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

POST/payments

Создает счет и возвращает ссылку `payment_url` для перенаправления покупателя.

Поле	Тип	Описание
amount	integer	Сумма в копейках. Обязательно.
order_id	string	Идентификатор заказа в вашей системе (уникальный для магазина). Обязательно.
payment_method	CARD \| SBP	Желаемый способ оплаты. Обязательно.
customer_id	string	ID покупателя в вашей системе. Обязательно при SBP.
redirect_success_url	string	Адрес возврата после успешной оплаты. Опционально.
redirect_fail_url	string	Адрес возврата при неудачном платеже. Опционально.

Запрос (JSON)

{
  "amount": 150000,
  "order_id": "ORDER-99238",
  "payment_method": "CARD",
  "redirect_success_url": "https://myshop.ru/success",
  "redirect_fail_url": "https://myshop.ru/fail"
}

Ответ (201 Created)

{
  "id": "7fa12a88-294b-4b11-bbfe-e69c3dbeaab9",
  "order_id": "ORDER-99238",
  "status": "PENDING",
  "amount": 150000,
  "charged_amount": 150000,
  "payment_url": "https://cispay.app/pay/7fa12a88-294b-4b11-bbfe-e69c3dbeaab9",
  "created_at": "2026-07-13T10:00:00Z"
}

Проверка статуса

GET/payments/status

Используется для опроса статуса платежа. Вы должны передавать либо внутренний ID шлюза (`id`), либо ваш идентификатор (`order_id`) в качестве query-параметра.

Поле	Тип	Описание
id	string (query)	ID платежа в cisPay. Обязательно, если не передан order_id.
order_id	string (query)	ID заказа мерчанта. Обязательно, если не передан id.

Запрос

curl https://api.cispay.app/payments/status?id=7fa12a88-294b-4b11-bbfe-e69c3dbeaab9 \
  -H "X-Shop-ID: c56d9539-7814-4112-9c44-59e55728a3bd" \
  -H "X-Api-Key: cis_sec_live_9b2e04f32a76cc89"

Ответ (200 OK)

{
  "id": "7fa12a88-294b-4b11-bbfe-e69c3dbeaab9",
  "order_id": "ORDER-99238",
  "status": "PAID",
  "amount": 150000,
  "charged_amount": 150000,
  "payment_method": "CARD",
  "currency": "RUB",
  "store_name": "Мой Магазин",
  "paid_at": "2026-07-13T10:02:14Z",
  "created_at": "2026-07-13T10:00:00Z"
}

Список транзакций

GET/transactions

Позволяет получить список последних транзакций магазина с фильтрацией по статусу. Список отсортирован по дате создания в обратном порядке.

Поле	Тип	Описание
limit	int (query)	Количество записей. По умолчанию 20, максимум 100.
offset	int (query)	Смещение для постраничной пагинации. По умолчанию 0.
status	string (query)	Фильтр по статусу (PENDING, PAID, FAILED, EXPIRED, REFUNDED).

Запрос

curl "https://api.cispay.app/transactions?limit=1&status=PAID" \
  -H "X-Shop-ID: c56d9539-7814-4112-9c44-59e55728a3bd" \
  -H "X-Api-Key: cis_sec_live_9b2e04f32a76cc89"

Ответ

{
  "items": [
    {
      "id": "7fa12a88-294b-4b11-bbfe-e69c3dbeaab9",
      "order_id": "ORDER-99238",
      "payment_method": "CARD",
      "status": "PAID",
      "amount": 150000,
      "charged_amount": 150000,
      "merchant_revenue": 144000,
      "customer_id": "cust-8822",
      "paid_at": "2026-07-13T10:02:14Z",
      "created_at": "2026-07-13T10:00:00Z"
    }
  ],
  "limit": 1,
  "offset": 0,
  "has_more": false
}

Баланс мерчанта

GET/balance

Возвращает текущий баланс личного кабинета мерчанта и сумму выплат в обработке.

Ответ

{
  "pending_conversion_rub_kopecks": 4820000,
  "available_usd_cents": 12345,
  "pending_payouts_usd_cents": 0
}

Возможности магазина

GET/store/capabilities

Запрос возвращает список активированных методов оплаты с тарифами в базисных пунктах (400 = 4.0%).

Ответ

{
  "store_id": "c56d9539-7814-4112-9c44-59e55728a3bd",
  "store_name": "Мой Магазин",
  "is_active": true,
  "payment_methods": [
    {
      "payment_method": "CARD",
      "is_active": true,
      "system_fee_percent": 400,
      "customer_fee_share_percent": 0
    },
    {
      "payment_method": "SBP",
      "is_active": true,
      "system_fee_percent": 400,
      "customer_fee_share_percent": 0
    }
  ]
}

Вебхуки (Уведомления)

При успешной оплате счета cisPay асинхронно отправляет HTTP POST запрос на `webhook_url` магазина. Для проверки подлинности проверяйте заголовок `X-Signature`, вычисляя хэш HMAC-SHA256 от тела запроса с использованием `X-Api-Key` в качестве ключа.

Вебхук (JSON)

{
  "id": "7fa12a88-294b-4b11-bbfe-e69c3dbeaab9",
  "store_id": "c56d9539-7814-4112-9c44-59e55728a3bd",
  "order_id": "ORDER-99238",
  "payment_method": "CARD",
  "status": "PAID",
  "amount": 150000,
  "currency": "RUB",
  "charged_amount": 150000,
  "merchant_revenue": 144000,
  "paid_at": "2026-07-13T10:02:14Z",
  "timestamp": "2026-07-13T10:02:15Z"
}

Python

import hmac
import hashlib

def verify_webhook(api_key: str, body: bytes, header_sig: str) -> bool:
    expected = hmac.new(
        api_key.encode("utf-8"),
        body,
        hashlib.sha256
    ).hexdigest()
    return hmac.compare_digest(expected, header_sig)

# body - сырое тело POST запроса в байтах
# header_sig - значение заголовка X-Signature

Node.js

const crypto = require("crypto");

function verifyWebhook(apiKey, rawBody, headerSig) {
  const expected = crypto
    .createHmac("sha256", apiKey)
    .update(rawBody)
    .digest("hex");
  return crypto.timingSafeEqual(
    Buffer.from(expected),
    Buffer.from(headerSig)
  );
}

Коды ответов шлюза

Наш API использует стандартные коды состояния HTTP для индикации успешности запросов:

Поле	Тип	Описание
400 Bad Request	Ошибка запроса	Некорректный JSON, отсутствует обязательное поле, либо метод оплаты не активен.
401 Unauthorized	Ошибка доступа	Неверный X-Shop-ID или X-Api-Key.
404 Not Found	Не найдено	Транзакция отсутствует в базе данных.
502 Bad Gateway	Временный сбой	Временная ошибка связи с банком. Рекомендуется повторить запрос позже.

Пример Ошибки (401)

{
  "detail": "Некорректный ключ X-Api-Key или Shop ID"
}