3.1 Create PayIn

POST /api/v1/payins

p2p Payment Page

Request

Headers

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

Body

Parameter	Type	Required	Description
external_id	string	Yes	Unique PayIn identifier on the merchant side (idempotency).
amount	string	Yes	Positive VND amount as a decimal string.
currency	string (3)	Yes	Must be VND.
shop_code	string	No	Shop code. If not provided, the default shop is used.
callback_url	string	No	URL for status change notifications.
merchant_user_id	string	Yes	Required by the current EPT VND template.
merchant_user_ip	string	No	Optional in the current EPT VND template.
paymentData	object	Yes	EPT VND payer data.
paymentData.account_number	string	Yes	Payer account number.
paymentData.holder	string	Yes	Payer account-holder name.
paymentData.bank_code	string	Yes	Bank code from Bank Codes.

Example request

{
  "external_id": "PIN-VND-EPT-001",
  "amount": "250000",
  "currency": "VND",
  "shop_code": "your_ept_vnd_shop",
  "merchant_user_id": "merchant-user-001",
  "callback_url": "https://merchant.example.com/webhooks/payin",
  "paymentData": {
    "account_number": "0123456789",
    "holder": "Nguyen Van An",
    "bank_code": "VCB"
  }
}

Response

Response fields

Fields with null values and empty paymentData are omitted from the response.

Parameter	Type	Description
id	number	Payfield operation ID.
status	string	Current PayIn status.
external_id	string	Unique PayIn identifier from the request.
amount	string	PayIn amount.
currency	string	VND.
shop_code	string	Shop code used for routing.
merchant_user_id	string	Merchant user identifier from the request.
merchant_user_ip	string	User IP from the request, when supplied.
callback_url	string	Callback URL from the request, when provided.
payment_page_url	string	Hosted payment-page URL at the root of the response.
payment_page_expires_at	string	Hosted payment-page expiration time, when available.
transaction_type	string	Always payin.
created_at	string	Creation timestamp.
updated_at	string	Last update timestamp.
finalization_date	string	Returned when the PayIn reaches a final status.

Example response

{
  "id": 12345,
  "status": "pending",
  "external_id": "PIN-VND-EPT-001",
  "amount": "250000",
  "currency": "VND",
  "shop_code": "your_ept_vnd_shop",
  "merchant_user_id": "merchant-user-001",
  "payment_page_url": "https://pay.example.com/vnd/PIN-VND-EPT-001",
  "transaction_type": "payin",
  "created_at": "2026-09-21T10:00:00+00:00",
  "updated_at": "2026-09-21T10:00:00+00:00"
}