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"
}

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

Апелляции

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

• Первичные — время на разрешение диспута 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"
}

Пример события 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;
};