Create a PayOut deal (disbursement)

Initiates a payout to the supplied target requisites. Validates the merchant balance and places a USDT hold (SELL rate) before creating the deal. Synchronous cascade auto-matching then follows: when a free trader exists the deal returns in `MATCHED`; otherwise it returns in `UNASSIGNED` and a retry worker keeps matching until the assignment SLA expires the deal (`EXPIRED`, hold released). Returns the deal with the recipient `target_requisite` populated and `currency` echoed from the request (ISO fiat currency of the payout).

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

Initiates a payout to the supplied target requisites. Validates the merchant balance and places a USDT hold (SELL rate) before creating the deal. Synchronous cascade auto-matching then follows: when a free trader exists the deal returns in MATCHED; otherwise it returns in UNASSIGNED and a retry worker keeps matching until the assignment SLA expires the deal (EXPIRED, hold released). Returns the deal with the recipient target_requisite populated and currency echoed from the request (ISO fiat currency of the payout).

Authorization

MerchantToken MerchantSignature

X-Merchant-Token<token>

64-character hex public merchant token assigned during onboarding.

In: header

X-Signature<token>

Stripe-style HMAC-SHA256 signature. Format: t=<unix_seconds>,v1=<hex_hmac_sha256> where hex_hmac = HMAC-SHA256(webhook_secret, "<unix_seconds>.<raw_body>"). Replay window: 5 minutes (60s future drift tolerated).

In: header

Request Body

application/json

TypeScript Definitions

Use the request body type in TypeScript.

tenant_id?string

Injected from auth context; omit in client requests.

Formatuuid

merchant_id?string

Injected from auth context; omit in client requests.

Formatuuid

amount*integer

Payout amount in smallest currency units.

Formatint64

currency*string

ISO 4217 currency code.

wallet_id*string

UUID of the merchant's USDT wallet to debit — the hold is placed in USDT (converted at the SELL rate at creation time), NOT on the fiat wallet. Use the wallet_id of the USDT row from GET /balance.

Formatuuid

idempotency_key*string

Unique operation key.

target_requisite*string

Recipient requisites (card number, SBP phone, IBAN).

target_name?string

Recipient full name for verification.

target_bank?string

Recipient bank: slug (e.g. ziraat, garanti) or human-readable name. Routed to the provider as the payout bank and used for intra-bank cascade matching (TRY/Havale). Empty = no bank hint (card/SBP payouts).

requisite_details?

Named recipient requisites beyond target_requisite / target_name. Allowed keys (enum): iban, account_number, document_number, bank_name, phone_number. Unknown keys are rejected with HTTP 400 (InvalidArgument) listing the allowed set. Optional: absent/empty = no extra requisites. Values are the merchant's own requisites and are echoed back unmasked.

payment_method*string

REQUIRED unified method reference — the catalog slug (sbp_rub, card_rub, mobcom_rub, express-havale, ...; the slug field of GET /api/v1/p2p/merchant/payment-methods, identical across all environments) or the method UUID (the id field); both resolve to the same row. NOT the uppercase RequisiteType enum (those are informational requisite_types, never sent in requests). Unknown/missing reference or a method serving another currency than the deal is rejected with HTTP 400 (currency cross-check; the error lists the allowed slugs). PayIn uses the same unified contract via payment_method_id.

Response Body

`application/json`

`application/problem+json`

curl -X POST "https://example.com/api/v1/p2p/merchant/deals/payout" \  -H "Content-Type: application/json" \  -d '{    "amount": 500000,    "currency": "RUB",    "wallet_id": "d9a8fbfc-848f-43a2-9168-911ed3a04a48",    "idempotency_key": "payout_order_99812",    "target_requisite": "2202201234567890",    "payment_method": "card_rub"  }'

{  "deal": {    "deal_id": "8bd2590f-2345-6789-abcd-ef1234567890",    "status": "MATCHED",    "amount": "500000",    "currency": "RUB",    "created_at": "2026-08-10T12:05:00Z",    "client_id": "player_42",    "deal_type": "PAYOUT",    "updated_at": "2026-08-10T12:05:00Z",    "target_requisite": "2202201234567890"  }}

{  "type": "../dictionary",  "title": "string",  "status": 0,  "detail": "string",  "instance": "../dictionary",  "errors": [    {      "field": "amount",      "message": "must be greater than 0",      "code": "POSITIVE_REQUIRED"    }  ]}

{  "type": "../dictionary",  "title": "string",  "status": 0,  "detail": "string",  "instance": "../dictionary",  "errors": [    {      "field": "amount",      "message": "must be greater than 0",      "code": "POSITIVE_REQUIRED"    }  ]}

{  "type": "../dictionary",  "title": "string",  "status": 0,  "detail": "string",  "instance": "../dictionary",  "errors": [    {      "field": "amount",      "message": "must be greater than 0",      "code": "POSITIVE_REQUIRED"    }  ]}

Create a PayOut deal (disbursement)

Authorization

Request Body

Response Body

200application/json

400application/problem+json

401application/problem+json

503application/problem+json

`application/json`

`application/problem+json`

`application/problem+json`

`application/problem+json`