Pay-Out · Vietnam

Request

The Pay-Out API initiates disbursement transactions. This page covers Vietnam (country code vn).

Request URL

Domain: Prefer unified host openapi.toppayment.com (path unchanged); legacy country domain (e.g. global-vn-openapi.toppayment.com) remains available.

Environment	URL
Sandbox	https://openapi.toppayment.com/sandbox/vn/disbursement/cash
Production	https://openapi.toppayment.com/vn/disbursement/cash

bankCode values are listed in Regional Payment Guide — Vietnam.

Request Header

Field	Required	Type	Description
Content-Type	M	String	application/json

Request Body

Field	Required	Type	Description
mchNo	M	String(32)	Merchant number
orderNum	M	String(50)	Merchant order number
amount	M	Number(32,8)	Amount
bankCode	M	String(32)	Vietnam bank code
bankCard	M	String(50)	Beneficiary account
accountName	M	String(50)	Beneficiary name
description	M	String(255)	Description
feeType	M	Number	Fee type 0: Deduction within the order 1: Handling fee is calculated separately
downNotifyUrl	M	String(164)	Callback URL
timestamp	M	String(13)	Timestamp
sign	M	String	Signature

Request Example

{
  "mchNo": "{{mchNo}}",
  "orderNum": "VNPPROD1234561",
  "amount": 100,
  "bankCode": "BIDV",
  "bankCard": "09270322921",
  "accountName": "maya",
  "description": "test",
  "feeType": 1,
  "downNotifyUrl": "https://test-domain.com/test/catchStatus",
  "timestamp": "1749451858772",
  "sign": "Generate per signature rules and replace"
}

Response

HTTP Response

Field	Required	Type	Description
Content-Type	M	String	application/json

Response Body Parameters

Field	Required	Type	Description
success	M	Boolean	Request success
code	M	String	9999 = success; otherwise resolve via status codes before finalizing failure
msg	O	String	Message
timeStamp	M	Number	Server time (ms)
data	M	Object	Payload
orderNum	M	String	Merchant order number
platOrderNum	M	String	Platform order number
amount	M	Number	Amount
fee	M	Number	Fee
feeType	M	Number	Fee type
status	M	Number	Status — Transaction Status Codes
statusMsg	M	String	Status message
bankCode	M	String	Bank code (Vietnam) — Regional Payment Guide — Vietnam
bankCard	M	String	Account number
accountName	M	String	Account name
description	O	String	Description

Response Example

{
  "success": true,
  "code": "9999",
  "msg": "SUCCESS",
  "timeStamp": 1767772957433,
  "data": {
    "orderNum": "VNPPROD1234561",
    "platOrderNum": "TRANS2008811496544403456",
    "amount": 100,
    "fee": 2,
    "feeType": 1,
    "status": 1,
    "statusMsg": "ORDER_RECEIVED_PROCESSING",
    "bankCode": "BIDV",
    "bankCard": "09270322921",
    "accountName": "maya",
    "description": "test"
  }
}

Notification

HTTP Request

Field	Required	Type	Description
Content-Type	M	String	application/json

Notification Body

Field	Required	Type	Description
platOrderNum	M	String	Platform order number
version	M	String	Version, e.g. v1
orderNum	M	String	Merchant order number
amount	M	Number	Amount
fee	M	Number	Fee
feeType	M	Number	Fee type
status	M	Number	Status — Transaction Status Codes
statusMsg	M	String	Status message
bankCode	M	String	Bank code (Vietnam)
bankCard	M	String	Account number
accountName	M	String	Account name
description	O	String	Description
sign	M	String	Signature

Acknowledgment

SUCCESS

Notification Example

{
  "platOrderNum": "TRANS2008812168572567552",
  "version": "v1",
  "orderNum": "VNPPROD12345648",
  "amount": 111,
  "fee": 3,
  "feeType": 1,
  "status": 2,
  "statusMsg": "supplement success!",
  "bankCode": "BIDV",
  "bankCard": "09270322921",
  "accountName": "maya",
  "description": "test",
  "sign": "sample-signature"
}