💸 Платежи и Заказы

API предоставляет методы для создания Ордеров и Платежей.

Базовый URL: https://page.royal-pay.cc

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

Поле status в ответе отражает текущее состояние платежа.

Статус	Значение	Описание
Создан	`created`	Платеж создан и ожидает оплаты.
Успешно	`completed`	Платеж успешно завершен.
Отменен	`canceled`	Платеж отменен (например, по таймауту).

1. 🧾 Создание Ордера

POST /api/v1/orders/

Создание предварительного ордера

Параметры запроса

Параметр	Тип/Расположение	Обязательный	Описание
`amount`	Body (number)	❌	Сумма заказа (напр., `1000.00`).
`outter_id`	Body (string)	✅	Ваш ID заказа во внешней системе.
`geo_id`	Body (integer)	❌	ID геолокации (по умолч. `1`).
`redirect_url`	Body (string)	✅	URL для редиректа (общий).
`success_redirect_url`	Body (string)	❌	URL при успешном завершении.
`fail_redirect_url`	Body (string)	❌	URL при ошибке.
`geo_name`	Body (string)	❌	Гео (`Россия`, `Азербайджан`, `Казахстан`, `Узбекистан`, `Кыргызстан`). По умолчанию: Россия

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

Bash
curl --location '{{base_url}}/api/v1/orders/' \
--header 'Authorization: Token <YOUR_API_KEY>' \
--header 'Content-Type: application/json' \
--data '{
    "amount": 1000.00,
    "outter_id": "1",
    "geo_id": 1,
    "redirect_url": "https://example.com/redirect",
    "success_redirect_url": "https://example.com/success",
    "fail_redirect_url": "https://example.com/fail",
    "geo_name": "Россия"
}'

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

JSON
{
    "amount": 1000.0,
    "outter_id": "1",
    "geo_id": 1,
    "redirect_url": "https://example.com/redirect",
    "success_redirect_url": "https://example.com/success",
    "fail_redirect_url": "https://example.com/fail",
    "merchant_id": 703,
    "merchant_token": "37067033d802d73a7d0b7bf3a83bb06e66553241",
    "order_id": "157d4b8e-d678-4daf-926a-0ec30edf3cce",
    "link": "https://page-dev.royalsfinance.app/order/157d4b8e-d678-4daf-926a-0ec30edf3cce"
}

Ошибки

Код	Ответ (Схема)	Причина
400	`ClientErrorResponseModel`	Некорректный запрос.
401	`ClientErrorResponseModel`	Ошибка авторизации.
422	`HTTPValidationError`	Ошибка валидации полей.
500	`ClientErrorResponseModel`	Внутренняя ошибка сервера.

2. 💳 Создание Внешнего Платежа

POST /api/v1/payments/

Создает платежа

Параметры запроса

Параметр	Тип/Расположение	Обязательный	Описание
`amount`	Body (number)	✅	Сумма перевода.
`transfer_method`	Body (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`
`redirect_url`	Body (string)	✅	URL для редиректа (общий).
`callback_url`	Body (string)	❌	URL для веб-хука при успехе.
`geo`	Body (string)	❌	Гео (`Россия`, `Азербайджан`, `Казахстан`, `Узбекистан`, `Кыргызстан`). По умолчанию: Россия
`outter_id`	Body (string)	❌	Ваш ID платежа во внешней системе.
`bank`	Body (string)	❌	Название банка (напр., "Sber").

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

Bash
curl --location '{{base_url}}/api/v1/payments/' \
--header 'Authorization: Token <YOUR_API_KEY>' \
--header 'Content-Type: application/json' \
--data '{
    "outter_id": "1",
    "bank": "Sber",
    "amount": 500.00,
    "transfer_method": "to_card_number",
    "client_id": "1",
    "geo": "Россия",
    "redirect_url": "https://example.com/redirect",
    "success_redirect_url": "https://example.com/success",
    "fail_redirect_url": "https://example.com/fail",
    "callback_url": "https://example.com/callback"
}'

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

JSON
{
    "bank": "Alfa",
    "sum": 2000.0,
    "transfer_method": "to_card_number",
    "status": "created",
    "full_name": "Test Card Q",
    "card_number": "7777444411117777",
    "sbp_phone_number": null,
    "account_number": null,
    "has_appeal": false,
    "is_canceled": false,
    "payment_gateway_id": 10442279,
    "payment_id": "f16f06b2-fa21-4e34-a0bd-0a3178caf08f",
    "order_id": "f16f06b2-fa21-4e34-a0bd-0a3178caf08f",
    "outter_id": "1",
    "geo_id": 1,
    "redirect_url": "https://example.com/redirect",
    "success_redirect_url": "https://example.com/success",
    "fail_redirect_url": "https://example.com/fail",
    "lifetime": null,
    "prev_sum": 2000.0,
    "donation_url": null,
    "tpay_link": null,
    "qr_code": "https://rf-static.ams3.digitaloceanspaces.com/development/ams3/payment_qr_codes/BankCard_19292_qr.png",
    "work_country": "Россия",
    "link": "https://page-dev.royalsfinance.app/payment/f16f06b2-fa21-4e34-a0bd-0a3178caf08f"
}

Ошибки

Код	Ответ (Схема)	Причина
400	`NoAvailableCardsResponseModel`	Нет доступных карт.
401	`UnauthorizedResponseModel`	Ошибка авторизации.
422	`HTTPValidationError`	Ошибка валидации полей.
500	`InternalServerErrorResponseModel`	Внутренняя ошибка сервера.

3. 💳 Создание Внутреннего Платежа

POST /api/v1/payments/internal/

Создает внутреннего платежа

Параметры запроса

Параметр	Тип/Расположение	Обязательный	Описание
`Authorization`	Header	✅	Ваш API-ключ.
`Content-Type`	Header	✅	`application/json`
`order_id`	Body (string)	✅	UUID Заказа.
`geo_id`	Body (integer)	❌	ID геолокации (по умолч. `1`).
`amount`	Body (number)	✅	Сумма перевода.
`transfer_method`	Body (string)	✅	Метод (напр., `to_card_number`).
`client_id`	Body (string)	✅	ID клиента.
`client_ip`	Body (string)	✅	IP клиента.
`bank`	Body (string)	❌	Название банка (напр., "Sber").
`callback_url`	Body (string)	❌	URL для веб-хука при успехе.

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

Bash
curl --location '{{base_url}}/api/v1/payments/internal/' \
--header 'Authorization: Token <YOUR_API_KEY>' \
--header 'Content-Type: application/json' \
--data '{
    "order_id": "9e4e1406-b431-4d67-8559-e90371772abb",
    "geo_id": 1,
    "bank": "Sber",
    "amount": 500.00,
    "transfer_method": "to_card_number",
    "client_id": "1",
    "client_ip": "127.0.0.1",
    "callback_url": "https://example.com/callback"
}'

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

JSON
{
    "bank": null,
    "sum": 2000.0,
    "transfer_method": null,
    "status": "created",
    "full_name": null,
    "card_number": null,
    "sbp_phone_number": null,
    "account_number": null,
    "has_appeal": null,
    "is_canceled": null,
    "payment_gateway_id": null,
    "payment_id": "f16f06b2-fa21-4e34-a0bd-0a3178caf08f",
    "order_id": "f16f06b2-fa21-4e34-a0bd-0a3178caf08f",
    "outter_id": null,
    "geo_id": null,
    "redirect_url": "https://page-dev.royalsfinance.app/payment/f16f06b2-fa21-4e34-a0bd-0a3178caf08f",
    "success_redirect_url": "https://example.com/success",
    "fail_redirect_url": "https://example.com/fail",
    "lifetime": null,
    "prev_sum": null,
    "donation_url": null,
    "tpay_link": null,
    "qr_code": null,
    "work_country": "Россия",
    "link": "https://page-dev.royalsfinance.app/payment/f16f06b2-fa21-4e34-a0bd-0a3178caf08f"
}

Ошибки

Код	Ответ (Схема)	Причина
400	`NoAvailableCardsResponseModel`	Нет доступных карт.
401	`InvalidTokenResponseModel`	Неверный токен (ошибка авторизации).
422	`HTTPValidationError`	Ошибка валидации полей.
500	`InternalServerErrorResponseModel`	Внутренняя ошибка сервера.

4. 📄 Получение Ордера по ID

GET /api/v1/orders/{order_id}/

Параметры запроса

Параметр	Тип	Обязательный	Описание
`order_id`	UUID	✅	UUID Заказа для получения.

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

Bash
curl --location '{{base_url}}/api/v1/orders/9e4e1406-b431-4d67-8559-e90371772abb/'

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

JSON
{
  "amount": 1000,
  "outter_id": "1",
  "geo_id": 1,
  "redirect_url": "https://example.com/redirect",
  "success_redirect_url": "https://example.com/success",
  "fail_redirect_url": "https://example.com/fail",
  "order_id": "9e4e1406-b431-4d67-8559-e90371772abb",
  "merchant_id": 1,
  "merchant_token": "string",
  "has_payment": true,
  "created_at": "2025-10-02T10:07:22.398831",
  "updated_at": "2025-10-02T10:07:22.398857"
}

Ошибки

Код	Ответ (Схема)	Причина
404	`ClientErrorResponseModel`	Заказ не найден.
422	`HTTPValidationError`	Ошибка валидации (неверный UUID).
500	`ClientErrorResponseModel`	Внутренняя ошибка сервера.

5. 📄 Получение Платежа по ID Ордера

GET /api/v1/payments/check-by-order-id/{order_id}/

Получает информацию о Платеже, используя order_id Ордера, к которому он привязан.

Параметры запроса

Параметр	Тип/Расположение	Обязательный	Описание
`order_id`	Path	✅	UUID Заказа, по которому ищется платеж.

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

Bash
curl --location '{{base_url}}/api/v1/payments/check-by-order-id/9e4e1406-b431-4d67-8559-e90371772abb/'

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

Ответ содержит полную информацию о платеже (PaymentResponseSchema).

JSON
{
  "bank": "Sber",
  "amount": 500,
  "transfer_method": "to_card_number",
  "status": "success",
  "full_name": "Ivanov Ivan Ivanovich",
  "card_number": "2202 ...",
  "payment_id": "a1b2c3d4-ef87-47bc-a271-cc0aa1419c21",
  "order_id": "9e4e1406-b431-4d67-8559-e90371772abb",
  "link": "https://page.royal-pay.cc/payment-form/a1b2c3d4-ef87-47bc-a271-cc0aa1419c21"
}

Ошибки

Код	Ответ (Схема)	Причина
401	`IncorrectRecaptchaResponseModel`	Некорректная recaptcha.
422	`HTTPValidationError`	Ошибка валидации (неверный UUID).
500	`InternalServerErrorResponseModel`	Внутренняя ошибка сервера.

📘 Словарь Полей

Ниже приведены описания ВСЕХ полей, встречающихся в отвеы: Ордеров, Платежей, Деталей платежей и вспомогательных сущностей.

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

🧱 1. Общие поля сущностей

🧩 Идентификаторы

Поле	Тип	Описание
id	number/string	Уникальный идентификатор объекта в системе (числовой или UUID — зависит от сущности).
order_id	UUID	Идентификатор созданного ордера. Используется для привязки платежей.
payment_id	UUID	Идентификатор созданного платежа.
payment_gateway_id	number / null	Внутренний ID процессинга, использованного для платежа.
bank_card	number	ID банковской карты, выбранной системой для списания.
payment	number	ID платежа (внутренний), к которому относится запись движения средств.
outter_id	string / null	Ваш внешний ID заказа/платежа — позволяет связать транзакцию с вашей системой.
outter_id_from_form	string / null	Внешний ID, который пришёл с пользовательской формы.
tips_id	number / null	ID записи в системе чаевых (если используется).
geo_id	number	ID геолокации/страны, влияющий на доступные методы оплаты.
merchant_id	number	ID мерчанта, от имени которого создавалась операция.
merchant_token	string	Токен мерчанта, связанный с текущим ордером.

📅 2. Даты и время

Поле	Тип	Описание
created_at	datetime	Время создания объекта.
updated_at	datetime	Время последнего обновления объекта.
lifetime	number / null	Время жизни платежа (TTL) в секундах. Может отсутствовать.

💰 3. Финансовые поля

Основные суммы

Поле	Тип	Описание
amount / sum	number / string	Сумма платежа или заказа. Используется в запросах.
prev_sum	number / null	Предыдущая сумма (если происходила корректировка).
amount_with_rate	string	Сумма с учётом комиссий мерчанта.
amount_in_usdt	string	Конвертированная сумма в USDT по курсу.
amount_in_usdt_with_rate	string	Конвертация в USDT с учётом комиссий.

Курсы и комиссии

Эти поля принадлежат объекту merchant_payment_detail.

Поле	Тип	Описание
course	string	Базовый курс валюты на момент операции.
rate	string	Комиссия мерчанта. Часто процент.
course_with_rate	string	Итоговый курс после применения комиссии.
accumulated_rate	string	Финальная ставка.

🏦 4. Банковские данные

Поле	Тип	Описание
bank	string / null	Название банка, участвующего в оплате (напр., `"Sber"`, `"Alfa"`).
russified_name	string / null	Полное русское название банка.
bik	string / null	БИК банка (для банковских переводов).
card_number	string / null	Маскированный номер карты получателя.
account_number	string / null	Номер банковского счета.
sbp_phone_number	string / null	Номер телефона для перевода через СБП.
transfer_method	string	Метод перевода (напр., `to_card_number`, `to_sbp_number`).

📝 5. Статусные поля

Поле	Тип	значения	Описание
status	string	выше написаны	Финальный статус сущности (платёж, ордер, запись по карте).
has_appeal	bool	true/false	Есть ли открытая апелляция по платежу.
is_canceled	bool	true/false	Был ли платеж отменён системой или пользователем.
has_payment	bool	true/false	Привязан ли к ордеру платеж.

🌍 6. Локация и клиент

Поле	Тип	Описание
geo / geo_name	string	Название географической зоны (например, “Россия”).
work_country	string	Страна, в которой выполнялась операция.
client_id	string / null	Идентификатор клиента
client_ip	string / null	IP адрес клиента, инициировавшего оплату.

🔗 7. Ссылки и URL

Поле	Тип	Описание
redirect_url	string	URL, куда пользователь отправляется после оплаты.
success_redirect_url	string	URL при успешной оплате.
fail_redirect_url	string	URL при ошибке/отмене.
callback_url	string / null	URL, куда отправляется веб-хук при завершении платежа.
link	string	Прямая ссылка на страницу оплаты/ордера.
deeplink_url	string / null	Глубокая ссылка для открытия банковского приложения.
tpay_link	string / null	Ссылка на альтернативный платёжный шлюз (если используется).
nspk_url	string / null	Прямая ссылка НСПК для оплаты через СБП.
qr_code	string / null	Ссылка на QR-код.
donation_url	string / null	Ссылка для донатов (при использовании donation-режима).