Payouts to clients (PayOut)

A payout (PayOut) is a P2P withdrawal operation in which the merchant creates a transfer request, and the executor — a trader or an API provider — makes the actual transfer to the recipient from their own bank account.

Payout flow (PayOut Flow)

PayOut creation endpoint

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

Request parameters (JSON Body)

* target_bank is mandatory for bank methods (BANK_TRANSFER / Havale) when the bank is not derived from the request itself: the platform resolves the bank from the TCMB code embedded in the IBAN (positions 5–9) against the GET /merchant/banks reference. If neither target_bank nor the IBAN-derived code is known, the request is rejected with 400 INVALID_ARGUMENT before the deal and the hold are created (see Error codes).

Request example

{
  "amount": 500000,
  "currency": "RUB",
  "wallet_id": "8f870a31-b88d-4cb0-a882-628d08cbda88",
  "target_requisite": "2202201234567890",
  "target_name": "Ivan Ivanovich I.",
  "payment_method": "card_rub",
  "idempotency_key": "payout_order_99812"
}

Response example (200 OK)

The response is a MerchantDealInfo object in the top-level deal field (there is no data wrapper). The deal identifier is deal_id (NOT id). For PAYOUT, payment_url is empty (it exists only for PayIn); instead, target_requisite is filled. currency echoes the ISO code of the payout's fiat currency from the request.

The status in the response depends on where the cascade routed the payout (matching runs synchronously, at creation time):

• PROCESSING — routed to an API provider: the payout was created at the provider within the same request, and the transfer is already in progress;
• MATCHED — routed to a trader, and a free executor was found (the example below);
• UNASSIGNED — no free executor at creation time; the retry worker keeps matching (see PayOut deal statuses).

The terminal status (COMPLETED / FAILED / EXPIRED) arrives by webhook — the PROCESSING and MATCHED holders in the creation response are equivalent in terms of the further lifecycle.

{
  "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 deal statuses

The canonical lifecycle is domain.PayOutStatus (7 values). PayOut uses a status domain separate from PayIn. The full table with the V1 codes is in the status reference.

Special statuses

• UNASSIGNED — at creation time, the cascade auto-matching found no free trader (all busy / limits exhausted / no requisites for that currency and amount). The deal is returned with this status in the POST /deals/payout response, after which the retry worker automatically retries matching: on success, the status moves to MATCHED → then the regular lifecycle; if the assignment SLA expires, the payout moves to the terminal EXPIRED and the hold is returned to the merchant. Not a terminal status. Manual assignment (admin override) remains available to the operator.
• PayOut does not use the PayIn statuses (PAYMENT_NOTIFIED, PAYMENT_VERIFIED, APPEALED, SOFT_DISPUTED).

TRY / IBAN payouts (Havale)

For Turkey, payouts go as a bank transfer by IBAN (RequisiteType BANK_TRANSFER): the base requisite is target_requisite (the recipient's IBAN), with target_bank and requisite_details filled in addition.

New request fields

Bank derivation

For a bank method (BANK_TRANSFER / Havale), the platform must know the recipient bank before the deal is created. The bank counts as derived when:

1. a valid target_bank is passed (a slug from GET /merchant/banks), or
2. the payment details contain a Turkish IBAN whose TCMB code (positions 5–9: TRxx BBBBB + account) resolves against the platform's bank reference — the bank is derived automatically, and passing target_bank is not needed.

If neither holds, the request is rejected immediately, before the deal is created and the escrow hold is taken:

{
  "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"
}

Request example (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 (minor units are kuruş, 2 decimal places).
• payment_method — the slug (or UUID) of the Havale method created for your tenant (for example, express-havale); the value is resolved against your tenant's active methods — an unknown reference or a method of another currency is rejected with 400 (the list of your tenant's methods and slugs — GET /api/v1/p2p/merchant/payment-methods, see Banks).
• requisite_details.document_number — an example of an extra detail (TC kimlik / document number), not always required: pass it when the method or the recipient bank requires it.

Response example (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 — an echo from the request, without masking (see the NOTE above).

Single payout limits

Amount limits are not hardcoded — they are determined dynamically by the tenant configuration:

Webhook events

IBAN validation

If the payout method accepts an IBAN (requisite type BANK_TRANSFER), the recipient goes through an ISO 13616 checksum check: a mistyped requisite is rejected immediately (400, with the IBAN masked in the error message); spaces and letter case are normalized before the check. Card and phone methods require no validation.