2.1 Create payout

Create payout

POST /api/v1/payouts

Creates a single payout on behalf of the merchant. Only one payout per request is allowed.

Shop routing: optionally specify shop_code in the request body. If shop_code is not provided, the operation is created in the merchant's default shop.

Headers

Parameter	Type	Required	Description
X-API-Key	string	Yes	API key.
X-Timestamp	string	Yes	Request time (ISO-8601 or UNIX sec).
X-Signature	string	Yes	HMAC-SHA256(timestamp + body, secret).
Content-Type	string	Yes	application/json.

Request body (JSON)

Parameter	Type	Required	Description
external_id	string	Yes	Unique payout identifier on the merchant side (idempotency).
amount	number	Yes	Payout amount (minimum greater than 0).
currency	string (3)	Yes	ISO currency code (RUB, USD, etc.).
card_number	string	Yes	Recipient card number (spaces allowed).
shop_code	string	No	Shop code. If not provided — default shop is used.
callback_url	string	No	URL for status change notifications (must be a valid URL).
merchant_user_id	string	Yes	Merchant user identifier (for accounting).
merchant_user_ip	string	Yes	User IP (for accounting).
paymentData	object	No	Additional data per shop schema (holder, phone, bank, comment, etc.).

Additional fields (e.g. recipient name, phone, bank, comment) may be included in paymentData according to the shop configuration. Alternatively, some shops allow flat fields at the root for compatibility — check with support.

paymentData fields by direction (shop):

• [PayOut] INR Payment Data — fields ifsc_code, holder
• [PayOut] BDT Payment Data — fields wallet_provider
• [PayOut] ARS Payment Data — fields recipient_name, bank_name

Example request

{
  "external_id": "PAY-001",
  "amount": 1000.00,
  "currency": "BDT",
  "shop_code": "shop-001",
  "card_number": "4111111111111111",
  "merchant_user_id": "merchant-user-001",
  "merchant_user_ip": "203.0.113.10",
  "callback_url": "https://merchant.example.com/webhooks/payout",
  "paymentData": {
  ....
  }
}

Response 201 (Created)

A single created operation object is returned (not an array).

{
  "id": 12345,
  "status": "pending",
  "external_id": "PAY-001",
  "amount": 1000,
  "currency": "BDT",
  "shop_code": "shop-001",
  "card_number": "4111111111111111",
  "merchant_user_id": "merchant-user-001",
  "merchant_user_ip": "203.0.113.10",
  "callback_url": "https://merchant.example.com/webhooks/payout",
  "transaction_type": "payout",
  "created_at": "2025-12-05T10:00:00.000000Z",
  "updated_at": "2025-12-05T10:00:00.000000Z"
}

If the shop response schema exposes additional payout fields, they are returned under paymentData. Fields with null values and empty paymentData are omitted from the response.

When the same request is sent again with the same external_id and shop (idempotency), the API returns 200 and the existing operation object with "message": "Transaction already exists" (no new payout is created).

The same external_id may still be used for a payin in the same shop. Idempotency is scoped by transaction type and shop.

Errors

• 422 — validation error: missing or invalid external_id, amount, currency, card_number, merchant_user_id, merchant_user_ip; invalid callback_url; invalid paymentData; insufficient balance; limit exceeded; shop currency mismatch.