1. Overview

Basic Information
  • Request Method: POST
  • Data Format: JSON
  • Character Encoding: UTF-8
  • Signature Algorithm: MD5
Important
  • All requests must include the sign parameter
  • Request IP must be in the merchant whitelist

2. Signature Algorithm

All API requests require signature verification.

2.1 Signature Steps

  1. Convert request params (except sign) to map
  2. Exclude empty strings and sign field
  3. Sort params by key (ASCII ascending)
  4. Concatenate as key=value&key=value
  5. Append &key=merchant_secret
  6. MD5 hash the string
  7. Convert to lowercase hex

2.2 Example Code

package main

import (
    "crypto/md5"
    "encoding/hex"
    "fmt"
    "sort"
    "strings"
)

func CalculateSign(params map[string]interface{}, secretKey string) string {
    keys := make([]string, 0, len(params))
    for k, v := range params {
        if strings.EqualFold(k, "sign") {
            continue
        }
        if s, ok := v.(string); ok && s == "" {
            continue
        }
        keys = append(keys, k)
    }
    sort.Strings(keys)

    var builder strings.Builder
    for i, k := range keys {
        if i > 0 {
            builder.WriteString("&")
        }
        builder.WriteString(fmt.Sprintf("%s=%v", k, params[k]))
    }
    builder.WriteString("&key=" + secretKey)

    sum := md5.Sum([]byte(builder.String()))
    return hex.EncodeToString(sum[:])
}
<?php
function calculateSign(array $params, string $secretKey): string {
    unset($params['sign']);

    foreach ($params as $k => $v) {
        if ($v === '') {
            unset($params[$k]);
        }
    }

    ksort($params, SORT_STRING);

    $pairs = [];
    foreach ($params as $k => $v) {
        $pairs[] = $k . '=' . $v;
    }

    $signStr = implode('&', $pairs) . '&key=' . $secretKey;
    return strtolower(md5($signStr));
}
?>
import java.nio.charset.StandardCharsets;
import java.security.MessageDigest;
import java.util.*;

public class SignUtil {
    public static String calculateSign(Map<String, Object> params, String secretKey) {
        Map<String, Object> filtered = new TreeMap<>();
        for (Map.Entry<String, Object> e : params.entrySet()) {
            String key = e.getKey();
            Object val = e.getValue();
            if ("sign".equalsIgnoreCase(key)) continue;
            if (val instanceof String && ((String) val).isEmpty()) continue;
            filtered.put(key, val);
        }

        StringBuilder sb = new StringBuilder();
        int i = 0;
        for (Map.Entry<String, Object> e : filtered.entrySet()) {
            if (i++ > 0) sb.append("&");
            sb.append(e.getKey()).append("=").append(e.getValue());
        }
        sb.append("&key=").append(secretKey);

        return md5Lower(sb.toString());
    }

    private static String md5Lower(String text) {
        try {
            MessageDigest md = MessageDigest.getInstance("MD5");
            byte[] digest = md.digest(text.getBytes(StandardCharsets.UTF_8));
            StringBuilder out = new StringBuilder();
            for (byte b : digest) out.append(String.format("%02x", b));
            return out.toString();
        } catch (Exception ex) {
            throw new RuntimeException(ex);
        }
    }
}
Notes
  • Empty string params are excluded
  • sign field is excluded
  • Convert values by original type
  • Final sign must be lowercase

3.1 Create Collection Order

POST

Request Parameters

ParameterTypeRequiredDescription
mchIdstringYesMerchant ID
mchOrderIdstringYesMerchant order ID
amountstringYesOrder amount
payTypestringYesPayment type
notifyUrlstringYesCallback URL
bankCodestringNoBank code when payType=banktransfer
remarkstringNoRemark
signstringYesSignature
amount parameter note
When payType=usdt, amount is in VND. Callback amount is also in VND, and remark must be the user's unique ID.

Request Example

{
    "mchId": "100001",
    "mchOrderId": "ORDER20240101001",
    "amount": "100.00",
    "payType": "vnbankqr",
    "notifyUrl": "https://example.com/notify",
    "remark": "Test",
    "sign": "a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6"
}

Response Parameters

ParameterTypeDescription
codeintStatus code
messagestringMessage
dataobjectResponse data
  └─ payUrlstringFormat
  └─ extraobjectAdditional info, key-value map structure (e.g. qrcode, amount, bank info)
      ├─ banknamestringBank name
      ├─ bankaccountstringBank account number
      ├─ bankownerstringAccount holder / payee name
      ├─ qrcodestringQR code string
      └─ amountstringOrder amount

Response Example

Production

{
    "code": 200,
    "message": "success",
    "data": {
        "payUrl": "{{baseOrigin}}?orderid=PLATFORM_ORDER_123456",
        "extra": {
            "bankname": "Vietcombank",
            "bankaccount": "1234567890",
            "bankowner": "NGUYEN VAN A",
            "qrcode": "https://...",
            "amount": "100.00"
        }
    }
}
Note
  • Channel details via query order API
  • Query returns details per channel

3.2 Create Collection Order - Self-Service Cashier

Self-service cashier dedicated API. Returns payee info (bankname, bankaccount, bankowner, qrcode, amount, remark) for upstream to build custom cashier. Does not return payUrl.

POST

Request Parameters

ParameterTypeRequiredDescription
mchIdstringYesMerchant ID
mchOrderIdstringYesMerchant order ID
amountstringYesOrder amount
payTypestringYesPayment type
notifyUrlstringYesCallback URL
bankCodestringNoBank code when payType=banktransfer
remarkstringNoRemark
signstringYesSignature

Response Parameters

ParameterTypeDescription
codeintStatus code
messagestringMessage
dataobjectPayee info for cashier
  └─ banknamestringBank/wallet name
  └─ bankaccountstringBank account or phone number
  └─ bankownerstringAccount holder / payee name
  └─ qrcodestringQR code string or scheme URI
  └─ amountstringOrder amount
  └─ remarkstringTransfer remark code (match_code) or platform order ID
  └─ time_leftintRemaining seconds until expiry (momo only)

Data Parameters by Payment Type

Parameters differ by payType:

payTypedata field mapping
banktransfer
bankqr
bankname=bank name, bankaccount=bank account, bankowner=account holder, qrcode=QR image, amount=amount, remark=platform orderId. No time_left.
momobankname=momo, bankaccount=phone_number, bankowner=full_name, qrcode=qr_code, amount=amount, remark=match_code, time_left=remaining seconds (countdown required).
momobank
zalobank
viettelbank
Same as bankqr. No time_left.
time_left Note
Only momo has expiry countdown. For momo, implement countdown timer using time_left (seconds). For bank QR / banktransfer, time_left is not returned.

Request Example

{
    "mchId": "100001",
    "mchOrderId": "ORDER20240101002",
    "amount": "100.00",
    "payType": "bankqr",
    "notifyUrl": "https://example.com/notify",
    "sign": "a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6"
}

Response Example

bankqr or banktransfer

{
    "code": 200,
    "message": "success",
    "data": {
        "bankname": "Vietcombank",
        "bankaccount": "1234567890",
        "bankowner": "NGUYEN VAN A",
        "qrcode": "https://...",
        "amount": "100.00",
        "remark": "PLATFORM_ORDER_xxx"
    }
}

momo (with time_left):

{
    "code": 200,
    "message": "success",
    "data": {
        "bankname": "momo",
        "bankaccount": "0912345678",
        "bankowner": "NGUYEN VAN A",
        "qrcode": "momo://...",
        "amount": "100.00",
        "remark": "ABC123",
        "time_left": 580
    }
}

3.3 Query Collection Order

POST

Request Parameters

ParameterTypeRequiredDescription
mchIdstringYesMerchant ID
mchOrderIdstringYesMerchant order ID
signstringYesSignature

Response Parameters

ParameterTypeDescription
codeintStatus code
messagestringMessage
dataobjectOrder data
  └─ isPaidintPayment status
  └─ amountstringOrder amount
  └─ payAmountstringActual paid amount
  └─ paidAtstringPaid time

4.1 Create Payout Order

POST

Request Parameters

ParameterTypeRequiredDescription
mchIdstringYesMerchant ID
mchOrderIdstringYesMerchant order ID
payTypestringYesPayout type
payCodestringYesBank code
accountstringYesAccount
ownerstringYesOwner
amountstringYesAmount
notifyUrlstringYesCallback URL
qrCodestringNoQR code
remarkstringNoRemark
signstringYesSignature
Important
  • Payout only supports vnbank
  • Must fill account, owner, payCode

Response Parameters

ParameterTypeDescription
codeintStatus code
messagestringMessage
orderidstringPlatform order ID

4.2 Query Payout Order

POST

Request Parameters

ParameterTypeRequiredDescription
mchIdstringYesMerchant ID
mchOrderIdstringYesMerchant order ID
signstringYesSignature

Response Parameters

ParameterTypeDescription
codeintStatus code
messagestringMessage
dataobjectOrder data
  └─ isPaidint0=未支付, 1=成功, 2=订单被驳回拒绝
  └─ amountstringOrder amount
  └─ paidAtstringPaid time

6. Query Merchant Balance

Query merchant total balance. Signature algorithm is the same as create order.

POST

Request Parameters

ParameterTypeRequiredDescription
mchIdstringYesMerchant ID
signstringYesSignature

Request Example

{
    "mchId": "100001",
    "sign": "a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6"
}

Response Parameters

ParameterTypeDescription
codeintStatus code
messagestringMessage
dataobjectResponse data
  └─ balancestringAvailable balance, 2 decimal places

Response Example

{"code":200,"message":"success","data":{"balance":"12345.67"}}

5.1 Collection Callback

Callback is sent when collection order is paid successfully.

Callback Parameters

ParameterTypeDescription
mchIdstringMerchant ID
mchOrderIdstringMerchant order ID
amountstringOrder amount
payAmountstringActual paid amount
isPaidintPayment status
payerNamestringPayer name
signstringSignature
Callback Notes
  • payerName is optional, only present when payer info is available
  • Callback is sent via POST
  • Merchant must verify signature
  • Return "success" string, otherwise system retries
  • Implement idempotency to avoid duplicate processing

Response Example

{
  "mchId": "100001",
  "mchOrderId": "ORDER20240101001",
  "amount": "100",
  "payAmount": "100",
  "isPaid": 1,
  "payerName": "NGUYEN VAN A",
  "sign": "a1b2c3d4e5f6g7h8i9j0"
}

5.2 Payout Callback

Callback is sent when payout order status changes.

Callback Parameters

ParameterTypeDescription
mchIdstringMerchant ID
mchOrderIdstringMerchant order ID
amountstringOrder amount
isPaidint2=成功, -2=订单被驳回拒绝
signstringSignature
Callback Notes
  • Callback is sent via POST
  • Verify signature
  • Return "success"
  • Implement idempotency

Response Example

{
  "mchId": "100001",
  "mchOrderId": "PAYOUT20240101001",
  "amount": "100",
  "isPaid": 2,
  "sign": "a1b2c3d4e5f6g7h8i9j0"
}

7. Collection Payment Types

payType Description
banktransferBank transfer
bankqrBank QR
momobankMoMo to bank
zalobankZalo to bank
viettelbankViettel to bank
momoMoMo
zaloZaloPay
viettelpayViettel wallet
scratchcardScratch card
usdtUSDT

8. Payout Payment Types

Payout payType list.

payType Description
vnbank Bank transfer

9. Collection Bank Codes(接口传银行编码)

Bank NameBINBank Code
Techcombank
Ngân hàng TMCP Kỹ thương Việt Nam
970407 TCB
IBK
Ngân hàng Công nghiệp Hàn Quốc (IBK)
970455 IBK
IBKHCM
Ngân hàng Công nghiệp Hàn Quốc - Chi nhánh TP. Hồ Chí Minh
970456 IBKHCM
KookminHN
Ngân hàng Kookmin - Chi nhánh Hà Nội
970462 KOOKMI
KookminHCM
Ngân hàng Kookmin - Chi nhánh Thành phố Hồ Chí Minh
970463 KBHCM
VRB
Ngân hàng Liên doanh Việt - Nga
970421 VRB
Agribank
Ngân hàng Nông nghiệp và Phát triển Nông thôn Việt Nam
970405 AGB
ACB
Ngân hàng TMCP Á Châu
970416 ACB
ABBANK
Ngân hàng TMCP An Bình
970425 ABB
BacABank
Ngân hàng TMCP Bắc Á
970409 NASB
VietCapitalBank
Ngân hàng TMCP Bản Việt
970454 VCPB
BaoVietBank
Ngân hàng TMCP Bảo Việt
970438 BVB
LPBank
Ngân hàng TMCP Lộc Phát Việt Nam
970449 LPB
VietinBank
Ngân hàng TMCP Công thương Việt Nam
970415 VTB
PVcomBank
Ngân hàng TMCP Đại Chúng Việt Nam
970412 PVCB
OceanBank
Ngân hàng TMCP Đại Dương
970414 OJB
GPBank
Ngân hàng Thương mại TNHH MTV Dầu Khí Toàn Cầu
970408 GPB
BIDV
Ngân hàng TMCP Đầu tư và Phát triển Việt Nam
970418 BIDV
SeABank
Ngân hàng TMCP Đông Nam Á
970440 SEAB
MSB
Ngân hàng TMCP Hàng Hải Việt Nam
970426 MSB
KienLongBank
Ngân hàng TMCP Kiên Long
970452 KLB
NamABank
Ngân hàng TMCP Nam Á
970428 NAMABA
Vietcombank
Ngân hàng TMCP Ngoại Thương Việt Nam
970436 VCB
HDBank
Ngân hàng TMCP Phát triển Thành phố Hồ Chí Minh
970437 HDB
OCB
Ngân hàng TMCP Phương Đông
970448 OCB
MBBank
Ngân hàng TMCP Quân đội
970422 MB
NCB
Ngân hàng TMCP Quốc Dân
970419 NCB
SCB
Ngân hàng TMCP Sài Gòn
970429 SCB
SHB
Ngân hàng TMCP Sài Gòn - Hà Nội
970443 SHB
SaigonBank
Ngân hàng TMCP Sài Gòn Công Thương
970400 SGN
Sacombank
Ngân hàng TMCP Sài Gòn Thương Tín
970403 SACB
TPBank
Ngân hàng TMCP Tiên Phong
970423 TPB
VietABank
Ngân hàng TMCP Việt Á
970427 VAB
VPBank
Ngân hàng TMCP Việt Nam Thịnh Vượng
970432 VPB
CAKE
TMCP Việt Nam Thịnh Vượng - Ngân hàng số CAKE by VPBank
546034 CAKE
Ubank
TMCP Việt Nam Thịnh Vượng - Ngân hàng số Ubank by VPBank
546035 UBANK
VietBank
Ngân hàng TMCP Việt Nam Thương Tín
970433 VB
PGBank
Ngân hàng TMCP Thịnh vượng và Phát triển
970430 PGB
Eximbank
Ngân hàng TMCP Xuất Nhập khẩu Việt Nam
970431 EXB
IndovinaBank
Ngân hàng TNHH Indovina
970434 IVB
CIMB
Ngân hàng TNHH MTV CIMB Việt Nam
422589 CIMB
HongLeong
Ngân hàng TNHH MTV Hong Leong Việt Nam
970442 HLB
PublicBank
Ngân hàng TNHH MTV Public Việt Nam
970439 VID
ShinhanBank
Ngân hàng TNHH MTV Shinhan Việt Nam
970424 SHBVN
StandardChartered
Ngân hàng TNHH MTV Standard Chartered Bank Việt Nam
970410 SCVN
UnitedOverseas
Ngân hàng United Overseas - Chi nhánh TP. Hồ Chí Minh
970458 UOB
Woori
Ngân hàng TNHH MTV Woori Việt Nam
970457 WOO
CBBank
Ngân hàng Thương mại TNHH MTV Xây dựng Việt Nam
970444 CBBANK
VIB
Ngân hàng TMCP Quốc tế Việt Nam
970441 VIB
Timo
Ngân hàng số Timo by Ban Viet Bank (Timo by Ban Viet Bank)
963388 Timo
KBank
Ngân hàng Đại chúng TNHH Kasikornbank
668888 KBANK
KEBHANAHN
Ngân hàng KEB Hana – Chi nhánh Hà Nội
970467 NKEB
KEBHanaHCM
Ngân hàng KEB Hana – Chi nhánh Thành phố Hồ Chí Minh
970466 HKEB
MBV
Ngân hàng TNHH MTV Việt Nam Hiện Đại
970414 MBV
Vikki
Ngân hàng TNHH MTV Số Vikki
970406 Vikki
VCBNeo
Ngân hàng TNHH MTV Ngoại thương Công nghệ số
970444 VCBNeo
COOPBANK
Ngân hàng Hợp tác xã Việt Nam
970446 COOP
Liobank
Liobank
970448 LIO
MoMo
CTCP Dịch Vụ Di Động Trực Tuyến
971025 MOMO
ZaloPay
ZaloPay
- ZALOPAY
ViettelMoney
Tổng Công ty Dịch vụ số Viettel - Chi nhánh tập đoàn công nghiệp viễn thông Quân Đội
971005 VTPAY
VNPTMoney
VNPT Money
971011 VNPTMONEY
PVcomBank Pay
Ngân hàng TMCP Đại Chúng Việt Nam Ngân hàng số
971133 PVDB
MAFC
Công ty Tài chính TNHH MTV Mirae Asset (Việt Nam)
977777 MAFC
Citibank
Ngân hàng Citibank, N.A. - Chi nhánh Hà Nội
533948 CITIBANK
DBSBank
DBS Bank Ltd - Chi nhánh Thành phố Hồ Chí Minh
796500 DBS
VBSP
Ngân hàng Chính sách Xã hội
999888 VBSP
HSBC
Ngân hàng TNHH MTV HSBC (Việt Nam)
458761 HSBC
Nonghyup
Ngân hàng Nonghyup - Chi nhánh Hà Nội
801011 NHBHN

10. 代付银行编码(接口传银行编码)

Bank NameBINBank Code
Techcombank
Ngân hàng TMCP Kỹ thương Việt Nam
970407 TCB
IBK
Ngân hàng Công nghiệp Hàn Quốc (IBK)
970455 IBK
IBKHCM
Ngân hàng Công nghiệp Hàn Quốc - Chi nhánh TP. Hồ Chí Minh
970456 IBKHCM
KookminHN
Ngân hàng Kookmin - Chi nhánh Hà Nội
970462 KOOKMI
KookminHCM
Ngân hàng Kookmin - Chi nhánh Thành phố Hồ Chí Minh
970463 KBHCM
VRB
Ngân hàng Liên doanh Việt - Nga
970421 VRB
Agribank
Ngân hàng Nông nghiệp và Phát triển Nông thôn Việt Nam
970405 AGB
ACB
Ngân hàng TMCP Á Châu
970416 ACB
ABBANK
Ngân hàng TMCP An Bình
970425 ABB
BacABank
Ngân hàng TMCP Bắc Á
970409 NASB
VietCapitalBank
Ngân hàng TMCP Bản Việt
970454 VCPB
BaoVietBank
Ngân hàng TMCP Bảo Việt
970438 BVB
LPBank
Ngân hàng TMCP Lộc Phát Việt Nam
970449 LPB
VietinBank
Ngân hàng TMCP Công thương Việt Nam
970415 VTB
PVcomBank
Ngân hàng TMCP Đại Chúng Việt Nam
970412 PVCB
OceanBank
Ngân hàng TMCP Đại Dương
970414 OJB
GPBank
Ngân hàng Thương mại TNHH MTV Dầu Khí Toàn Cầu
970408 GPB
BIDV
Ngân hàng TMCP Đầu tư và Phát triển Việt Nam
970418 BIDV
SeABank
Ngân hàng TMCP Đông Nam Á
970440 SEAB
MSB
Ngân hàng TMCP Hàng Hải Việt Nam
970426 MSB
KienLongBank
Ngân hàng TMCP Kiên Long
970452 KLB
NamABank
Ngân hàng TMCP Nam Á
970428 NAMABA
Vietcombank
Ngân hàng TMCP Ngoại Thương Việt Nam
970436 VCB
HDBank
Ngân hàng TMCP Phát triển Thành phố Hồ Chí Minh
970437 HDB
OCB
Ngân hàng TMCP Phương Đông
970448 OCB
MBBank
Ngân hàng TMCP Quân đội
970422 MB
NCB
Ngân hàng TMCP Quốc Dân
970419 NCB
SCB
Ngân hàng TMCP Sài Gòn
970429 SCB
SHB
Ngân hàng TMCP Sài Gòn - Hà Nội
970443 SHB
SaigonBank
Ngân hàng TMCP Sài Gòn Công Thương
970400 SGN
Sacombank
Ngân hàng TMCP Sài Gòn Thương Tín
970403 SACB
TPBank
Ngân hàng TMCP Tiên Phong
970423 TPB
VietABank
Ngân hàng TMCP Việt Á
970427 VAB
VPBank
Ngân hàng TMCP Việt Nam Thịnh Vượng
970432 VPB
CAKE
TMCP Việt Nam Thịnh Vượng - Ngân hàng số CAKE by VPBank
546034 CAKE
Ubank
TMCP Việt Nam Thịnh Vượng - Ngân hàng số Ubank by VPBank
546035 UBANK
VietBank
Ngân hàng TMCP Việt Nam Thương Tín
970433 VB
PGBank
Ngân hàng TMCP Thịnh vượng và Phát triển
970430 PGB
Eximbank
Ngân hàng TMCP Xuất Nhập khẩu Việt Nam
970431 EXB
IndovinaBank
Ngân hàng TNHH Indovina
970434 IVB
CIMB
Ngân hàng TNHH MTV CIMB Việt Nam
422589 CIMB
HongLeong
Ngân hàng TNHH MTV Hong Leong Việt Nam
970442 HLB
PublicBank
Ngân hàng TNHH MTV Public Việt Nam
970439 VID
ShinhanBank
Ngân hàng TNHH MTV Shinhan Việt Nam
970424 SHBVN
StandardChartered
Ngân hàng TNHH MTV Standard Chartered Bank Việt Nam
970410 SCVN
UnitedOverseas
Ngân hàng United Overseas - Chi nhánh TP. Hồ Chí Minh
970458 UOB
Woori
Ngân hàng TNHH MTV Woori Việt Nam
970457 WOO
CBBank
Ngân hàng Thương mại TNHH MTV Xây dựng Việt Nam
970444 CBBANK
VIB
Ngân hàng TMCP Quốc tế Việt Nam
970441 VIB
Timo
Ngân hàng số Timo by Ban Viet Bank (Timo by Ban Viet Bank)
963388 Timo
KBank
Ngân hàng Đại chúng TNHH Kasikornbank
668888 KBANK
KEBHANAHN
Ngân hàng KEB Hana – Chi nhánh Hà Nội
970467 NKEB
KEBHanaHCM
Ngân hàng KEB Hana – Chi nhánh Thành phố Hồ Chí Minh
970466 HKEB
MBV
Ngân hàng TNHH MTV Việt Nam Hiện Đại
970414 MBV
Vikki
Ngân hàng TNHH MTV Số Vikki
970406 Vikki
VCBNeo
Ngân hàng TNHH MTV Ngoại thương Công nghệ số
970444 VCBNeo
COOPBANK
Ngân hàng Hợp tác xã Việt Nam
970446 COOP
Liobank
Liobank
970448 LIO
MoMo
CTCP Dịch Vụ Di Động Trực Tuyến
971025 MOMO
ZaloPay
ZaloPay
- ZALOPAY
ViettelMoney
Tổng Công ty Dịch vụ số Viettel - Chi nhánh tập đoàn công nghiệp viễn thông Quân Đội
971005 VTPAY
VNPTMoney
VNPT Money
971011 VNPTMONEY
PVcomBank Pay
Ngân hàng TMCP Đại Chúng Việt Nam Ngân hàng số
971133 PVDB
MAFC
Công ty Tài chính TNHH MTV Mirae Asset (Việt Nam)
977777 MAFC
Citibank
Ngân hàng Citibank, N.A. - Chi nhánh Hà Nội
533948 CITIBANK
DBSBank
DBS Bank Ltd - Chi nhánh Thành phố Hồ Chí Minh
796500 DBS
VBSP
Ngân hàng Chính sách Xã hội
999888 VBSP
HSBC
Ngân hàng TNHH MTV HSBC (Việt Nam)
458761 HSBC
Nonghyup
Ngân hàng Nonghyup - Chi nhánh Hà Nội
801011 NHBHN

11. Error Codes

Error CodeDescription
200Success
402Parameter error
403Invalid merchant
406IP/order
407Insufficient balance
409Signature error
410Token/QR failed
411QR parse failed
412Create failed
427Balance query failed