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

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

POST /api/v2/payments/

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

Параметр	Обязат.	Тип	Описание
`sum`	✅	number	Сумма платежа
`type`	✅	string	Тип перевода: `to_sbp_number`, `to_card_number`, `to_account_number`, `to_account_number_qr`, `to_transgran_number`, `to_transgran_sbp`, `to_yandex_tips`, `nspk`, `to_mobile_commerce`, `to_quasi_ecom`, `to_bt_sbp`, `to_bt_card_number`, `to_donation_url`
`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`	Заявка создана, ожидает оплаты
`failed`	Платёж отменён
`refund`	Платёж возвращён
`success`	Платёж успешно завершён
`deleted`	Платёж перевели в статус удалено

Дополнительные antifraud-поля

Следующие поля используются для антифрод-проверок. Если данный функционал включён (default=false), эти поля становятся обязательными:

Поле	Тип	Описание
`client_id`	`string`	Идентификатор клиента
`client_ip`	`string`	IP-адрес клиента
`device_type`	`string`	Тип устройства: `mobile` или `pc`
`os`	`string`	Операционная система устройства
`browser`	`string`	Браузер клиента
`vpn`	`boolean`	Признак использования VPN: `true` / `false`
---

⏱️ Время жизни заявки (TTL)

Заявки на приём средств имеют ограниченное время жизни.

Если заявка не была оплачена до истечения TTL, её статус автоматически изменяется на failed.
TTL по умолчанию — 7 минут.

Таблица методов оплаты

Метод (`type`)	Название	Краткое описание
`to_sbp_number`	Оплата по СБП	Стандартный приём платежа по номеру телефона через СБП.
`to_card_number`	Оплата на карту	Приём платежа по реквизитам банковской карты.
`to_account_number`	Оплата на банковский счёт	Приём платежа по номеру банковского счёта.
`to_account_number_qr`	Transgran Вьетнам	Трансграничный платёж для Вьетнама с возвратом `qr_code_link` в response body.
`to_transgran_number`	Transgran по номеру	Трансграничный перевод по номеру без указания `geo`.
`to_transgran_sbp`	Transgran по СБП	Трансграничный перевод через СБП без указания `geo`.
`to_yandex_tips`	Yandex Tips	Метод оплаты с возвратом данных для чаевых, включая `tips_id`, `nspk_url` и `sbp_phone_number`.
`nspk`	NSPK (QR-код)	Метод оплаты через НСПК с возвратом QR-кода или ссылки на оплату.
`to_mobile_commerce`	Мобильная коммерция	Приём платежа через сценарий мобильной коммерции, вывод аналогичен SBP.
`with_qr_code`	QR-НСПК	Метод оплаты с возвратом `qr_code_link` и `account_number`.
`to_donation_url`	Пожертвования	Метод оплаты пожертвования с возвратом ссылки `donation_url`.
`to_bt_sbp`	Белый Треугольник СБП	Метод оплаты, в ответе которого возвращается `sbp_phone_number`.
`to_bt_card_number`	Белый Треугольник Карта	Метод оплаты, в ответе которого возвращается `card_number`.

Дополнительные сценарии

Поля	Сценарий	Описание
`is_intrabank_transfer=true`	Внутрибанковский перевод	Используется для переводов внутри одного банка, например Альфа→Альфа, Озон→Озон, Сбер→Сбер.

✅ Обычный платеж по SBP

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

🔄 Опрос статуса заявки (Polling)

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

Bash
curl "{{base_url}}/api/v2/payments/{{Our-Payment-ID}}" 

polling используется как дополнение к callback, а не как его полная замена.

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

Отмена платежа доступна только в том случае, если платеж находится в статусе «Создан». Для отмены платежа необходимо отправить DELETE запрос на урл

Bash
curl -X DELETE "{{url}}/api/v2/payments/{{our_id}}" \
  -H "Authorization: Token YOUR_TOKEN"

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

Bash
curl --location '{{base_url}}/api/v1/payments/' \
--header 'Authorization: Token <YOUR_API_KEY>' \
--header 'Content-Type: application/json' \
--data '{
    "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",
    "client_id": "1",
    "client_ip": "192.168.1.1",
    "device_type": "mobile",
    "os": "iOS",
    "browser": "Safari",
    "vpn": true,
    "geo": "Россия"
}`

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

JSON
{
    "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://prod.royalfin.app/deeplink/4f93b0cd-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
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
{ "card_number": "9999999999999999" }

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

Bash
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
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
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
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": "Россия"
  }'

8️⃣ Перевод на банковский счёт с выводом QR-кода (`to_account_number`)

Метод предназначен для перевода средств на банковский счёт с возможностью получения QR-кода для оплаты.

⚠️ Ограничение: На данный момент метод поддерживается только банком Alfa.

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

Bash
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": "Alfa",
    "client_id": "AC-551",
    "outter_id": "ACC-12345",
    "geo": "Россия"
  }'

Ответ

В ответе может присутствовать только одно из полей, связанных с QR-кодом:

qr_code — прямая ссылка на изображение QR-кода
qr_code_link — ссылка на страницу с QR-кодом

❗ Важно: Если поле qr_code заполнено, то qr_code_link(пример: https://link.api.m10.az/cEXRgxicnafV8wvT1234") будет иметь значение null, и наоборот.

JSON
{
  "qr_code": "https://rf-static.ams3.digitaloceanspaces.com/development/ams3/payment_qr_codes/full-shot-ninja-wearing-equipment_1.jpg",
  "qr_code_link": null,
  "account_number": "55555555555555555"
}

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

Для трансграна гео не указывается

Если дополнительное поле work_country не указано, система автоматически выдаст свободный трансгран.
Если поле передано, подбор будет выполнен с учетом указанной страны.

Bash
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",
  }'

9️⃣ Transgran Вьетнам

Bash
curl -X POST "{{base_url}}/api/v2/payments/" \
  -H "Authorization: Token YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "sum": 8614,
    "type": "to_account_number_qr",
    "geo": "Россия"
  }
  '

Поле, по которому различается response body

JSON
{ "qr_code_link": "https://pay-service.online/pays/NjkwMjY2OWJlZaUxMTbiZWI1YjFkMmU0OjY5YmE5NjdiODQ3YjBjNmE4NjM0NmI4ZA/3433956-dd6ae425-dbd4-49e0-84bd-58e53adf156e.png" }

🔟 Transgran по СБП (`to_transgran_sbp`)

Для трансграна гео не указывается

Если дополнительное поле work_country не указано, система автоматически выдаст свободный трансгран.
Если поле передано, подбор будет выполнен с учетом указанной страны.

Bash
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",
  }'

Вывод как у SBP.

1️⃣1️⃣ Yandex Tips (`to_yandex_tips`)

Bash
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
{ "tips_id": "111111111111",
  "nspk_url": "https://qr.nspk.ru/csdl;jfcnsdkcjsdnfclsjfds",
  "sbp_phone_number": "+79874563174"

}

1️⃣2️⃣ NSPK (QR-код)

Bash
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
{
  "qr_code": "https://rf-static.ams3.digitaloceanspaces.com/production/ams3/payment_qr_codes/BankCard_70301_qr.png"
}

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

Bash
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️⃣4️⃣ QR-нспк (`with_qr_code`)

Bash
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
{
  "qr_code_link": "https://qr_link.png",
  "account_number": "102267134323420005476"
}

1️⃣5️⃣ NSPK (`nspk`) — оплата через форму

Данный метод оплаты возвращает ссылку на форму NSPK, где клиенту необходимо ввести паспортные данные для завершения платежа.

⚠️ Важные моменты

Поле client_id обязательно — без него метод не будет работать.
Перед интеграцией необходимо согласовать с бизнесом, что используется именно этот способ оплаты (nspk с формой).
Клиент завершает оплату по ссылке, которую вы получаете в ответе.

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

Bash
curl -X POST "{{base_url}}/api/v2/payments/" \
  -H "Authorization: Token YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "sum": 300,
    "type": "nspk",
    "client_id": "MOB-22",
    "bank": "Alfa", # Можно не передавать банк тогда выдаст любой доступный
    "outter_id": "MOB-PAY-4411",
    "geo": "Россия"
  }'

В ответе вы получите ссылку на форму NSPK:

JSON
{
  "nspk_url": "https://link.com"
}

🔗 Что делать дальше

Передайте значение nspk_url клиенту и перенаправьте его на эту страницу для ввода паспортных данных и завершения платежа.

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

Bash
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": "Монголия"
    }
'

1️⃣6️⃣ Пожертвования

Bash
curl -X POST "{{base_url}}/api/v2/payments/" \
  -H "Authorization: Token YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "sum": 1000
    "type": "to_donation_url"
    "bank": "Sber" # Пока что доступен только Сбер
    "is_intrabank_transfer": true
    }
'

В ответе вы получите ссылку оплаты пожертвования:

JSON
{
     "donation_url": "https://test.com"
}

1️⃣7️⃣ БТ СБП

Bash
curl -X POST "{{base_url}}/api/v2/payments/" \
  -H "Authorization: Token YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "sum": 1000
    "type": "to_bt_sbp"
    "client_id": "MOB-22",
    "bank": "Alfa", 
    "outter_id": "MOB-PAY-4411",
    }
'

В ответе вы получите номер карты:

JSON
{
     "sbp_phone_number": "+7-213-123-123"
}

1️⃣8️⃣ БТ Карта

Bash
curl -X POST "{{base_url}}/api/v2/payments/" \
  -H "Authorization: Token YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "sum": 1000
    "type": "to_bt_card_number"
    "client_id": "MOB-22",
    "bank": "Alfa", 
    "outter_id": "MOB-PAY-4411",
    }
'

В ответе вы получите номер телефона:

JSON
{
     "card_number": "123456789"
}

Ошибки

Код	Ответ	Причина
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.

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

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

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

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

Дополнительные antifraud-поля

⏱️ Время жизни заявки (TTL)

Таблица методов оплаты

Дополнительные сценарии

✅ Обычный платеж по SBP

🔄 Опрос статуса заявки (Polling)

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

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

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

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

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

Блок merchant_payment_detail

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

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

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

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

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

8️⃣ Перевод на банковский счёт с выводом QR-кода (to_account_number)

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

Ответ

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

9️⃣ Transgran Вьетнам

🔟 Transgran по СБП (to_transgran_sbp)

1️⃣1️⃣ Yandex Tips (to_yandex_tips)

1️⃣2️⃣ NSPK (QR-код)

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

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

1️⃣5️⃣ NSPK (nspk) — оплата через форму

⚠️ Важные моменты

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

🔗 Что делать дальше

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

1️⃣6️⃣ Пожертвования

1️⃣7️⃣ БТ СБП

1️⃣8️⃣ БТ Карта

Ошибки

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

Блок `merchant_payment_detail`

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

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

8️⃣ Перевод на банковский счёт с выводом QR-кода (`to_account_number`)

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

🔟 Transgran по СБП (`to_transgran_sbp`)

1️⃣1️⃣ Yandex Tips (`to_yandex_tips`)

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

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

1️⃣5️⃣ NSPK (`nspk`) — оплата через форму