Выводы

Заявки на вывод средств с баланса аккаунта: на СБП по номеру телефона или на USDT (TRC20 / BEP20). Вывод возможен только на реквизиты, добавленные в кабинете и подтверждённые по письму — свободный ввод реквизитов через API не принимается.

API v1 · обновлено 2026-09-12

Как это работает

В кабинете (раздел «Выводы») мерчант добавляет реквизит — номер телефона для СБП или адрес USDT. На почту приходит письмо «Подтвердите реквизит для вывода»; до подтверждения выводить на него нельзя.
Через API вы получаете список подтверждённых реквизитов (GET /payout-addresses) и создаёте заявку POST /payouts с addressId.
Сумма заявки резервируется на балансе (available → pending). Заявку проверяет финансовая служба; выплата обычно уходит в течение одного рабочего дня, USDT — по курсу на момент создания заявки.
Итог приходит вебхуком payout.paid или payout.rejected (если подписаны) и виден в GET /payouts/{id}. При отказе сумма возвращается в available.

Заявки создаются только живым ключом sk_live_: по тестовому ключу POST /payouts отвечает 403 test_mode. Одновременно в обработке может быть не более трёх заявок.

GET /payout-addresses — подтверждённые реквизиты

Поле	Описание
`id`	Идентификатор реквизита — передаётся в `POST /payouts` как `addressId`.
`method`	`sbp` · `usdt_trc20` · `usdt_bep20`.
`account`	Телефон или адрес кошелька — в API всегда замаскирован.
`bank`	Банк получателя (только СБП).
`label`	Название, заданное в кабинете.

Добавить или удалить реквизит через API нельзя — только в кабинете, с подтверждением по почте. Это защита баланса: утёкший API-ключ не позволит вывести деньги на чужой кошелёк.

POST /payouts — создать заявку

Поля запроса

Поле	Тип	Описание
`amount`	string \| number	Сумма в рублях, списывается с `available`. Не меньше минимума вывода (см. Тарифы); комиссия за вывод вычитается из суммы.
`addressId`	integer	Подтверждённый реквизит из `GET /payout-addresses`. Обязателен, если не передана пара `method` + `account`.
`method`, `account`	string	Альтернатива `addressId`: способ и полный телефон/адрес. Принимается только если такой реквизит уже добавлен и подтверждён в кабинете, иначе `422 address_not_confirmed`.
`orderId`	string ≤ 128	Ваш идентификатор заявки — ключ идемпотентности. Повтор с тем же `orderId` возвращает существующую заявку с кодом 200, вторая заявка не создаётся.
`comment`	string ≤ 500	Заметка для себя; видна в кабинете.

Ответ

Поле	Описание
`status`	`pending` → `approved` → `processing` → `paid`; либо `rejected` (отказ, сумма вернулась на баланс) или `cancelled` (отменена мерчантом в кабинете, пока была `pending`).
`amount`, `feeAmount`, `netAmount`	Списано с баланса · комиссия за вывод · отправлено получателю (`amount − feeAmount`).
`usdtAmount`, `usdtRate`	Только для USDT: сколько уйдёт на кошелёк и по какому курсу (₽ за 1 USDT). Фиксируются при создании заявки.
`externalId`	Идентификатор перевода после выплаты: хеш транзакции для USDT, номер операции для СБП.
`statusReason`	Причина отказа / отмены.
`source`	`api` · `manual` (кабинет) · `auto` (автовывод).

GET /payouts/{id} — статус заявки

Опрос одной заявки — не чаще раза в 3 секунды (иначе 429 с Retry-After). Для уведомлений используйте вебхуки.

GET /payouts — список

Параметр	Описание
`orderId`	Одна заявка по вашему идентификатору (ответ — объект, не список).
`status`	Фильтр по статусу.
`limit`	1…100, по умолчанию 20.
`cursor`	`nextCursor` из предыдущего ответа. Список идёт от новых к старым.

Вебхуки payout.paid / payout.rejected

События выводов отправляются на webhook_url каждого проекта аккаунта, у которого они включены в настройках вебхуков (по умолчанию — включены все события). Конверт и подпись — как у счетов (Вебхуки), в data лежит объект payout в том же виде, что и в GET /payouts/{id}.

Автовывод

В кабинете можно включить автовывод: когда доступный баланс достигает порога (в USDT для крипто-реквизитов, в рублях для СБП), Payra сам создаёт заявку на вывод всей доступной суммы — не чаще выбранного интервала. Такие заявки приходят в API и вебхуках с source: "auto". Курс USDT для порога и для суммы заявки берётся у платёжного провайдера и обновляется каждые 10 минут.

Ошибки

HTTP	`code`	Когда
400	`validation`	Нет `addressId` и пары `method` + `account`, некорректная сумма, неизвестный `cursor`.
403	`test_mode`	Тестовый ключ: выводы только по `sk_live_`.
404	`address_not_found` / `not_found`	Реквизит или заявка не принадлежат аккаунту.
409	`too_many_pending`	Уже три заявки в обработке.
409	`duplicate_request`	Заявка без `orderId` с той же суммой и реквизитом уже создана меньше минуты назад. Передавайте `orderId`, если это отдельный вывод.
422	`address_not_confirmed`	Реквизит ещё не подтверждён по письму или не добавлен в кабинете.
422	`min_amount`	Сумма меньше минимума вывода или комиссия съедает её целиком.
422	`insufficient_funds`	Сумма больше доступного баланса.
422	`method_unavailable`	Способ вывода временно отключён.
422	`rate_unavailable`	Курс USDT недоступен — попробуйте позже.