Vietnam Payment API

About 1385 wordsAbout 5 min

Warning

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

Limits

Transaction Type	Limit (Unit: VND)
Collection	10,000 – 100,000,000
Disbursement	100,000 – 10,000,000

Collection API

Collection Apply

Description:

Create a Collection order.

URL：/vnd/collect/apply
Note: appId VND, amount VND, settlement VND

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 (when status=2, 4, or 5) (Vietnam time), format: yyyy-MM-dd HH:mm:ss
errorMsg	String	Failure reason (when status=3)
sign	String	Signature

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 (available when status=2) (Vietnam Time), format: yyyy-MM-dd HH:mm:ss
errorMsg	String	Payment failure reason (available when status=3)
sign	String	Signature

Bank Codes

Bank codes for BANK_ACCOUNT (Bank Card)

bankCode	bankName
VCB	Ngân hàng TMCP Ngoại Thương Việt Nam (Vietcombank)
DAB	Ngân hàng TMCP Đông Á (DongA Bank)
TCB	Ngân hàng TMCP Kỹ Thương (Techcombank)
MB	Ngân hàng TMCP Quân Đội (MB)
VIB	Ngân hàng TMCP Quốc tế (VIB)
ICB	Ngân hàng TMCP Công Thương (VietinBank)
EXB	Ngân hàng TMCP Xuất Nhập Khẩu (Eximbank)
ACB	Ngân hàng TMCP Á Châu (ACB)
HDB	Ngân hàng TMCP Phát Triển Nhà TP. Hồ Chí Minh (HDBank)
MSB	Ngân hàng TMCP Hàng Hải (MariTimeBank)
NCB	Ngân hàng TMCP Quốc dân (NCB)
VAB	Ngân hàng TMCP Việt Á (VietA Bank)
VPB	Ngân hàng TMCP Việt Nam Thịnh Vượng (VPBank)
STB	Ngân hàng TMCP Sài Gòn Thương Tín (Sacombank)
BAB	Ngân hàng TMCP Bắc Á
GPB	Ngân hàng TMCP Dầu Khí (GPBank)
AGB	Ngân hàng Nông nghiệp và Phát triển Nông thôn (Agribank)
BIDV	Ngân hàng Đầu tư và Phát triển Việt Nam (BIDV)
OJB	Ngân hàng TMCP Đại Dương (OceanBank)
PGB	Ngân Hàng TMCP Xăng Dầu Petrolimex (PGBank)
SHB	Ngân hàng TMCP Sài Gòn - Hà Nội (SHB)
TPB	Ngân hàng TMCP Tiên Phong (TienPhong Bank)
NAB	Ngân hàng Nam Á (NamABank)
SGB	Ngân hàng Sài Gòn Công Thương
ABB	Ngân hàng TMCP An Bình
SCB	Ngân hàng Thương Mại Cổ Phần Sài Gòn - SCB
IVB	Ngân hàng trách nhiệm hữu hạn Indovina
VCCB	Ngân hàng TMCP Bản Việt
OCB	Ngân hàng TMCP Phương Đông
SEA	Ngân hàng TMCP Đông Nam Á
LVB	Ngân hàng bưu điện Liên Việt
WRB	Ngân hàng WOORIL
PVCOMBANK	Ngân hàng TMCP Đại chúng Việt Nam (PVcomBank)
SHNB	Ngân hàng Shinhan
KLB	Ngân hàng Kiên Long Bank
BVB	Ngân hàng BaoVietbank
GAB	Ngân hàng Đại Á
NVB	Ngân hàng Navibank