VietQR.com

API VietQR Tài liệu kết nối và sử dụng dịch môi trường Production

Domain: https://api.vietqr.org

1. Mục tiêu môi trường Production

  • Kiểm thử tạo mã QR: Kiểm thử API tạo QR động, QR tĩnh, QR bán động.

  • Kiểm tra kết nối hệ thống: Ghi nhận dữ liệu giao dịch để xử lý dịch vụ cho khách hàng.

  • Kiểm tra giao dịch: Thử nghiệm tính năng tra cứu giao dịch.

  • Hoàn tiền (Refund): Thử nghiệm tính năng hoàn tiền cho người dùng.

Ứng dụng hỗ trợ kiểm thử: Postman

2. Các API VietQR hỗ trợ

3. Cấu hình nhận dữ liệu giao dịch

Đối tác cần cấu hình API nhận dữ liệu theo chuẩn VietQR:

4. Chi tiết các API

4.1. API Get Token VietQR

  • Thông tin truy cập: Sử dụng Account API do VietQR cung cấp.

  • Hướng dẫn: Sử dụng Authorization với thông tin tài khoản để nhận access_token (Thời hạn tối đa: 300s = 5 phút).

cURL:

curl --location --request POST 'https://api.vietqr.org/vqr/api/token_generate' \

--header 'Authorization: Basic Y3VzdG9tZXItdnNvMjIwMzBwYW5kYXBpbi11c2VyMjUyMTk6WTNWemRHOXRaWEl0ZG5Odk1qSXdNekJ3WVc1a1lYQnBiaTExYzJWeU1qVXlNVGs9'

Response:

{

    "access_token": "eyJhbGciOiJIUzUxMiJ9.eyJhdXRob3JpdGllcyI6WyJST0xFX1VTRVIiXSwidXNlciI6IlkzVnpkRzl0WlhJdGRuTnZORFU1TVRSdFpXbDBkV0Z1TFhWelpYSXlOalkxTlE9PSIsImlhdCI6MTc4NjA5NjIxMywiZXhwIjoxNzg2MDk2NTEzfQ.irXzu0G3qFOsgPJOB2OO7u2eN2itu5pwiE3EnrddhtMQaM0ldjx6vJiYffi2w_76vM2u65PBGvSRbbWr3Hs7eA",

    "token_type": "Bearer",

    "expires_in": 300

}

4.2. API Generate QR Code

Thông tin ngân hàng (Production):

  • bankAccount: 0981801381

  • bankCode: MB

  • userBankName: PHAM QUYNH ANH

QR động (qrType = 0)

QR cho từng giao dịch, gắn sẵn amount và orderId để đối soát.

Tham số bắt buộc: bankCode, bankAccount, userBankName, content (≤23 ký tự), qrType (0), amount (Số nguyên dương, không định dạng phân cách), orderId (≤13 ký tự), transType (mặc định "C").

Có thể truyền thêm: sign, urlLink, note, additionalData.

cURL:

curl --location 'https://api.vietqr.org/vqr/api/qr/generate-customer' \

--header 'Content-Type: application/json' \

--header 'Authorization: Bearer eyJhbGciOiJIUzUxMiJ9.eyJhdXRob3JpdGllcyI6WyJST0xFX1VTRVIiXSwidXNlciI6IlkzVnpkRzl0WlhJdGRuTnZORFUwTWpadGRHRnlkR3hoYm1RdGRYTmxjakkyTmpRMyIsImlhdCI6MTc4NjA2OTEzMCwiZXhwIjoxNzg2MDk5NDMwfQ.jU87Snu_LDNETZI3res1nmvPf3wxSQCKa_Fi0Yt0tGA3_dii-uc1clzL1NYmwvgBiqfEElmzINaUaXJFFuOJBw' \

--data '{

    "amount": 8000,

    "content": "Test Create QR Code",

    "bankAccount": "0981801381",

    "bankCode": "MB",

    "userBankName": "PHAM QUYNH ANH",

    "transType": "C",

    "orderId": "MEITUAN_QRTEST",

    "qrType": "0"

}'

QR Tĩnh/QR cửa hàng (qrType = 1)

QR cố định cho tài khoản nhận tiền, người dùng tự nhập số tiền.

Tham số bắt buộc: bankCode, bankAccount, userBankName, content (≤23 ký tự), qrType (1), transType ("C"), terminalCode (10 ký tự).

Lưu ý: Phải sử dụng terminalCode mới.

cURL:

curl --location 'https://api.vietqr.org/vqr/api/qr/generate-customer' \

--header 'Content-Type: application/json' \

--header 'Authorization: Bearer eyJhbGciOiJIUzUxMiJ9.eyJhdXRob3JpdGllcyI6WyJST0xFX1VTRVIiXSwidXNlciI6IlkzVnpkRzl0WlhJdGRtbGxkSEZ5ZEdWemRDMTFjMlZ5TWpRMk9BPT0iLCJpYXQiOjE3NDk3MTY1NzUsImV4cCI6MTc0OTcxNjg3NX0.XKK-PK1Y0X4-nq-h8Yjg7U8mPrt7w5nQOrLCfN9IXnqUqHr2fJikl2yBXsRv6zZXuUHmtwIjIZ9s9slIgl6FTg' \

--data '{

    "content": "Test Create QR Code",

    "bankAccount": "0981801381",

    "bankCode": "MB",

    "userBankName": "PHAM QUYNH ANH",

    "transType": "C",

    "qrType": 1,

    "terminalCode": "MEITUANQR1"

}'

QR Bán động (qrType = 3)

QR cho điểm bán, gắn thông tin cửa hàng và dịch vụ.

Tham số bắt buộc: amount, bankCode, bankAccount, userBankName, content, qrType (3), transType ("C"), terminalCode (10 ký tự), serviceCode.

Lưu ý: Phải có 1 trong 2 tham số terminalCode hoặc serviceCode mới.

cURL:

curl --location 'https://dev.vietqr.org/vqr/api/qr/generate-customer' \

--header 'Content-Type: application/json' \

--header 'Authorization: Bearer eyJhbGciOiJIUzUxMiJ9.eyJhdXRob3JpdGllcyI6WyJST0xFX1VTRVIiXSwidXNlciI6IlkzVnpkRzl0WlhJdGRuTnZNalV5TVRCd2FXNWthV1J2Ym1jdGRYTmxjakkyTkRndyIsImlhdCI6MTc2ODM4MTc4MiwiZXhwIjoxNzY4MzgyMDgyfQ.3lBR1ZWFwxnX9VlPWD5dz9Uf24UsaXk-zl9kRA3wWXCGvNAx_YcIlMog0ZJ5PmqlQDGlgIgjo8NWZVdHevIAKg' \

--data '{

    "amount": 8000,

    "content": "Test Create QR Code",

    "bankAccount": "0981801381",

    "bankCode": "MB",

    "userBankName": "PHAM QUYNH ANH",

    "transType": "C",

    "terminalCode": "MEITUANQR1",

    "serviceCode": "DICHVUPIN8K",

    "qrType": 3

}'

4.3. API Create terminalCode

Tạo mã điểm bán/cửa hàng.

Tham số bắt buộc: merchantName, terminalName, terminalCode (10 ký tự), terminalAddress, bankAccount, bankCode, checkSum (MD5: password + bankCode + bankAccount).

cURL:

curl --location 'https://dev.vietqr.org/vqr/api/tid/synchronize/v1' \

--header 'Content-Type: application/json' \

--header 'Authorization: Bearer eyJhbGciOiJIUzUxMiJ9.eyJhdXRob3JpdGllcyI6WyJST0xFX1VTRVIiXSwidXNlciI6IlkzVnpkRzl0WlhJdGJtZDFlV1Z1TFhWelpYSXlORGt5IiwiaWF0IjoxNzIwMDg4MDE3LCJleHAiOjE3MjAwODgwNzZ9.3_jljTg8llYVANJW4MVqW6YsJZbFl10r2AC66NNXCuSDWMyNYd2MlbnStNuyjHIqYDO5E5jD0izl4puPckYSyw' \

--data '{

    "terminals": [

        {

            "merchantName": "VSO45914MEITUAN",

            "terminalName": "MEITUAN TRAM SAC",

            "terminalCode": "MEITUANQR1",

            "terminalAddress": "Thu do Ha Noi",

            "bankAccount": "0981801381",

            "bankCode": "MB",

            "checkSum": "02a112fac082e2c4cd757f802be84036"

        }

    ]

}'

4.4. API Check Transaction

Tra cứu giao dịch.

Tham số bắt buộc: bankAccount, type (0: orderId; 1: referenceNumber), value, checkSum (MD5: bankAccount + username).

cURL:

curl --location 'https://api.vietqr.org/vqr/api/transactions/check-order' \

--header 'Authorization: Bearer eyJhbGciOiJIUzUxMiJ9.eyJhdXRob3JpdGllcyI6WyJST0xFX1VTRVIiXSwidXNlciI6IlkzVnpkRzl0WlhJdGRuTnZORFU1TVRSdFpXbDBkV0Z1TFhWelpYSXlOalkxTlE9PSIsImlhdCI6MTc4NjA5NzU3NiwiZXhwIjoxNzg2MDk3ODc2fQ.prAvOx0MEfRn6xEb2_w3836gLBZoB4PcSGWcnQSMQtNKceHQ4BWnNW0zaY9WTn-zSBoo-0HdcNdRrfLCVGG0tA' \

--header 'Content-Type: application/json' \

--data '{

    "bankAccount": "0981801381",

    "type": 1,

    "value": "FT26219310908830",

    "checkSum": "5b5f443bda3975965bda1ada0de721d6"

}'

4.5. API Refund

Hoàn tiền giao dịch gốc.

Tham số bắt buộc: bankCode, bankAccount, referenceNumber, amount, content, checkSum (MD5: secretKey + referenceNumber + amount + bankAccount).

cURL:

curl --location 'https://api.vietqr.org/vqr/api/transaction/refund' \

--header 'Content-Type: application/json' \

--header 'Authorization: Bearer eyJhbGciOiJIUzUxMiJ9.eyJhdXRob3JpdGllcyI6WyJST0xFX1VTRVIiXSwidXNlciI6IlkzVnpkRzl0WlhJdGRuTnZORFU1TVRSdFpXbDBkV0Z1TFhWelpYSXlOalkxTlE9PSIsImlhdCI6MTc4NjA5ODcwNywiZXhwIjoxNzg2MDk5MDA3fQ.zFy_EJEaP38i941nzbEikPu-IhximmoRjPoyNdCizrGy4rN8cy-HpcwBxLgn3TzPeRuXOixfY8mnln9T6E1cug' \

--data '{

    "bankCode": "MB",

    "bankAccount": "0981801381",

    "referenceNumber": "FT26219310908830",

    "amount": "7999",

    "content": "Refund FT26219310908830",

    "checkSum": "96bbd360c3e882a100564c9d74242095"

}'

Lưu ý: Phản hồi trả về message là mã giao dịch hoàn tiền. VietQR sử dụng transType: D (Debit) cho các giao dịch chuyển đi.

5. Luồng xử lý bất thường

  • QR hết hạn: QR động tồn tại trong 15 phút. Sau khi thanh toán hoặc quá thời gian, mã không còn hiệu lực.

  • Quét/lặp thanh toán: QR động không thể thanh toán lại. QR tĩnh/bán động có thể quét lại.

  • Callback mất gói: Có thể do cấu hình sai, bảo trì hệ thống, hoặc cao tải.

  • Refund thất bại & Cơ chế Retry: Cần kiểm tra lại với phía ngân hàng. Hệ thống VietQR tự động retry callback 10 lần trong 5 phút nếu xảy ra lỗi.