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

Выплаты P2P

Общее описание

Система Royal Finance предоставляет API для выполнения выплат (payouts) с использованием P2P методов.

Доступные методы

Код (method) Описание
SBP СБП
INTERBANK Межбанк
ACCOUNT_NUMBER Номер Счета
SBER Сбер
TINKOFF Тинькофф

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

Код (status) Описание
pending в ожидании
in_progress в процессе
completed конечный статус (завершен)
wait_confirm ожидает подтверждения
failed_to_send_payout не удалось отправить КБ выплату
canceled конечный статус (отменен)

V3 — Callback-first (без подписи)

POST /api/v3/payouts/

V3 не требует подписи, но требует подтверждения через callback.

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

Для V3 требуется передача токена в заголовке:

HTTP
1
Authorization: Token YOUR_PAYOUT_TOKEN

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

Поле Тип Обязательный Описание
method string ✅ Метод перевода
requisite string ✅ Реквизиты получателя (например, номер телефона/карты/счета)
amount integer ✅ Сумма выплаты
bank string ⚠️ Обязателен для SBP

Пример запроса (cURL)

Bash
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
curl --location '{{base_url}}/api/v3/payouts/' \
--header 'Authorization: Token YOUR_PAYOUT_TOKEN' \
--header 'Content-Type: application/json' \
--data '{
  "method": "INTERBANK",
  "requisite": "2202206836681893",
  "bank": "Tinkoff",
  "amount": 5000,
  "outter_id": "f506f029-ea0f-4c6a-9d8f-98437de44909",
}'

Пример успешного ответа (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
{
  "id": 2688,
  "bank": "Tinkoff",
  "nspk_code": null,
  "requisite": "2202206836681893",
  "full_name": null,
  "method": "Межбанк",
  "amount": "5000.00",
  "currency": "RU",
  "project": null,
  "status": "wait_confirm",
  "outter_id": null,
  "created_at": "2025-05-06T13:30:50.334222+03:00",
  "updated_at": "2025-05-06T13:30:50.334236+03:00",
  "merchant_rate": "3.00",
  "requested_at": 1746527450,
  "merchant_payout_detail": {
    "id": 1138,
    "course": "102.00",
    "rate": "3.00",
    "amount_in_usdt": "49.0196",
    "amount_in_usdt_with_rate": "50.4902",
    "created_at": "2025-05-06T13:30:50.343952+03:00",
    "updated_at": "2025-05-06T13:30:50.343979+03:00"
  }
}

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

Поле Тип Описание
id integer Внутренний ID выплаты
bank string Название банка
nspk_code string / null Код НСПК, если применимо
requisite string Реквизиты получателя
full_name string / null ФИО получателя
method string Метод перевода
amount string Сумма выплаты
currency string Валюта выплаты
status string статус
outter_id string / null Внешний ID, переданный в запросе
created_at datetime Время создания
updated_at datetime Время последнего обновления
merchant_rate string Комиссия мерчанта (процент)
requested_at integer UNIX-время, переданное в запросе
merchant_payout_detail object Детали расчета комиссии и конвертации:
merchant_payout_detail.course string Курс конвертации
merchant_payout_detail.amount_in_usdt string Сумма выплаты до применения комиссии
merchant_payout_detail.amount_in_usdt_with_rate string Сумма списания с учетом комиссии

Возможные ошибки

Код Причина Описание ответа
401 Ошибка авторизации {"detail": "Authentication credentials were not provided."}
403 Несоответствие версий API {"detail": "API version mismatch. Please switch to 'v1=>v2' or 'v2=>v1' in the URL and try again."}
400 Отсутствует поле amount {"amount": ["Обязательное поле." ]}
400 Неверный тип amount {"amount": ["Amount must be an integer" ]}
400 Превышен лимит символов {"amount": ["Убедитесь, что вы ввели не более 10 цифры." ]}
400 Сумма вне допустимого диапазона {"amount": ["Amount is outside the allowable range" ]}
400 Превышен дневной лимит {"amount": ["Exceeds daily payout limit" ]}
400 Недостаточно средств {"amount": ["Insufficient funds to create a payout" ]}
400 Неверный метод выплаты {"method": ["'INTERBANKd' is invalid payout method provided." ]}
400 Отсутствует bank или nspk_code {"bank": ["Either 'bank' or 'nspk_code' must be provided." ]}
400 Общая ошибка системы {"non_field_errors": ["Currently unable to create a payout. Please contact support for more information." ]}
400 Не настроен Webhook URL {"non_field_errors": ["Webhook URL is not set. Please contact administrators." ]}

Преимущества v3:

  • ✅ Нет необходимости подписывать запросы
  • ✅ Устойчивость к прерыванию соединения
  • ✅ Активация происходит только после подтверждения callback’ом от клиента

📣 Чтобы подключить v3:

  • Предоставьте callback URL

Callback-процесс (v3)

  1. Вы отправляете запрос на выплату (POST /api/v3/payouts/)
  2. Мы отправляем webhook на ваш URL (запрос на подтверждение)
  3. Вы возвращаете 200 OK (подтверждение)
  4. Мы активируем выплату

Если необходимо, предоставим схему интеграции и шаблон callback-хука.