Create a PayOut deal (payout)

POST/api/v1/p2p/merchant/deals/payoutСтейдж

Initiates a payout to the provided target payment details. Checks the merchant balance and places a USDT hold (SELL rate) before creating the deal. Next comes synchronous cascade auto-matching: if a free trader is available, the deal is returned as MATCHED; otherwise as UNASSIGNED, and the re-matching worker keeps looking until the assignment SLA expires the deal (EXPIRED, the hold is released). Returns the deal with the recipient's target_requisite filled in and currency as an echo of the request (the ISO code of the payout fiat currency).

Authorization

MerchantToken MerchantSignature MerchantTimestamp

X-Merchant-Token<token>

The merchant's public token (64 hex characters), issued at onboarding.

In: header

X-Signature<token>

HMAC-SHA256 signature (a single scheme for all endpoints). Format: t=<unix_seconds>,v1=<hex_hmac_sha256> where hex_hmac = HMAC-SHA256(webhook_secret, "<unix_seconds>.<raw_body>"). Replay window: 5 minutes (a 60-second drift into the future is allowed).

In: header

X-Timestamp<token>

Unix time of the request in seconds. Signature window: 5 minutes back / 60 seconds forward.

In: header

Request Body

application/json

TypeScript Definitions

Use the request body type in TypeScript.

tenant_id?string

Injected from the auth context; omit it in client requests.

Formatuuid

merchant_id?string

Injected from the auth context; omit it in client requests.

Formatuuid

amount*integer

The payout amount in minor currency units.

Formatint64

currency*string

ISO 4217 currency code.

wallet_id*string

The 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

A unique operation key.

target_requisite*string

The recipient payment details (card number, SBP phone, IBAN).

target_name?string

The recipient's full name for reconciliation.

target_bank?string

The recipient's bank: a slug (for example ziraat, garanti) or a human-readable name. Passed to the provider as the payout bank and used for intrabank cascade matching (TRY/Havale). Empty = no bank hint (card/SBP payouts).

requisite_details?

Named recipient details 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) and a list of valid ones. Optional: missing/empty = no extra details. The values are the merchant's own details and are returned unmasked.

payment_method*string

The REQUIRED single method reference — the catalog slug (sbp_rub, card_rub, mobcom_rub, express-havale, ...; the slug field from GET /api/v1/p2p/merchant/payment-methods, identical across all environments) or the method's UUID (the id field); both resolve to the same row. NOT the uppercase RequisiteType enum (those are informational requisite_types, never passed in requests). An unknown/missing reference, or a method serving a different deal currency, is rejected with HTTP 400 (a currency cross-check; the error carries the list of valid slugs). PayIn uses the same single 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 "X-Merchant-Token: <MERCHANT_TOKEN>" \  -H "X-Timestamp: <UNIX_TIMESTAMP>" \  -H "X-Signature: t=<UNIX_TIMESTAMP>,v1=<HEX_HMAC_SHA256>" \  -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"    }  ]}

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`