Merchant API Reference

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

Открыть Swagger / OpenAPI

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

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

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

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

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

X-Shop-IDUUID

Уникальный идентификатор вашего магазина.

X-Api-Keystring

Секретный ключ авторизации (формат cis_sec_...). Должен храниться строго на вашем сервере.

Поле	Тип	Описание
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 (Метод оплаты)

CARDstring

Оплата банковской картой РФ.

SBPstring

Оплата по Системе Быстрых Платежей (СБП) через QR-код.

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

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

PENDINGstring

Платеж зарегистрирован и ожидает оплаты (время жизни — 30 минут).

PAIDstring

Средства успешно списаны с плательщика.

FAILEDstring

Платеж отменен банком или провайдером.

EXPIREDstring

Время жизни платежа истекло без оплаты.

REFUNDEDstring

Выполнен полный возврат средств.

Поле	Тип	Описание
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` для перенаправления покупателя.

amountinteger

Сумма в копейках. Обязательно.

order_idstring

Идентификатор заказа в вашей системе (уникальный для магазина). Обязательно.

payment_methodCARD | SBP

Желаемый способ оплаты. Обязательно.

customer_idstring

ID покупателя в вашей системе. Обязательно при SBP.

redirect_success_urlstring

Абсолютный http(s)-адрес возврата после успешной оплаты. Опционально: если не указан, берётся адрес по умолчанию из настроек магазина.

redirect_fail_urlstring

То же для неудачного платежа. Опционально.

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

После подтверждения оплаты покупатель на странице оплаты видит подтверждение и через 5 секунд автоматически переходит на `redirect_success_url` (кнопка перехода доступна сразу). При неудаче автоматического перехода нет — покупателю показывается кнопка возврата, чтобы он мог сначала попробовать оплатить ещё раз. Адрес по умолчанию для обоих случаев задаётся в личном кабинете, в настройках магазина, и применяется в том числе к платежам из песочницы.

Запрос (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-параметра.

idstring (query)

ID платежа в cisPay. Обязательно, если не передан order_id.

order_idstring (query)

ID заказа мерчанта. Обязательно, если не передан id.

Поле	Тип	Описание
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

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

limitint (query)

Количество записей. По умолчанию 20, максимум 100.

offsetint (query)

Смещение для постраничной пагинации. По умолчанию 0.

statusstring (query)

Фильтр по статусу (PENDING, PAID, FAILED, EXPIRED, REFUNDED).

Поле	Тип	Описание
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
    }
  ]
}

Прямой запрос SBP QR

POST/payments/sbp-direct

Регистрирует платёж через СБП и сразу возвращает готовый `sbp_qr_payload` в ответе — без перенаправления покупателя на нашу страницу оплаты. QR-код и весь экран оплаты вы показываете полностью на своей стороне; результат прилетит вебхуком на `webhook_url` или опрашивайте GET /payments/status.

Доступен только магазинам, которым администратор явно включил этот режим (поле `direct_sbp_enabled` в GET /store/capabilities) — по умолчанию выключен для всех магазинов. Без разрешения запрос вернёт 403 Forbidden. Чтобы включить, напишите в поддержку.

amountinteger

Сумма в копейках. Обязательно.

order_idstring

Идентификатор заказа в вашей системе (уникальный для магазина). Обязательно.

customer_idstring

ID покупателя в вашей системе. Обязательно для СБП.

customer_ipstring

Реальный IP-адрес покупателя (не вашего сервера!). Обязательно — в обычном флоу мы берём IP сами из браузера покупателя, здесь это H2H-вызов с вашего сервера, поэтому передайте его явно. Провайдер использует его для антифрод-скоринга.

descriptionstring

Описание платежа. Опционально.

Поле	Тип	Описание
amount	integer	Сумма в копейках. Обязательно.
order_id	string	Идентификатор заказа в вашей системе (уникальный для магазина). Обязательно.
customer_id	string	ID покупателя в вашей системе. Обязательно для СБП.
customer_ip	string	Реальный IP-адрес покупателя (не вашего сервера!). Обязательно — в обычном флоу мы берём IP сами из браузера покупателя, здесь это H2H-вызов с вашего сервера, поэтому передайте его явно. Провайдер использует его для антифрод-скоринга.
description	string	Описание платежа. Опционально.

Запрос (JSON)

{
  "amount": 150000,
  "order_id": "ORDER-99239",
  "customer_id": "cust-8822",
  "customer_ip": "203.0.113.42"
}

Ответ (201 Created)

{
  "id": "7fa12a88-294b-4b11-bbfe-e69c3dbeaab9",
  "order_id": "ORDER-99239",
  "status": "PENDING",
  "amount": 150000,
  "charged_amount": 150000,
  "sbp_qr_payload": "https://qr.nspk.ru/AS...",
  "expires_in_seconds": 1800,
  "created_at": "2026-07-13T10:00:00Z"
}

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

При успешной оплате счета 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Временный сбой

Временная ошибка связи с банком. Рекомендуется повторить запрос позже.

Поле	Тип	Описание
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"
}