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.

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	number	Yes	Payin amount (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	No	Merchant user identifier (for accounting).
merchant_user_ip	string	No	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] BDT Payment Data — fields wallet_provider , mobile_number, email and customer_name
• [PayIn] INR Payment Data — fields wallet_provider , mobile_number, email and customer_name

Example request

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

Response 201 (Created)

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

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

For payment-page flows, the response may also include payment_page_url and payment_page_expires_at.

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; invalid callback_url; invalid paymentData; limit exceeded; shop currency mismatch.