3.1 Create payin

Create payin

POST /api/v1/payins

Creates a single payin on behalf of the merchant.

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.

merchant_user_id and merchant_user_ip are mandatory root fields for every create payin request, including all shop-specific paymentData contracts.

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 payin identifier on the merchant side (idempotency).
amount	string	Yes	Payin amount as a positive decimal string (must be greater than 0).
currency	string (3)	Yes	ISO currency code (RUB, USD, etc.).
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 according to the shop's payin schema.

Additional fields may be included in paymentData according to the shop configuration. The API also accepts the alias payment_data for compatibility.

paymentData fields by direction (shop):

• [PayIn] ARS Payment Data — no additional paymentData fields required

Example request

{
  "external_id": "PIN-001",
  "amount": "1000.00",
  "currency": "BDT",
  "shop_code": "shop-001",
  "merchant_user_id": "merchant-user-001",
  "merchant_user_ip": "203.0.113.10",
  "callback_url": "https://merchant.example.com/webhooks/payin"
}

Response 201 (Created)

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

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

For payment-page flows, the response may also include payment_page_url and payment_page_expires_at. 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 payin is created).

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

Errors

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

amount must be a JSON string, not a JSON number. The API normalizes it by currency scale, for example "1000.00" for RUB/BDT or "10.123456" for USDT.