Vietnam Payment API

About 2675 wordsAbout 9 min

Warning

Before reading this API document, please make sure to check API Description Guide first.

Transaction Limits

Transaction Type	Limit
Collection	USD: 0.99-2000, VND: 10000-50000000
Disbursement	VND: 10000-50000000

Collection API

Collection Application

Description:

Create a Collection order.

URL：/vnd/collect/apply
Note: appId needs to use VND corresponding, user payment success will increase VND balance

URL：/usd/collect/apply
Note: appId needs to use USD corresponding, user payment success will increase USD balance

Request Method:

Parameter	Required	Type	Description
appId	Yes	Long	Business ID (obtained from backend, must match the currency in URL)
orderId	Yes	String	Merchant order ID (must be unique, max length 48)
name	Yes	String	Payer name (Format: English or Vietnamese case-insensitive, spaces allowed, 1-30 characters, "firstName middleName lastName" (middleName is optional). Special characters supported: ! -)
outBankNo	No	String	Payer card number, required when payType = PAYMENT_GATEWAY
phone	Yes	String	Valid phone number
email	Yes	String	Valid email address
amount	Yes	String	Transaction amount (Unit: ₫ VND) Range: 50,000 – 100,000,000. Must be a multiple of 100
payType	Yes	String	Transaction type: QR, PAYMENT_GATEWAY, BANK_TRANSFER, EWALLET
inBankCode	No	String	Payment method. When payType = EWALLET, supports MOMO_VND for MoMo Wallet payment
callBackUrl	Yes	String	Redirect URL after successful payment
callBackFailUrl	Yes	String	Redirect URL after failed payment
notifyUrl	No	String	Notification callback URL
currency	No	String	Currency (default: VND, supported: USD, VND)
subject	No	String	Payment note
body	No	String	Payment details
partnerUserId	Yes	String	Unique user identifier (e.g. userId) for risk control, must be valid. Format: numbers, letters, or symbols -~!@#$%&*()_
sign	Yes	String	Signature

request

{
    "appId": 1054,
    "orderId": "M233323000059",
    "amount": "300",
    "phone": "08230219312",
    "email": "23423@qq.com",
    "name": "test",
    "inBankCode": "VCB",
    "payType": "QR",
    "partnerUserId": "149597870",
    "sign": "af0gAHkUOyYHu9owQp8NJ4mPEeUW4vuJcjdxqLIzrVw8AvpLSjD1DXupReSG/CyuSkFRyiIvCp5u703AuGGmfgD2gKDH3Ywau41bAbG2jnHJ8mtjiSJ5iWUzanyd4Kr7d1+rETbzUl7/BkW3t0X8UUFdqpxwG8DPUjAwUKfplWDHV7koG51Ozexd80DCsmW6eWdouAZ1uNXGLYmV3ftE3BmfNRtuv1C5bfTJWrTEIOxbF6g2uYOFZTlIgrQgd7/2PsAYwQQXNz8Q8CYl4OxqCv4pXJxaLWPbR5tqZu9og5kn32C9aHW/NlU1y39vzz+4ef81yPAqUV9oHlSMSPrMmw=="
}

va-response

{
    "status": "1",
    "error": "00000000",
    "msg": "",
    "data": {
        "orderId": "M233323000059",
        "orderNo": "6023071013539074",
        "payUrl": "https://a.api-uat.vnd.com/1L9zQS2",
        "bankCode": "VCB",
        "qrCode": "00020101021228760011ph.ppmi.p2m0111OPDVPHM1XXX0315777148000000017041652948137245442930503001520460165303608540810000.vnd Of Mandalu62310010ph.allbank05062110000803***88310012ph.ppmi.qrph0111OPDVPHM1XXX63042763",
        "sign": "YEoA8Y2JzQFGVzwJSqmemm1Kfv/bfyIfCqv2dp7RNzT5B72AQvdD+nt2nR4sL1HWscvmNHyVt5ovAi7MMhy3ziih/sMph+wPx4YjH3W1h5DyBvSlWvaKfKrK5ViomZ0pPYWydwRHnnRnicxToHK9S6qtSy7Q73O0hdz4hJ9p41Th3ycBl2Q9SeqSZYSY1ohcPDhdyRf2y0prb8rHgpBKzxZ5BKX/1bsE9OmsSEHAEYT8OGgko6aNe8XPAhr4G48cpWTftvnGQuzh0O65nuZRI/PF+Axt2zJCVbFHDDSREI9NlAT82ebDqhlVdxQzKE67D1nxgjb3dPmDUYHOBpmwxQ=="
    }
}

Return data Parameter Description

Parameter	Type	Description
orderId	String	Merchant order ID (must be unique)
orderNo	String	Platform order ID
payUrl	String	Returned payment address, or sometimes a guide/details
bankNo	String	Receiving account number (BANK_TRANSFER)
bankCode	String	Receiving bank
bankUserName	String	Recipient name (BANK_TRANSFER)
qrCode	String	QR code content — can be used to generate a QR code (for payType=QR)
sign	String	Signature

Collection Query

Description:

Query a Collection order
When payType=PAYMENT_GATEWAY, orderNo is returned synchronously and can be queried directly
For other payment methods, after asynchronous notification, query status again using orderNo

URL: /vnd/collect/query

Parameters:

Parameter	Required	Type	Description
appId	Yes	Long	Business ID (obtained from backend, must match the currency in the URL)
orderId	Yes	String	Merchant order ID
orderNo	No	String	Platform order ID (faster response)
sign	Yes	String	Signature

request

{
    "appId": 1054,
    "orderId": "M22222000028",
    "sign": "EmyJGm3ELzG4FsOd0Krs9ncbSjo4oTGuXWML+7djYla3+VAwd9wS17z38p/7U2ZAjroO04XrE7YXcB1o76Dtyipj3h3bJzs7FYma1QNkMUdt9hh7m8U6hMsMQX7vIWHtXNwz4pbTSC75+kQWXaCew7KoE6LXECdJU8AISgNgeki2TK9R0pCfshr0Z2SZBPeuT6OvIH5LdmqgdZhuqnffGU2qnXk4KMkO848e6/WALLBR+LE1wyKHfPnYVcuKSMVYxkvKyyIL5JIPEgW0o5bh4RCbaUn3NZtyYwrU1uQ3ZDFRThm9j6XAQP+LBlmq3nOePqBtp/VDVarRaV+7FbQg3A=="
}

response

{
    "status": "1",
    "error": "00000000",
    "msg": "",
    "data": {
        "orderId": "M22222000028",
        "orderNo": "6023042811314347",
        "amount": "50000.00",
        "actualAmount": "0.00",
        "fee": "0.00",
        "status": 1,
        "sign": "fP433ygWVDLVGxYkVnIJj7riGq0U3vyVX+MbBAImxfGLZkZcEAHVEoVYuULZSmXAAXKRSyd67WlDNm+24pougM54ofAoH4HMtCL2tfCoBReFyz3z02AGKkrKE2xWhSpWoqfQoBvzwuN5iGMMu0s9Q1YvqiwJ8WDVIENnmiIyD8qDJN7caHTW2US14/faG+69AvnuIgJ/nu7/jogOlgEYdZdVYU7gcRDE+d47KjlFGswQkJ/h/uzV7cWtUqrtOO7ZnZ3/z33Xx8awokX36QoYcPSWAU0h+Ij9O9402HNhm1eTbYcLU0uI/z8xCAtyAI/tTyiFijpiNlxUKQj+zKsILw=="
    }
}

Return data Parameter Description

Parameter	Type	Description
orderId	String	Merchant order ID (must be unique)
orderNo	String	Platform order ID
amount	String	Transaction amount
actualAmount	String	Amount received
fee	String	Fee
status	Integer	Status (0: Not started, 1: Collecting, 2: Collection successful, 3: Collection failed, 4: Partial collection, 5: Excess collection, -1: Exception pending confirmation)
payTime	String	Payment success time (present when status=2, 4, or 5) (Vietnam time), format: yyyy-MM-dd HH:mm:ss
errorMsg	String	Failure reason (present when status=3)
sign	String	Signature

Payment Methods

Currency	Payment Type (payType)	Payment Code (inBankCode)	Limit	Status	Description
VND	QR	QR	10000-50000000	Available	QR Code
VND	BANK_TRANSFER	BANK	10000-50000000	Available	Bank Transfer
VND	EWALLET	MOMO_VND	10000-5000000	Available	MOMO Wallet
USD	QR	VN_QR_USD	0.99-2000	Available	QR Code
USD	BANK_TRANSFER	VN_BANK_USD	0.99-2000	Available	Bank Transfer

Disbursement API

Disbursement Apply

Description:

Create a Disbursement order

URL: /vnd/pay/apply

Parameters:

Parameter	Required	Type	Description
appId	Yes	Long	Business ID (obtained from backend, must match the currency in the URL)
orderId	Yes	String	Merchant order ID (must be unique, length ≤ 48)
amount	Yes	String	Transaction amount (unit: ₫) Range: 50,000–10,000,000
accountType	Yes	String	Account type: BANK_ACCOUNT
bankCode	Yes	String	Bank code
accountNo	Yes	String	User bank account number
name	Yes	String	Recipient name (Format: English or Vietnamese, case-insensitive, spaces allowed, 1–30 characters, "firstName middleName lastName" (middleName is optional), special characters supported: '.-)
phone	Yes	String	Real phone number
email	Yes	String	Real email address
notifyUrl	No	String	Callback URL
subject	No	String	Payment note (transaction title, product name, payment reason)
body	No	String	Detailed note
partnerUserId	Yes	String	User unique identifier (e.g., userId). Used by risk control, must be valid. Format: numbers, letters, or common symbols -~!@#$%&*()_.
sign	Yes	String	Signature

request（accountType为BANK_CARD类型时）

{
    "appId": 1054,
    "orderId": "M100000450012",
    "amount": "500",
    "accountType": "BANK_CARD",
    "bankCode": "BDO",
    "accountNo": "09876543210",
    "name": "john doe",
    "phone": "08276543210",
    "email": "johndoe@cashfree.com",
    "subject": "iphone13",
    "body": "ProMotion technology with adaptive refresh rates up to 120Hz",
    "partnerUserId": "149597870",
    "sign": "I1PeK3eJOVsFFNowxVRqMXpeWm1lr/BcRpBi8WsW4wVo1+5CC3JsrFq/m/L2O69NzKHvtDWi4zia3DL3dPut0yMyUyqL91LNCSaeISbGsQPlhEsQpyTOryS/RKOfsrn2Xo37SCF/phAvndOk2jwwGwqM5xLz1ms9Ukl85wv27QFNrXIMxK2p18oe7MpMYrgf+xvEBE/VqCtKMtN9pO449wWwXzHWNPbZ76s4pAvKwRE9yXQDr7Iw14Dktcnl1FoLM4gWM/obkO+mz6SyAGDuXhVh/+OD/IGNiCyTCNq6ciQY28UnCFV6ZIP40gxsFhfBJKbK+Raw7y1Bh912ifYfug=="
}

response

{
    "status": "1",
    "error": "00000000",
    "msg": "",
    "data": {
        "orderId": "M100000450013",
        "orderNo": "3023062014149637",
        "sign": "LmhUnkw5j0pMiimsG8rKwdNNZGvXH5MpSmD6mdHZwq1SQwuK5BohmdEoqKB/jkMk28o3da4Cxh6Q+tW97+yTCemRrF+dMaHA73rpOeUuujKQl/UcFvJuMhfLBa2tp09L71NzoBqpPD6aXf37mYAz8E1HmERwFPpac5FVxIYanHG8cqmMLJYsVmHTSxWavgWU03ys9UczBePkBiR8sl2FSOhFABB0wAP28lswrV/ABS68IsLKtyd1fyI3GBfSbIK5nDEEnlE+EdElFdLs9taAxJImeVF1x4eT47+bkPJ2qS8z3K8QGzKLF3W+8SiRZGfSwDTsLKH+2Vycvy5auRl+ag=="
    }
}

Return data Parameter Description

Parameter	Required	Type	Description
orderId	Yes	String	Merchant order ID (must be unique)
orderNo	Yes	String	Platform order ID
sign	Yes	String	Signature

Disbursement Query

Description:

Query a Disbursement order

URL: /vnd/pay/query

Parameters:

Parameter	Required	Type	Description
appId	Yes	Long	Business ID (obtained from backend, must match the currency in the URL)
orderId	Yes	String	Merchant order ID
orderNo	No	String	Platform order ID (faster response)
sign	Yes	String	Signature

request

{
    "appId": 1000,
    "orderId": "M1234567111",
    "orderNo": "3022111516571436",
    "sign": "ZxkVZL+GAyv0VhvWn4IvuYahTzxgQuthkuV2ONWiqIfIDb2avvHlFOUJVzqZi1q8CPHXZm1ltanRTRVTxfsuftLvGeDioUHglWt46/RU6c1OPznpLGsZ35Q3n5tW2y1EnOsxPynXBFLuDQy+aZ3l9u6AQ30T0zQexMGT+IxuFkmUp02g/6juaHa5ZgNMv7lN67ixIp162wrM7OJuaOif872QijSceRdZhzaMGImAwB0D4MosRV4WMBOKkwgPdmS7GuZN66YUidXk3wTGqX3MYRw6M0kj4eNegSUwPXvp4q4p0KO8Y3xUMld54GY2ApX3WN3CBtC/vpJqEszjGBbbGg=="
}

response — Order Failed

{
    "status": "1",
    "error": "00000000",
    "msg": "",
    "data": {
        "orderId": "M1234567111",
        "orderNo": "3022111516571436",
        "amount": "100000.00",
        "fee": "0.00",
        "status": 3,
        "errorMsg": "Đơn hàng không tồn tại",
        "sign": "KKuvCl0SuNANJs+l2ogDaJm8pmV+Hi+Xa7q27vJ6D1Ehs4aOp13kRbITfJAhczh3T81BE9qwHeJaYwf+r0EypKM9TL6pMwfG8Az4gRy1D57wiUaVjl2PWcvbEqrn1hL0b+btkjvAM9I+CcSv+wuOW3/uku17Ws3FhgJLj9sFsQUBAPjDO+758VnwBytCOLBmljLBXyKgNgpmFQ1/DNkqWl0UNzyLK45Zw3yf5NiwhEFbvW0jlOWlfu/ql4hluISUQG573jEoFCBEnQLb2tQoRZj1QYNRCXPf5lbej0vzqbEwvR9h+ZOf255t1MocJkdIe463DTV5U3KZdVT87HMagw=="
    }
}

response — Order Successful

{
    "status": "1",
    "error": "00000000",
    "msg": "",
    "data": {
        "orderId": "M1234567112",
        "orderNo": "3022111517401574",
        "amount": "100000.00",
        "fee": "1003.00",
        "status": 2,
        "payTime": "2024-03-01 23:59:59",
        "sign": "khPtOmGq+cpKX0HFAI/lbP0dx4oVyNAnL5oLsdmhDJdASlQm0yg5I3o+MhImYggEsL6c2bo5fP29t54OZFqSdQDfIuNDvGbAMAr4mRBxc0hoHLkBLyyagfVPBLyQA1JY8XV3ZL4ySzQ3ZQnMCfrh2K39ueUuz6HpZ03Hj0KYijVRCXAZaio/L5jfLBT12QXmvIfAHa8s/k9flhK05ENHPep3zjj/MZGOEaX7jkEJLfjK0duypDCa61BRQjM+oePOdVsgleIl1Yf98UAxMDZ/A3912KFHEb+/jvmdnulNbiJFyuT1fEe+j2teUgw3vFsZAtwNWAgxhC7UO+N0Q5z4EA=="
    }
}

Return data Parameter Description

Parameter	Type	Description
orderId	String	Merchant order ID (must be unique)
orderNo	String	Platform order ID
amount	String	Transaction amount
fee	String	Fee
status	Integer	Order status (0 Not Started, 1 Processing, 2 Disbursement Success (final), 3 Disbursement Failed (final), -1 Exception Pending Confirmation)
payTime	String	Payment success time (present when status=2) (Vietnam Time), format: yyyy-MM-dd HH:mm:ss
errorMsg	String	Payment failure reason (presnet when status=3)
sign	String	Signature

Payment Methods

Currency	Payment Type (accountType)	Payment Code (bankCode)	Limit	Status	Description
VND	BANK_ACCOUNT	VCB	10000-50000000	Available	Vietcombank
VND	BANK_ACCOUNT	DAB	10000-50000000	Available	DongA Bank
VND	BANK_ACCOUNT	TCB	10000-50000000	Available	Techcombank
VND	BANK_ACCOUNT	MB	10000-50000000	Available	Military Bank
VND	BANK_ACCOUNT	VIB	10000-50000000	Available	Vietnam International Bank
VND	BANK_ACCOUNT	ICB	10000-50000000	Available	VietinBank
VND	BANK_ACCOUNT	EXB	10000-50000000	Available	Eximbank
VND	BANK_ACCOUNT	ACB	10000-50000000	Available	Asia Commercial Bank
VND	BANK_ACCOUNT	HDB	10000-50000000	Available	HDBank
VND	BANK_ACCOUNT	MSB	10000-50000000	Available	Maritime Bank
VND	BANK_ACCOUNT	NCB	10000-50000000	Available	National Citizen Bank
VND	BANK_ACCOUNT	VAB	10000-50000000	Available	Viet A Bank
VND	BANK_ACCOUNT	VPB	10000-50000000	Available	VPBank
VND	BANK_ACCOUNT	STB	10000-50000000	Available	Sacombank
VND	BANK_ACCOUNT	BAB	10000-50000000	Available	Bac A Bank
VND	BANK_ACCOUNT	GPB	10000-50000000	Available	GPBank
VND	BANK_ACCOUNT	AGB	10000-50000000	Available	Agribank
VND	BANK_ACCOUNT	BIDV	10000-50000000	Available	BIDV
VND	BANK_ACCOUNT	OJB	10000-50000000	Available	OceanBank
VND	BANK_ACCOUNT	PGB	10000-50000000	Available	PG Bank
VND	BANK_ACCOUNT	SHB	10000-50000000	Available	Saigon - Hanoi Bank
VND	BANK_ACCOUNT	TPB	10000-50000000	Available	TienPhong Bank
VND	BANK_ACCOUNT	NAB	10000-50000000	Available	Nam A Bank
VND	BANK_ACCOUNT	SGB	10000-50000000	Available	Saigon Bank
VND	BANK_ACCOUNT	ABB	10000-50000000	Available	An Binh Bank
VND	BANK_ACCOUNT	SCB	10000-50000000	Available	Saigon Commercial Bank
VND	BANK_ACCOUNT	IVB	10000-50000000	Available	Indovina Bank
VND	BANK_ACCOUNT	VCCB	10000-50000000	Available	Viet Capital Bank
VND	BANK_ACCOUNT	OCB	10000-50000000	Available	Orient Commercial Bank
VND	BANK_ACCOUNT	SEA	10000-50000000	Available	Dong Nam A Bank
VND	BANK_ACCOUNT	LVB	10000-50000000	Available	LienVietPostBank
VND	BANK_ACCOUNT	WRB	10000-50000000	Available	Woori Bank
VND	BANK_ACCOUNT	PVCOMBANK	10000-50000000	Available	PVcomBank
VND	BANK_ACCOUNT	SHNB	10000-50000000	Available	Shinhan Bank
VND	BANK_ACCOUNT	KLB	10000-50000000	Available	Kien Long Bank
VND	BANK_ACCOUNT	BVB	10000-50000000	Available	BaoViet Bank
VND	BANK_ACCOUNT	GAB	10000-50000000	Available	Dai A Bank
VND	BANK_ACCOUNT	NVB	10000-50000000	Available	Navibank