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

Rosplat — Платежная платформа

Мы помогаем на всех этапах подключения, поэтому не стесняйтесь обращаться за помощью по интеграции к нам в рабочий чат, сотрудники технического отдела окажут всю нужную помощь и ответят на вопросы.

Подключение к Rosplat

Создание проекта

В личном кабинете вы можете создать новый проект и указать в его настройках:

• Название проекта — публичное имя вашего проекта;
• Страница успешной оплаты — адрес страницы, на которую пользователь будет перенаправлен после успешной оплаты;
• Callback URL — адрес, на который будут отправлены события изменения статусов.

Проверка проекта

После создания проекта и редактирования его настроек, мы проверим его на соответствие требованиям.

Введение в API

Базовый URL для всех запросов к API вы всегда можете получить в ЛК на сайте или в рабочем чате.

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

Для аутентификации запросов нужно передать в headers:

• x-shop — id вашего проекта;
• x-secret — Секретный ключ вашего проекта.

Эти данные можно получить в настройках вашего проекта в ЛК.

Баланс и статус проекта

Чтобы получить информацию о статусе проекта и его текущий баланс:

Ответ:

{
  "success": 1,
  "shop": {
    "id": 111,
    "balance": 111111.11,
    "status": 1
  }
}

Платежи

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

• sbp — оплата по номеру телефона (СБП);
• card — оплата по реквизитам карты.

Схемы создания платежей

• redirect — перенаправление пользователя на страницу оплаты;
• host-2-host — оплата без перенаправления пользователя.

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

Основные (отсылаются на Callback URL):

Полный список:

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

Создание нового заказа и инициация платежа через Host-2-Host API.

Поля запроса (все обязательные):

• merchant_order_id (string) — уникальный ID заказа у мерчанта;
• user_id (string) — ID пользователя у мерчанта;
• email (string) — email пользователя;
• method (string) — метод оплаты: sbp или card;
• amount (integer) — сумма в рублях (без копеек).

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

{
  "merchant_order_id": "order1234567890",
  "user_id": "user1234567890",
  "email": "user@example.com",
  "method": "sbp",
  "amount": 1000
}

Ответ (метод sbp):

{
  "success": 1,
  "payment": {
    "note": {
      "pan": "+7XXXXXXXXXX",
      "fio": "Иванов Иван",
      "type": "sbp",
      "bank": "Т-Банк"
    },
    "id": 4040404,
    "status": 0,
    "amount_to_shop": 820,
    "amount_to_pay": 1000,
    "changed_amount": 1000,
    "amount": 1000,
    "updatedAt": "2025-05-05T15:45:42.079Z",
    "createdAt": "2025-05-05T15:45:41.933Z",
    "expired": "2025-05-05T15:55:42.079Z"
  }
}

Ответ (метод card):

{
  "success": 1,
  "payment": {
    "note": {
      "pan": "2200XXXXXXXXXXXX",
      "fio": "Иванов Иван",
      "type": "card",
      "bank": "Банк Екатеринбург"
    },
    "id": 4040408,
    "status": 0,
    "amount_to_shop": 820,
    "amount_to_pay": 1000,
    "changed_amount": 1000,
    "amount": 1000,
    "updatedAt": "2025-05-05T19:08:10.259Z",
    "createdAt": "2025-05-05T19:08:10.186Z",
    "expired": "2025-05-05T19:18:10.258Z"
  }
}

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

Формируется платежная ссылка, которая редиректит на платежную страницу.

Поля запроса (все обязательные):

• shop_id (integer) — ID магазина;
• sign (string) — подпись, формируется с помощью приватного ключа;
• merchant_order_id (string) — уникальный ID заказа у мерчанта;
• user_id (string) — ID пользователя у мерчанта;
• method (string) — метод оплаты: sbp или card;
• amount (integer) — сумма в рублях (без копеек).

Подпись запроса (signature)

Пример формирования подписи (Node.js):

const crypto = require("crypto");

const getMd5HashSignature = (shop_id, secret, amount, merchant_order_id) => {
  return crypto
    .createHash("md5")
    .update(`${shop_id}:${secret}:${amount}:${merchant_order_id}`)
    .digest("hex");
};

После оплаты платежная форма редиректит на вашу страницу успешного платежа, а платформа отправляет событие на ваш Callback URL.

Статус ордера платежа

Ответ:

{
  "success": 1,
  "order": {
    "id": 111111111,
    "shop_id": 111,
    "status": 2
  }
}

Отмена платежа

Мерчанты могут отменить платеж в статусе ожидания оплаты (status = 0).

Поля запроса:

• guid (string, обязательно) — уникальный идентификатор платежа (GUID).

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

{
  "guid": "11e1c118-f111-54b4-11d1-dbfea712a11a"
}

Успешный ответ:

{
  "success": true,
  "message": "Deal canceled successfully"
}

Выплаты

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

• sbp — выплата по номеру телефона (СБП);
• card — выплата по реквизитам карты.

Статусы выплат

Создание заявки на выплату

Поля запроса:

• amount (integer) — сумма выплаты (обязательно);
• method (string) — метод: card или sbp (обязательно);
• pan (string) — номер карты или телефона (обязательно);
• fio (string) — ФИО владельца (опционально);
• bank (string) — название банка (опционально).

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

{
  "amount": 1000,
  "method": "card",
  "pan": "XXXXXXXXXXXXXXXX",
  "fio": "Иванов Иван Иванович",
  "bank": "Сбербанк"
}

Ответ:

{
  "success": 1,
  "requestPayout": {
    "id": 1,
    "shop_id": 1,
    "amount": 1000,
    "method": "card",
    "fio": "Иванов Иван Иванович",
    "pan": "XXXXXXXXXXXXXXXX",
    "bank": "Сбербанк",
    "createdAt": "2023-10-01T00:00:00.000Z",
    "updatedAt": "2023-10-01T00:00:00.000Z"
  }
}

Статус заявки на выплату

По внутреннему ID:

По внешнему ID мерчанта:

Ответ:

{
  "success": 1,
  "payout_request": {
    "id": 1111,
    "merchant_payout_id": "rp12345",
    "shop_id": 111,
    "status": 6
  }
}

Сверка выплат (Reconciliation)

Когда выплата переходит в статус 9 (Reconciliation), платформа отправляет на ваш Callback URL событие payout_reconciliation с данными выплаты. Мерчант должен подтвердить или отклонить выплату, вернув HTTP-статус:

• HTTP 200 / 201 — выплата подтверждена, переходит в статус 0 (в обработку);
• Любой другой HTTP-статус — выплата отклонена и автоматически отменяется (статус -1).

Callback payout_reconciliation:

{
  "event": "payout_reconciliation",
  "request_payout_id": 12345,
  "shop_id": 111,
  "merchant_payout_id": "rp12345",
  "amount": 10000,
  "method": "card",
  "pan": "XXXXXXXXXXXXXXXX",
  "bank": "Сбербанк",
  "createdAt": "2025-05-05T15:45:42.079Z"
}

Поля события:

API сверки баланса мерчанта

API позволяет получить журнал всех зафиксированных изменений баланса магазина за выбранный период. Ручка предназначена для регулярной сверки, например раз в неделю.

Подключение и авторизация

Перед использованием служба поддержки должна включить API сверки для нужного магазина. Замените базовый URL в примерах на URL, выданный при подключении.

В каждый запрос необходимо передавать заголовки:

x-shop: 123
x-secret: your_merchant_secret

• x-shop — ID магазина;
• x-secret — секретный ключ магазина.

Получение журнала сверки

Query-параметры:

Правила периода:

• используется полуинтервал [from, to);
• максимальная длительность — 31 день;
• to не может находиться в будущем;
• часовой пояс обязателен: используйте Z для UTC или явное смещение, например +03:00;
• в ответе границы периода нормализуются в UTC.

Пример недельного периода:

from=2026-08-03T00:00:00Z
to=2026-08-10T00:00:00Z

Проводка с датой ровно 2026-08-03T00:00:00Z попадёт в ответ, а проводка с датой ровно 2026-08-10T00:00:00Z уже относится к следующему периоду.

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

curl --get 'https://api.example.com/merchant/reconciliation/api' \
  --header 'x-shop: 123' \
  --header 'x-secret: your_merchant_secret' \
  --data-urlencode 'from=2026-08-03T00:00:00Z' \
  --data-urlencode 'to=2026-08-10T00:00:00Z' \
  --data-urlencode 'limit=3'

Пример ответа первой страницы:

{
  "success": 1,
  "shop_id": 123,
  "period": {
    "from": "2026-08-03T00:00:00.000Z",
    "to": "2026-08-10T00:00:00.000Z",
    "bounds": "[from,to)"
  },
  "entries": [
    {
      "entry_id": 9001,
      "occurred_at": "2026-08-03T08:15:00.000Z",
      "money_log_type": "deposit_shop",
      "entity_type": "deposit",
      "entity_id": 501,
      "merchant_operation_id": null,
      "component": "principal",
      "amount": "50000.00",
      "balance_before": "100000.00",
      "balance_after": "150000.00"
    },
    {
      "entry_id": 9002,
      "occurred_at": "2026-08-04T10:30:00.000Z",
      "money_log_type": "payment",
      "entity_type": "payment",
      "entity_id": 1001,
      "merchant_operation_id": "PAY-2026-1001",
      "component": "principal",
      "amount": "9700.00",
      "balance_before": "150000.00",
      "balance_after": "159700.00"
    },
    {
      "entry_id": 9003,
      "occurred_at": "2026-08-05T13:00:00.000Z",
      "money_log_type": "payout_request",
      "entity_type": "payout_request",
      "entity_id": 2001,
      "merchant_operation_id": "PAYOUT-2026-2001",
      "component": "principal",
      "amount": "-5000.00",
      "balance_before": "159700.00",
      "balance_after": "154700.00"
    }
  ],
  "pagination": {
    "limit": 3,
    "has_more": true,
    "next_cursor": "eyJ2IjoxLCJzaG9wX2lkIjoxMjMsImZyb20iOiIyMDI2LTA4LTAzVDAwOjAwOjAwLjAwMFoiLCJ0byI6IjIwMjYtMDgtMTBUMDA6MDA6MDAuMDAwWiIsImNyZWF0ZWRfYXQiOiIyMDI2LTA4LTA1VDEzOjAwOjAwLjAwMFoiLCJpZCI6OTAwM30"
  },
  "summary": {
    "totals": {
      "deposits": { "count": 1, "amount": "50000.00" },
      "payments": { "count": 1, "amount": "9700.00" },
      "payout_principal": { "count": 1, "amount": "-5000.00" },
      "payout_fees": { "count": 1, "amount": "-250.00" },
      "payout_reversals": { "count": 0, "amount": "0.00" },
      "withdrawals": { "count": 1, "amount": "-2000.00" },
      "manual_adjustments": { "count": 1, "amount": "100.00" },
      "internal_transfers": { "count": 0, "amount": "0.00" },
      "other": { "count": 0, "amount": "0.00" }
    },
    "opening_balance": "100000.00",
    "closing_balance": "152550.00",
    "net_change": "52550.00",
    "expected_closing_balance": "152550.00",
    "difference": "0.00"
  }
}

Пагинация

Если pagination.has_more равен true, выполните следующий запрос с next_cursor. Значения from и to должны полностью совпадать с первым запросом.

curl --get 'https://api.example.com/merchant/reconciliation/api' \
  --header 'x-shop: 123' \
  --header 'x-secret: your_merchant_secret' \
  --data-urlencode 'from=2026-08-03T00:00:00Z' \
  --data-urlencode 'to=2026-08-10T00:00:00Z' \
  --data-urlencode 'limit=3' \
  --data-urlencode 'cursor=eyJ2IjoxLCJzaG9wX2lkIjoxMjMsImZyb20iOiIyMDI2LTA4LTAzVDAwOjAwOjAwLjAwMFoiLCJ0byI6IjIwMjYtMDgtMTBUMDA6MDA6MDAuMDAwWiIsImNyZWF0ZWRfYXQiOiIyMDI2LTA4LTA1VDEzOjAwOjAwLjAwMFoiLCJpZCI6OTAwM30'

Пример последней страницы:

{
  "success": 1,
  "shop_id": 123,
  "period": {
    "from": "2026-08-03T00:00:00.000Z",
    "to": "2026-08-10T00:00:00.000Z",
    "bounds": "[from,to)"
  },
  "entries": [
    {
      "entry_id": 9004,
      "occurred_at": "2026-08-05T13:00:01.000Z",
      "money_log_type": "payout_request_fee",
      "entity_type": "payout_request",
      "entity_id": 2001,
      "merchant_operation_id": "PAYOUT-2026-2001",
      "component": "fee",
      "amount": "-250.00",
      "balance_before": "154700.00",
      "balance_after": "154450.00"
    },
    {
      "entry_id": 9005,
      "occurred_at": "2026-08-06T11:00:00.000Z",
      "money_log_type": "withdraw",
      "entity_type": "withdraw",
      "entity_id": 3001,
      "merchant_operation_id": null,
      "component": "principal",
      "amount": "-2000.00",
      "balance_before": "154450.00",
      "balance_after": "152450.00"
    },
    {
      "entry_id": 9006,
      "occurred_at": "2026-08-07T09:00:00.000Z",
      "money_log_type": "manual_adjustment",
      "entity_type": "manual_adjustment",
      "entity_id": null,
      "merchant_operation_id": null,
      "component": "other",
      "amount": "100.00",
      "balance_before": "152450.00",
      "balance_after": "152550.00"
    }
  ],
  "pagination": {
    "limit": 3,
    "has_more": false,
    "next_cursor": null
  }
}

Значение полей проводки

Связанные сущности и идентификаторы

Для одной выплаты обычно создаются отдельные проводки:

• component = principal — тело выплаты;
• component = fee — комиссия;
• component = principal_reverse — возврат тела выплаты;
• component = fee_reverse — возврат комиссии.

Поэтому count в сводке — количество проводок, а не обязательно количество уникальных заявок.

Как проверять сводку

opening_balance + net_change = expected_closing_balance
closing_balance - expected_closing_balance = difference

• difference = "0.00" означает, что доступные проводки сходятся с зафиксированным конечным балансом;
• ненулевой difference означает, что в истории есть изменение, которое невозможно детализировать через доступный журнал. Передайте период, shop_id и значение difference службе поддержки.

Базовый flow еженедельной сверки

1. Определите закрытый недельный период. Рекомендуется использовать UTC и не включать текущий незавершённый день.
2. Выполните первый запрос без cursor.
3. Сохраните summary и обработайте entries.
4. Дедуплицируйте проводки по entry_id.
5. Для payment, payout_request и withdraw сопоставьте merchant_operation_id со своей заявкой. Для deposit используйте только entity_id нашей системы.
6. Пока has_more = true, повторяйте запрос с next_cursor, сохраняя исходные from и to.
7. Суммируйте все полученные amount и сравните результат со summary.net_change.
8. Проверьте summary.difference. При ненулевом значении обратитесь в поддержку.
9. После успешной сверки сохраните границу to; следующий период начинайте ровно с неё, чтобы не получить пропуски или пересечения.

Rate limit

Допускается 30 запросов в минуту на один магазин. Ответ содержит заголовки:

X-RateLimit-Limit: 30
X-RateLimit-Remaining: 29
X-RateLimit-Reset: 60

При превышении лимита возвращается HTTP 429:

{
  "error": "reconciliation_rate_limit_exceeded",
  "limit": 30,
  "reset_in": 42
}

Повторите запрос не раньше чем через reset_in секунд.

Ошибки

API не включён — HTTP 403:

{
  "error": "reconciliation_api_disabled"
}

Некорректный период — HTTP 400:

{
  "error": "invalid_period",
  "message": "from must be an ISO 8601 timestamp with timezone"
}

Другие ошибки валидации:

• period_too_large — период превышает 31 день;
• invalid_limit — недопустимое значение limit;
• invalid_cursor — курсор повреждён, изменён или относится к другому магазину/периоду.

Ошибки авторизации возвращаются при отсутствующем или неверном x-shop/x-secret. В этом случае проверьте выданные реквизиты и активность магазина.

Апелляции

Типы апелляций

• Первичные — время на разрешение диспута 30 минут;
• Повторные — время на разрешение диспута 6 часов.

Поддерживаемые типы файлов

*.png   *.jpeg   *.jpg   *.pdf   *.mp4   *.mov

Статусы апелляций

Создание апелляции

Поля запроса (все обязательные):

• payment_id (integer) — ID платежа, к которому есть диспут;
• note (string) — комментарий пользователя;
• file (blob) — файл чека, доказательство оплаты.

Ответ:

{
  "success": 1,
  "appeal": { "id": 123 }
}

Статус апелляции

Ответ:

{
  "success": 1,
  "appeal": {
    "id": 11111,
    "payment_id": 111111111,
    "status": 1
  }
}

Коллбеки

Ваш Callback URL должен быть доступен по протоколу HTTPS и принимать POST запросы.

Необходимо возвращать статус 200 или 201, в случае ошибки событие отправится повторно.

Список событий

Пример события payment_changed_status:

{
  "event": "payment_changed_status",
  "status": 1,
  "payment_id": 4040404,
  "guid": "11e1c118-f111-54b4-11d1-dbfea712a11a",
  "shop_id": 123,
  "merchant_id": "order1234567890",
  "user_id": "user1234567890",
  "email": "user@example.com",
  "amount_to_shop": 820,
  "amount_to_pay": 1000,
  "changed_amount": 1000,
  "amount": 1000,
  "method_group": "sbp",
  "updatedAt": "2025-05-05T15:45:42.079Z",
  "createdAt": "2025-05-05T15:45:41.933Z",
  "signature": "118809ecb4ef902326d55f1243e296b2..."
}

Пример события request_payout_changed_status:

{
  "event": "request_payout_changed_status",
  "request_payout_id": 12345,
  "status": 3,
  "status_detail": "Approved",
  "amount": 10000,
  "updatedAt": "2025-05-05T15:45:42.079Z"
}

Пример события appeal_changed_status (принята):

{
  "event": "appeal_changed_status",
  "payment_id": 4897937,
  "merchant_id": "order382738",
  "appeal_id": 8239,
  "appeal_status": 1,
  "appeal_status_detail": "Approved",
  "trader_note": "Все в порядке",
  "updatedAt": "2025-05-05T15:45:42.079Z"
}

Callback апелляций

Статусы в callback appeal_changed_status:

Пример события appeal_changed_status (отклонена):

{
  "event": "appeal_changed_status",
  "payment_id": 4897937,
  "merchant_id": "order382738",
  "appeal_id": 8239,
  "appeal_status": 4,
  "appeal_status_detail": "Rejected",
  "trader_note": "Fake receipt. Transaction not found.",
  "updatedAt": "2025-05-05T15:45:42.079Z"
}

Пример события payout_reconciliation:

{
  "event": "payout_reconciliation",
  "request_payout_id": 12345,
  "shop_id": 111,
  "merchant_payout_id": "rp12345",
  "amount": 10000,
  "method": "card",
  "pan": "XXXXXXXXXXXXXXXX",
  "bank": "Сбербанк",
  "createdAt": "2025-05-05T15:45:42.079Z"
}

Подпись события (signature)

Для проверки целостности данных используется HMAC SHA256 с вашим секретным ключом из настроек проекта в ЛК.

Пример проверки подписи (Node.js):

const crypto = require("crypto");

const verifySignature = (data, signature, secretKey) => {
  const expected = crypto
    .createHmac("sha256", secretKey)
    .update(JSON.stringify(data))
    .digest("hex");
  return expected === signature;
};