Создание выплаты

POST/integration/payouts

Создаёт выплату в RUB с баланса мерчанта на заранее сохранённый кошелёк. Сумма блокируется на балансе и переводится получателю; финальный статус приходит вебхуком payout.status_updated.

Требуется подпись

Этот эндпоинт работает только с подписанными запросами(X-Api-Key + X-Timestamp + X-Signature). Обычного ключа недостаточно.

Breaking change: только wallet_uuid

Получатель выплаты теперь задаётся только через wallet_uuid. Поля destination, metadata и callback_url в теле запроса больше не поддерживаются — если прислать любое из них, запрос будет отклонён с 422.

Порядок работы: сначала создайте кошелёк для выплат в личном кабинете, затем передавайте его uuid в этом запросе. callback_url берётся из настроек мерчанта и должен использовать HTTPS.

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

Поле	Тип	Описание
`amount`обяз.	`integer`	Сумма в минорных единицах (копейки): `2500000` = 25 000,00 ₽. Минимум `1`.
`currency`обяз.	`string`	Валюта выплаты. Поддерживается только `RUB`.
`external_id`обяз.	`string`	Ваш идентификатор выплаты (до 255 символов). Обеспечивает идемпотентность.
`wallet_uuid`обяз.	`uuid`	UUID кошелька для выплат. Кошелёк создаётся заранее в личном кабинете и должен принадлежать вашему мерчанту. Сколько дойдёт до получателя, можно узнать заранее — предварительным расчётом.

Пример

201 Created

# Заголовки X-Timestamp и X-Signature — см. «Подписанные запросы»
curl -X POST https://api.cashera.cash/api/v1/integration/payouts \
  -H "X-Api-Key: $CASHERA_API_KEY" \
  -H "X-Timestamp: 1780000000" \
  -H "X-Signature: 4f3c2a...e91b" \
  -H "Content-Type: application/json" \
  -d '{
    "amount": 250000,
    "currency": "RUB",
    "external_id": "withdraw-001",
    "wallet_uuid": "b41f0c8e-3d55-4a17-9e02-7c6d1a8f4b30"
  }'

Баланс и блокировка

При создании выплаты сумма списывается с доступного баланса и блокируется до завершения. Если доступных средств недостаточно, вернётся 422. После статуса failedблокировка снимается и средства возвращаются в доступный баланс.

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

Повторный запрос с тем же external_id вернёт уже созданную выплату, а не создаст новую. При гонке запросов возможен ответ 409 Conflict — повторите запрос статуса.

Ошибки

Поле	Тип	Описание
`401`опц.	`Unauthorized`	Проблема с подписью или временем запроса.
`403`опц.	`Forbidden`	Мерчант отключён, баланс заморожен, IP не разрешён, не задан секрет, либо выплаты на карту не подключены.
`404`опц.	`Not Found`	Кошелёк из `wallet_uuid` не найден или принадлежит другому мерчанту.
`409`опц.	`Conflict`	Конфликт идемпотентности по `external_id`.
`422`опц.	`Unprocessable Entity`	Ошибка валидации, переданы запрещённые поля (`destination`, `metadata`, `callback_url`), в настройках мерчанта нет `callback_url` или он не HTTPS, валюта не RUB, недостаточно средств или превышены лимиты выплат на карту.
`429`опц.	`Too Many Requests`	Превышен лимит запросов к интеграционному API.