Payout

HTTP API

Прямой HTTP-контракт Payout API (Payment Easy).

HTTP API

Base URL: {baseUrl}/api/v1/payment-easy/{username}

Payout не использует JSON-конверт Payin Classic — транспорт XML, авторизация по RSA.

Краткая сводка по операциям

Метод	Тело запроса	Назначение
POST	`<request><balance /></request>`	Получить баланс
POST	`<request><payment .../></request>`	Создать выплату (карта или СБП)
POST	`<request><status id="..." /></request>`	Получить статус выплаты

Все три операции отправляются на один и тот же URL. Действие определяется корневым элементом в теле.

Заголовки и подпись

Заголовок	Что внутри
`Content-Type`	`application/xml`
`Signature`	RSA-подпись тела в base64 (PKCS#1 v1.5, SHA-1)

username идёт в URL, а не в заголовке. Key-Id в Payout не используется — идентификация по username + валидной подписи.

Алгоритм подписи

Возьмите тело запроса как есть (точные байты XML).
Посчитайте SHA-1.
Подпишите RSA приватным ключом в режиме PKCS#1 v1.5.
Закодируйте подпись в base64.
Положите в заголовок Signature.

Ответы сервера при наличии публичного ключа сервера подписываются тем же алгоритмом — заголовок Signature в ответе.

Ключи и формат PEM описаны в Ключи для Payout.

Операции

Баланс

Тело запроса:

<request><balance /></request>

Успешный ответ:

<response>
  <balance balance="1500000" overdraft="0" />
</response>

Также допустим «голый» вариант:

<balance balance="1500000" overdraft="0" />

Атрибут	Тип	Описание
`balance`	int64	Доступный баланс в копейках
`overdraft`	int64	Овердрафт в копейках

Ошибка:

<error>invalid signature</error>

Выплата

Тело запроса (карта):

<request>
  <payment id="unique-tx-id" sum="100000" service="24" account="4277255555555555" date="2026-04-24T12:00:00+0300">
    <attribute name="phone" value="79999999999" />
  </payment>
</request>

Тело запроса (СБП — по номеру телефона):

<request>
  <payment id="sbp-tx-id" sum="50000" service="26" account="79876543210" date="2026-04-24T12:00:00+0300">
    <attribute name="phone" value="79999999999" />
    <attribute name="payee_bank_code" value="100000000111" />
  </payment>
</request>

Атрибуты `<payment>`

Атрибут	Тип	Обяз.	Описание
`id`	string	да	Уникальный ID транзакции (до 64 байт)
`sum`	int64	да	Сумма в копейках
`service`	int	да	Тип сервиса (см. ниже)
`account`	string	да	Номер карты / телефона / кошелька
`date`	string	да	Дата транзакции в формате `2006-01-02T15:04:05-0700`

Вложенные `<attribute>`

`name`	Значение	Обяз.	Когда
`phone`	Телефон плательщика	да	Всегда
`payee_bank_code`	Код банка получателя	условно	Только для `service=26` (СБП)

Список кодов банков — см. bank_codes.go в SDK (238 банков).

Ответ — выплата в процессе (final="0" — статус ещё не финальный):

<response>
  <result id="unique-tx-id" code="1" state="40" final="0" trans="gateway-tx-id">
    <attribute name="fee" value="100" />
  </result>
</response>

Ответ — выплата завершена успешно (final="1"):

<response>
  <result id="unique-tx-id" code="0" state="60" final="1" trans="gateway-tx-id">
    <attribute name="fee" value="100" />
  </result>
</response>

Атрибут	Тип	Описание
`id`	string	Ваш ID транзакции
`code`	int	Код результата (см. Коды ошибок Payout)
`state`	int	Состояние платежа
`final`	int	`1` — финальный статус, `0` — ещё в процессе
`trans`	string	ID транзакции на стороне шлюза

Вложенные <attribute>:

`name`	Значение
`fee`	Комиссия в копейках (может отсутствовать)
`error-description`	Текст ошибки, если `code` указывает на сбой

Ошибка транспорта/подписи:

<error>signature verification failed</error>

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

Тело запроса:

<request><status id="unique-tx-id" /></request>

Ответ: тот же формат <response><result .../></response>, что и у выплаты.

Платёж опрашивается до тех пор, пока final не станет 1. Матрица финальных состояний — в Кодах ошибок Payout.

Сервисы (`service`)

Код	Название	Что в `account`
`24`	Банковские карты	Номер карты
`25`	Кошельки QIWI	Номер кошелька
`26`	СБП	Номер телефона получателя (+ `payee_bank_code`)
`28`	Мобильные телефоны	Номер телефона

Валюта и суммы

Валюта — всегда RUB.
sum передаётся в копейках (int64). Сумма 1000.00 ₽ → 100000.

Каскадное решение готово работать от 1 000 до 100 000 ₽ по СБП и по картам (т.е. sum от 100000 до 10000000 копеек). Можно зафиксировать любой более узкий диапазон под ваши процессы — согласуется с менеджером.

Webhooks

У Payout нет собственного webhook — отдельного URL для уведомлений о выплатах настроить нельзя. Получение статуса:

После создания выплаты (<request><payment .../></request>) опрашивайте <request><status id="..." /></request>.
Повторяйте, пока в ответе не появится final="1".
Финальный статус определяется по комбинации code / state (см. Коды ошибок Payout).

Тайминги и расписание

Параметр	Значение
Среднее время выплаты	~60 минут (от приёма заявки до финального статуса)
Расписание	Круглосуточно, 24/7 — отдельных банковских окон по умолчанию нет
Часовой пояс	МСК (UTC+3) — присылайте `date` с офсетом `+0300`

Гарантированный максимум по времени выплаты не фиксируется и зависит от загрузки каскада и ответа банка-эквайера. Для критичных кейсов согласуйте отдельные SLA с менеджером.

Идемпотентность

id — ваш уникальный идентификатор операции. Сервер ассоциирует его с конкретной выплатой.
Повторный вызов <payment> с тем же id не создаёт новую выплату — вернётся текущее состояние.
Для опроса статуса используйте <status>, а не повторную отправку <payment>.

SDK

Если не хотите собирать XML вручную, используйте официальные SDK: Go, Node.js, Python, PHP.

Обзор

Выплаты — SDK на Go, Node.js, Python, PHP.

Go-модуль для интеграции с Payment Easy Payout API.