Выплаты клиентам (PayOut)

Выплата (PayOut) — это P2P-операция вывода средств, при которой мерчант создаёт заявку на перевод, а исполнитель — трейдер или API-провайдер — выполняет фактический перевод получателю со своего банковского счёта.

Процесс выплаты (PayOut Flow)

Эндпоинт создания PayOut

POST /api/v1/p2p/merchant/deals/payout

Параметры запроса (JSON Body)

* target_bank обязателен для банковских методов (BANK_TRANSFER / Havale), если банк не выводится из самого запроса: платформа определяет банк по TCMB-коду из IBAN (позиции 5–9) через справочник GET /merchant/banks. Если ни target_bank, ни код из IBAN не определены — запрос отклоняется 400 INVALID_ARGUMENT до создания сделки и холда (см. Коды ошибок).

Пример запроса

{
  "amount": 500000,
  "currency": "RUB",
  "wallet_id": "8f870a31-b88d-4cb0-a882-628d08cbda88",
  "target_requisite": "2202201234567890",
  "target_name": "Иван Иванович И.",
  "payment_method": "card_rub",
  "idempotency_key": "payout_order_99812"
}

Пример ответа (200 OK)

Ответ — объект MerchantDealInfo в поле deal верхнего уровня (обёртки data нет). Идентификатор сделки — deal_id (НЕ id). Для PAYOUT payment_url пуст (он есть только у PayIn); вместо него заполнено target_requisite. currency — эхо ISO-кода fiat-валюты выплаты из запроса.

Статус в ответе зависит от того, куда каскад маршрутизировал выплату (матчинг выполняется синхронно, в момент создания):

• PROCESSING — маршрут на API-провайдера: выплата создана у провайдера в том же запросе, перевод уже в работе;
• MATCHED — маршрут на трейдера, свободный исполнитель найден (пример ниже);
• UNASSIGNED — свободного исполнителя нет на момент создания; retry-воркер продолжает матчинг (см. Статусы PayOut сделки).

Терминальный статус (COMPLETED / FAILED / EXPIRED) приходит вебхуком — держатели статуса PROCESSING и MATCHED в ответе создания равнозначны с точки зрения дальнейшего жизненного цикла.

{
  "deal": {
    "deal_id": "e81d77a0-0d3a-4422-b91c-7cb052a2119c",
    "status": "MATCHED",
    "amount": "500000",
    "currency": "RUB",
    "created_at": "2026-07-12T17:21:00Z",
    "client_id": "",
    "deal_type": "PAYOUT",
    "updated_at": "2026-07-12T17:21:00Z",
    "payment_url": "",
    "target_requisite": "2202201234567890",
    "received_amount": "0",
    "amount_match_status": ""
  }
}

Статусы PayOut сделки

Канонический жизненный цикл — domain.PayOutStatus (7 значений). PayOut использует отдельный домен статусов от PayIn. Полная таблица с V1-кодами — в Справочнике статусов.

Особые статусы

• UNASSIGNED — на момент создания авто-матчинг каскада не нашёл свободного трейдера (все заняты / лимиты исчерпаны / нет реквизитов под эту валюту и сумму). Сделка возвращается с этим статусом в ответе POST /deals/payout, после чего retry-воркер автоматически повторяет мэтчинг: при успехе статус переходит в MATCHED → далее обычный жизненный цикл; если SLA на назначение истекает — выплата переходит в терминальный EXPIRED, холд возвращается мерчанту. Не терминальный статус. Ручное назначение (admin override) остаётся доступным для оператора.
• PayOut не использует PayIn-статусы (PAYMENT_NOTIFIED, PAYMENT_VERIFIED, APPEALED, SOFT_DISPUTED).

Выплаты TRY / IBAN (Havale)

Для Турции выплаты идут как банковский перевод по IBAN (RequisiteType BANK_TRANSFER): базовый реквизит — target_requisite (IBAN получателя), дополнительно заполняются target_bank и requisite_details.

Новые поля запроса

Определение банка (bank derivation)

Для банковского метода (BANK_TRANSFER / Havale) платформа должна знать банк получателя ещё до создания сделки. Банк считается определённым, если:

1. передан валидный target_bank (слаг из GET /merchant/banks), или
2. в реквизитах есть турецкий IBAN, чей TCMB-код (позиции 5–9: TRxx BBBBB
   • счёт) резолвится в справочник банков платформы — банк выводится автоматически, target_bank передавать не нужно.

Если ни то, ни другое не выполняется — запрос отклоняется сразу, до создания сделки и взятия эскроу-холда:

{
  "type": "about:blank",
  "title": "Bad Request",
  "status": 400,
  "detail": "{\"code\":3,\"message\":\"target_bank: bank not derivable from IBAN — pass target_bank (see GET /merchant/banks)\",\"details\":[]}",
  "instance": "/api/v1/p2p-engine"
}

Пример запроса (TRY / Havale)

{
  "amount": 2500000,
  "currency": "TRY",
  "wallet_id": "8f870a31-b88d-4cb0-a882-628d08cbda88",
  "target_requisite": "TR33 0006 1005 1978 6457 8413 26",
  "target_name": "Ahmet Yilmaz",
  "target_bank": "ziraat",
  "requisite_details": {
    "iban": "TR33 0006 1005 1978 6457 8413 26",
    "document_number": "12345678901"
  },
  "payment_method": "express-havale",
  "idempotency_key": "payout_try_order_00042"
}

• amount: 2500000 = 25 000.00 TRY (минорные единицы — куруш, 2 знака).
• payment_method — слаг (или UUID) Havale-метода, заведённого для вашего тенанта (например, express-havale); значение резолвится против активных методов тенанта — неизвестная ссылка или метод другой валюты отклоняется с 400 (список методов и слагов вашего тенанта — GET /api/v1/p2p/merchant/payment-methods, см. Banks).
• requisite_details.document_number — пример дополнительного реквизита (TC kimlik / номер документа), нужен не всегда: передавайте, когда метод или банк получателя его требует.

Пример ответа (200 OK)

{
  "deal": {
    "deal_id": "c25f9b31-7e40-4a11-8f0a-6d92b7c4e155",
    "status": "MATCHED",
    "amount": "2500000",
    "currency": "TRY",
    "created_at": "2026-08-18T11:02:00Z",
    "client_id": "",
    "deal_type": "PAYOUT",
    "updated_at": "2026-08-18T11:02:00Z",
    "payment_url": "",
    "target_requisite": "TR33 0006 1005 1978 6457 8413 26",
    "received_amount": "0",
    "amount_match_status": ""
  }
}

target_requisite — эхо из запроса без маскировки (см. NOTE выше).

Лимиты на разовые выплаты

Лимиты сумм не захардкожены — они динамически определяются конфигурацией тенанта:

События вебхуков

Валидация IBAN

Если метод выплаты принимает IBAN (тип реквизита BANK_TRANSFER), получатель проходит проверку контрольной суммы ISO 13616: реквизит с опечаткой отклоняется сразу (400, маскированный IBAN в тексте ошибки), пробелы и регистр нормализуются до проверки. Карточные и телефонные методы проверки не требуют.