Выплаты (Pay-Out)

Pay-Out — вывод средств с баланса кабинета на реквизиты получателя. В отличие от Pay-In, реквизиты передаёте вы: платформа находит исполнителя, который переведёт деньги, и подтверждает результат.

Сумма списывается с баланса в USDT по курсу, зафиксированному при создании заявки.

Как проходит выплата

1. Вы вызываете POST /payment/pay-out с суммой и реквизитами получателя.
2. Заявка принимается в статусе pending и встаёт в очередь.
3. Исполнитель берёт её в работу — статус меняется на active.
4. Деньги уходят получателю, заявка закрывается как success.

На каждом переходе приходит webhook. Перечень статусов — в разделе Статусы сделок.

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

POST /payment/pay-out HTTP/1.1
Host: https://svc.cashwell.io
Content-Type: application/json
X-Secure-Key: <ваш API-ключ>

{
  "amount": 10000,
  "merchantTransactionId": "payout-2001",
  "callbackUrl": "https://example.com/callback",
  "timeoutInMin": 60,
  "requisite": {
    "sbpNumber": "79123215109",
    "bank": "SBER",
    "ownerName": "Иван Иванов"
  }
}

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

Поле	Тип	Обяз.	Описание
amount	number	да	Сумма в фиатной валюте, от 100 до 1 000 000
merchantTransactionId	string	да	Ваш идентификатор операции. Должен быть уникален в рамках кабинета
requisite	object	да	Реквизиты получателя — см. ниже
currency	string	нет	Фиатная валюта операции. По умолчанию — валюта кабинета
callbackUrl	string	нет	Адрес для webhook по этой выплате
timeoutInMin	number	нет	Через сколько минут отменить заявку, если её не взяли в работу. От 1 до 1440
payerInfo	object	нет	Данные получателя в вашей системе
isMatching	boolean	нет	Создать не выплату, а matching-заявку — см. Matching
matchingTransactionId	string	нет	Внешний идентификатор matching-заявки

Реквизиты получателя

В объекте requisite передаётся один платёжный идентификатор — он и определяет способ перевода.

Поле	Описание
sbpNumber	Номер телефона для перевода по СБП
cardNumber	Номер банковской карты, 14–18 цифр
ostCardNumber	Номер карты для перевода по каналу OST C2C
qrCode	QR-ссылка или строка QR для оплаты
bank	Банк получателя
ownerName	Имя владельца платёжного средства

Осторожно

Проверяйте реквизиты до отправки запроса. Заявка с неверными данными пройдёт валидацию формата, дойдёт до исполнителя и вернётся как canceled с cancelReason: "WRONG_REQUISITE" — потратив время окна выплаты. Для карт проверяйте длину и контрольную сумму, для СБП — формат номера.

Если на балансе не хватает средств, заявка не создаётся: запрос вернёт 403 INSUFFICIENT_FUNDS. Текущий баланс — методом «Баланс кабинета».

Тайм-аут заявки

timeoutInMin задаёт, сколько заявка ждёт исполнителя, прежде чем будет отменена автоматически. Значение приходит обратно в поле paymentLifetime.

Отсчёт идёт до момента, когда заявку взяли в работу. Уже начатая выплата по тайм-ауту не отменяется.

Отмена выплаты

POST /payment/pay-out/{id}/cancel

Отменить можно заявку, которую ещё не начали исполнять. Средства возвращаются на баланс, сделка уходит в canceled.

Что учитывать при исполнении

Время обработки не фиксировано. Оно зависит от метода, суммы и загрузки системы. Не выставляйте в своей системе жёсткий дедлайн короче timeoutInMin.

Статус может вернуться назад. Переход active → pending означает, что заявку пришлось переназначить другому исполнителю. Это штатное поведение: не создавайте выплату заново, дождитесь финального статуса.

Выплата может уйти на ручное подтверждение. Статус manual_review — заявка остановлена для проверки оператором. Дальше она закроется как success или canceled.

Опасно

Не считайте выплату исполненной ни на pending, ни на active. Единственные основания списать средства у себя — success и success_changed. Повторное создание заявки «на всякий случай» приведёт к двойной выплате: платформа не свяжет две заявки с разными merchantTransactionId.

Быстрые откупы и matching

Тот же endpoint обслуживает два дополнительных сценария:

• Быстрые откупы — выплата по QR-ссылке, где сумма читается из самого QR. Отдельные методы POST /payment/instant-pay-out/validate и POST /payment/instant-pay-out, см. Быстрые откупы по QR.
• Matching — с флагом isMatching: true вместо выплаты создаётся заявка, которую закрывают входящие invoice-платежи, см. Matching.

Что дальше

• Статусы сделок — значения status и cancelReason
• Надёжность интеграции — как не выплатить дважды
• Коды ошибок — отказы при создании заявки