Перейти к содержанию

📦 Приём платежей — API документация

🔗 Метод запроса

POST /api/v2/payments/

📤 Параметры запроса (Request Body)

Параметр Обязат. Тип Описание
sum ✅ number Сумма платежа
type ✅ string Тип перевода: to_sbp_number, to_card_number, to_account_number, to_transgran_number, to_transgran_sbp, to_yandex_tips, nspk, to_mobile_commerce, to_quasi_ecom
bank ❌ string Запрашиваемый банк (Sber, Tinkoff, Alfa, Ozon, Vtb и т.д.)
is_intrabank_transfer ❌ boolean Внутрибанковский перевод (Озон→Озон, Альфа→Альфа, Сбер→Сбер)
client_id ❌ string ID клиента
outter_id ❌ string Внешний ID вашей системы
geo ❌ string Гео (Россия, Азербайджан, Казахстан, Узбекистан, Кыргызстан). По умолчанию: Россия
is_allow_another_amount ❌ boolean Разрешить клиенту менять сумму
callback_url ❌ string URL для отправки коллбеков

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

Статус Описание
created Заявка создана, ожидает оплаты
canceled Платёж отменён
refund Платёж возвращён
completed Платёж успешно завершён
deleted Платёж перевели в статус удалено

💳 Примеры запросов

1️⃣ Обычный платеж по SBP

Bash
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
curl -X POST "{{base_url}}/api/v2/payments/" \
  -H "Authorization: Token YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "sum": 1500,
    "type": "to_sbp_number",
    "bank": "Tinkoff",
    "client_id": "client_ABC123",
    "outter_id": "ORD-982134",
    "geo": "Россия",
    "is_allow_another_amount": true,
    "callback_url": "https://yourdomain.com/payment/callback"
  }'

✅ Пример успешного ответа (200 OK)

JSON
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
{
    "id": 10442449,
    "sum": "2500.00",
    "card_number": null,
    "created_at": "2025-11-27T14:01:26.617629+03:00",
    "updated_at": "2025-11-27T14:01:26.617639+03:00",
    "bank": "Alfa",
    "russified_name": "Альфа Банк",
    "bik": "044525593",
    "type": "to_sbp_number",
    "status": "created",
    "qr_code": null,
    "qr_code_link": null,
    "currency": "Рубль",
    "full_name": "Testov Tester Testik",
    "sbp_phone_number": "+79874563174",
    "client_id": "AC-551",
    "client_ip": null,
    "outter_id": "ACC-12345",
    "project": null,
    "merchant_payment_detail": {
        "id": 9336278,
        "course": "78.90",
        "rate": "0.00",
        "course_with_rate": "78.90",
        "amount_in_usdt": "31.6857",
        "accumulated_rate": "9.00",
        "amount_with_rate": "2275.0000",
        "amount_in_usdt_with_rate": "28.8340",
        "created_at": "2025-11-27T14:01:26.798306+03:00",
        "updated_at": "2025-11-27T14:01:26.798317+03:00"
    },
    "outter_id_from_form": null,
    "tips_id": null,
    "nspk_url": null,
    "work_country": "Россия",
    "redirect_url": null,
    "callback_url": null,
    "deeplink_url": "https://pay-dev.royalsfinance.app/deeplink/4f90b0cd-1d74-467f-8bdc-9ab1ef414814"
}

Описание полей ответа

Ниже приведено описание всех параметров, которые возвращаются при создании или получении платежа.

Основные поля платежа

Поле Тип Описание
id number Уникальный идентификатор платежа в системе.
sum string Сумма платежа
card_number string / null Номер карты, если используется банковская карта.
bank string Короткое название банка или платежного сервиса.
russified_name string Полное русское название банка.
bik string / null БИК банка,
type string Тип операции(выше был полный список)
status string Текущий статус платежа
qr_code string / null URL с изображением QR-кода
qr_code_link string / null URL с изображением QR-кода
currency string Валюта платежа. Например: "Рубль".
full_name string Полное имя создателя реквизита
sbp_phone_number string Телефон получателя для оплаты через СБП.
client_id string / null Идентификатор клиента
client_ip string / null IP-адрес клиента, который передали при создание платежа.
outter_id string / null Внешний ID транзакции от мерчанта
project string / null Идентификатор проекта мерчанта, внутри которого создан платеж.
outter_id_from_form string / null Внешний ID, переданный через форму (если используется форма оплаты).
tips_id number / null Идентификатор чаевых, если платеж включает tips.
nspk_url string / null Прямая ссылка НСПК на оплату
work_country string Страна, в которой обрабатывается платеж.
redirect_url string / null URL для перенаправления пользователя после оплаты.
callback_url string / null URL вашего сервера для получения callback-уведомлений.
deeplink_url string / null Ссылка-deeplink

Блок merchant_payment_detail

Этот объект содержит детальную информацию об обработке платежа со стороны мерчанта и конвертации валюты.

Поле Тип Описание
id number ID детали платежа.
course string Курс валюты
course_with_rate string Итоговый курс с учётом rate.
amount_in_usdt string Сумма в USDT.
accumulated_rate string Финальная ставка.
amount_with_rate string Сумма со ставкой.
amount_in_usdt_with_rate string Сумма со ставкой USDT.

2️⃣ Перевод на карту (to_card_number)

Bash
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
curl -X POST "{{base_url}}/api/v2/payments/" \
  -H "Authorization: Token YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "sum": 1800,
    "type": "to_card_number",
    "bank": "Sber",
    "client_id": "client_001",
    "outter_id": "CARD-99122",
    "geo": "Россия",
    "callback_url": "https://yourdomain.com/payment/callback"
  }'

Отличающее поле:

JSON
1
{ "card_number": "9999999999999999" }

3️⃣ Внутрибанковский перевод (Моно → Моно)

Bash
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
curl -X POST "{{base_url}}/api/v2/payments/" \
  -H "Authorization: Token YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "sum": 1000,
    "type": "to_sbp_number",
    "is_intrabank_transfer": true,
    "bank": "Alfa",
    "client_id": "client_ABC123",
    "outter_id": "ORD-982134",
    "geo": "Россия",
    "is_allow_another_amount": true,
    "callback_url": "https://yourdomain.com/payment/callback"
  }'

Вывод такой же, как при SBP.

4️⃣ Озон → Озон

Bash
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
curl -X POST "{{base_url}}/api/v2/payments/" \
  -H "Authorization: Token YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "sum": 500,
    "type": "to_card_number",
    "is_intrabank_transfer": true,
    "bank": "Ozon",
    "geo": "Россия",
    "outter_id": "OZ-55511",
    "client_id": "client_7721"
  }'

Вывод как у to_card_number.

5️⃣ Альфа → Альфа

Bash
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
curl -X POST "{{base_url}}/api/v2/payments/" \
  -H "Authorization: Token YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "sum": 2000,
    "type": "to_sbp_number",
    "is_intrabank_transfer": true,
    "bank": "Alfa",
    "client_id": "CL-992",
    "outter_id": "ORDER-ALFA-8844",
    "geo": "Россия"
  }'

Вывод как у SBP.

6️⃣ Перевод на банковский счет (to_account_number)

Bash
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
curl -X POST "{{base_url}}/api/v2/payments/" \
  -H "Authorization: Token YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "sum": 2500,
    "type": "to_account_number",
    "bank": "VTB",
    "client_id": "AC-551",
    "outter_id": "ACC-12345",
    "geo": "Россия"
  }'

Отличающее поле:

JSON
1
{ "account_number": "55555555555555555" }

7️⃣ Transgran по номеру (to_transgran_number)

Bash
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
curl -X POST "{{base_url}}/api/v2/payments/" \
  -H "Authorization: Token YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "sum": 3200,
    "type": "to_transgran_number",
    "client_id": "TG-202",
    "outter_id": "TG-REQ-882",
    "geo": "Азербайджан"
  }'

Вывод аналогичен to_card_number.

8️⃣ Transgran через SBP (to_transgran_sbp)

Bash
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
curl -X POST "{{base_url}}/api/v2/payments/" \
  -H "Authorization: Token YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "sum": 900,
    "type": "to_transgran_sbp",
    "client_id": "TG-SBP-77",
    "outter_id": "TG-SBP-REQ-994",
    "geo": "Казахстан"
  }'

Вывод как у SBP.

9️⃣ Yandex Tips (to_yandex_tips)

Bash
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
curl -X POST "{{base_url}}/api/v2/payments/" \
  -H "Authorization: Token YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "sum": 450,
    "type": "to_yandex_tips",
    "client_id": "YANDEX-TIPS-91",
    "outter_id": "TIPS-5521",
    "geo": "Россия",
    "callback_url": "https://yourdomain.com/payment/callback"
  }'

Отличающее поле:

JSON
1
2
3
4
5
{ "tips_id": "111111111111",
  "nspk_url": "https://qr.nspk.ru/csdl;jfcnsdkcjsdnfclsjfds",
  "sbp_phone_number": "+79874563174"

}

10 NSPK (QR-код)

Bash
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
curl -X POST "{{base_url}}/api/v2/payments/" \
  -H "Authorization: Token YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "sum": 1000,
    "type": "nspk",
    "client_id": "1234",
    "outter_id": "NSPK-001",
    "bank": "Alfa",
    "geo": "Россия",
    "callback_url": "https://yourdomain.com/payment/callback"
  }'

Отличающее поле:

JSON
1
2
3
{
  "qr_code": "https://rf-static.ams3.digitaloceanspaces.com/production/ams3/payment_qr_codes/BankCard_70301_qr.png"
}

1️⃣1️⃣ Мобильная коммерция (to_mobile_commerce)

Bash
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
curl -X POST "{{base_url}}/api/v2/payments/" \
  -H "Authorization: Token YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "sum": 300,
    "type": "to_mobile_commerce",
    "client_id": "MOB-22",
    "bank": "Alfa",
    "outter_id": "MOB-PAY-4411",
    "geo": "Россия"
  }'

Вывод аналогичен SBP.

1️⃣2️⃣ QR-нспк (with_qr_code)

Bash
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
curl -X POST "{{base_url}}/api/v2/payments/" \
  -H "Authorization: Token YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "sum": 300,
    "type": "with_qr_code",
    "client_id": "MOB-22",
    "bank": "Alfa",
    "outter_id": "MOB-PAY-4411",
    "geo": "Россия"
  }'

Отличающее поле:

JSON
1
2
3
4
{
    "qr_code_link": "https://qr_link.png",
    "account_number": "102267134323420005476"
}

1️⃣3️⃣ Запрос по монголии

Bash
1
2
3
4
5
6
7
8
9
curl -X POST "{{base_url}}/api/v2/payments/" \
  -H "Authorization: Token YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
        "sum": 10000,
        "type": "to_account_number",
        "geo": "Монголия"
    }
'

Ошибки

Код Ответ Причина
400 Bad Request Ошибка в теле запроса или отсутствуют обязательные параметры.
400 {"error": "No available cards.", "code": 40005} В данный момент нет доступных карт для приема платежа.
400 {"error": "Payment creation failed", "code": "30002"} Общая ошибка при создании платежа на сервере.
401 Unauthorized Неверные или отсутствующие учетные данные (Authorization Header).
403 {"error": {"code": 10401, "msg": "Учетные данные не были предоставлены.", ...}} Отсутствует или недействителен токен авторизации.
403 {"error": "Client is blocked. Reason: spam", "code": 50000} Аккаунт клиента заблокирован.
404 Not Found Ресурс не найден.
500 Internal Server Error Внутренняя ошибка сервера.
500 {"error": "Request timed out. The server took too long to respond.", "code": 50020} Таймаут запроса: сервер не успел обработать запрос вовремя.

Примечание о таймауте

Если запрос обрабатывается дольше установленного лимита (X-Request-Timeout), сервер вернёт ошибку с кодом 50020.