Thông tin tài liệu

文档信息

Nội dung

内容

Mục lục là trường tự động của Microsoft Word. Nếu hiển thị trống, nhấn Ctrl+A rồi F9 để cập nhật.

目录为 Microsoft Word 自动字段。若显示为空，请按 Ctrl+A 后按 F9 更新。

Đây là hướng dẫn thực hành, mô tả trình tự các bước cần làm để đưa dịch vụ thanh toán VietQR vào hệ thống của Đối tác.

Tài liệu này không thay thế bản đặc tả kỹ thuật. Đặc tả mô tả từng API có những trường nào; hướng dẫn này mô tả thứ tự làm, cách làm, và những chỗ dễ sai.

Khi cần tra cứu chi tiết trường dữ liệu, giới hạn độ dài hay mẫu phản hồi đầy đủ, hãy dùng tài liệu BLC-API-SPEC-PROD-VIETQR v1.0.

本文档是实操指南，说明将 VietQR 支付服务接入合作伙伴系统所需的步骤顺序。

本文档不能替代技术规范文档。技术规范说明每个接口包含哪些字段；本指南说明按什么顺序做、怎么做，以及哪些地方容易出错。

如需查阅字段明细、长度限制或完整响应示例，请参阅 BLC-API-SPEC-PROD-VIETQR v1.0。

Hạng mục

项目

Mô tả

说明

Nguồn cấp

提供方

Quy tắc bảo mật quan trọng nhất

Mật khẩu của VietQR được sinh ra từ chính tên đăng nhập theo quy tắc base64. Vì vậy, lộ username đồng nghĩa với lộ password.

Phải đối xử với cặp username và password như một bí mật duy nhất: không đưa vào mã nguồn, không lưu trong kho mã, không ghi vào nhật ký, không đưa vào tài liệu hay thư điện tử.

最重要的安全规则

VietQR 的密码由用户名按 base64 规则生成。因此，泄露 username 等同于泄露 password。

必须将 username 与 password 视为同一个机密：不得写入源代码、不得提交到代码仓库、不得记入日志、不得写入文档或电子邮件。

1.  Callback không phải kênh duy nhất. Có tình huống ngân hàng không báo giao dịch sang VietQR; khi đó VietQR không có gì để gửi cho Đối tác. Hệ thống bắt buộc phải có tác vụ đối soát chủ động, xem Bước 4.

2.  Callback sẽ đến trùng. VietQR thử lại 10 lần trong 5 phút khi gặp lỗi. Cơ chế chống trùng ở tầng cơ sở dữ liệu là bắt buộc, không phải tùy chọn.

3.  Sandbox và Production không giống nhau. Hai môi trường dùng mô hình đối soát khác nhau, và một số API chỉ tồn tại ở một môi trường. Xem Mục 9.

1.  回调不是唯一通道。存在银行未将交易通知 VietQR 的情况，此时 VietQR 没有数据可推送给合作伙伴。系统必须具备主动对账任务，详见步骤四。

2.  回调一定会重复到达。VietQR 在失败时会在 5 分钟内重试 10 次。数据库层的幂等去重机制是必须项，而非可选项。

3.  沙箱与生产环境并不一致。两个环境采用不同的对账模型，且部分接口仅存在于其中一个环境。详见第 9 章。

Trình tự dưới đây được thiết kế để mỗi giai đoạn đều có kết quả kiểm chứng được trước khi sang giai đoạn kế tiếp. Không nên làm song song các giai đoạn 1 đến 3.

以下顺序的设计原则是：每个阶段都能得到可验证的结果后再进入下一阶段。不建议并行推进第 1 至第 3 阶段。

GĐ

阶段

Nội dung

内容

Môi trường

环境

Tiêu chí hoàn thành

完成标准

Vì sao giai đoạn 4 và 5 phải làm trên Production

API Check Transaction và API Refund không tồn tại trên Sandbox. Đây là hạn chế của dịch vụ, không phải lựa chọn thiết kế của Đối tác.

Khuyến nghị dự trù một khoản ngân sách nhỏ để chạy kiểm thử bằng giao dịch tiền thật giá trị thấp trong giai đoạn nghiệm thu, trước khi mở dịch vụ cho người dùng cuối.

为什么第 4、5 阶段必须在生产环境进行

交易查询接口与退款接口在沙箱环境中不存在。这是服务本身的限制，而非合作伙伴的设计取舍。

建议预留少量预算，在验收阶段用小额真实交易完成测试，然后再对最终用户开放服务。

Bảng dưới là nhận định của Bluecom dựa trên kinh nghiệm tích hợp cổng thanh toán nói chung, dùng để tham khảo khi lập kế hoạch. Đây không phải cam kết tiến độ.

下表为 Bluecom 基于支付网关集成经验给出的判断，仅供排期参考，不构成进度承诺。

Giai đoạn

阶段

Ghi chú

备注

Đây là điểm sai nhiều nhất khi bắt đầu. Mật khẩu không phải một chuỗi ngẫu nhiên do VietQR cấp phát riêng, mà chính là tên đăng nhập được mã hóa base64.

这是接入初期最容易出错的地方。密码并不是 VietQR 单独分配的随机字符串，而是用户名经 base64 编码后的结果。

password      = base64(username)

Authorization = "Basic " + base64(username + ":" + password)

// Java

String password = Base64.getEncoder()

        .encodeToString(username.getBytes(StandardCharsets.UTF_8));

String basic = Base64.getEncoder()

        .encodeToString((username + ":" + password).getBytes(StandardCharsets.UTF_8));

headers.set("Authorization", "Basic " + basic);

# Python

password = base64.b64encode(username.encode()).decode()

basic    = base64.b64encode(f"{username}:{password}".encode()).decode()

headers  = {"Authorization": f"Basic {basic}"}

Token có hiệu lực 300 giây. Không gọi Get Token trước mỗi request nghiệp vụ, vì cách làm đó nhân đôi số lượng request và làm tăng độ trễ không cần thiết.

Yêu cầu triển khai

• Cache token trong bộ nhớ tiến trình và tái sử dụng.

• Chủ động làm mới khi token còn 30 đến 60 giây hiệu lực, thay vì đợi đến khi nhận lỗi.

• Dùng khóa đồng bộ quanh thao tác làm mới, tránh nhiều luồng cùng gọi Get Token.

• Khi gặp lỗi xác thực, làm mới token và thử lại đúng một lần. Thất bại tiếp thì ghi nhật ký và cảnh báo, không thử lại vô hạn.

• Không ghi token vào nhật ký ở bất kỳ mức nào.

令牌有效期为 300 秒。不要在每次业务请求前都调用 Get Token，因为这种做法会使请求量翻倍，并带来不必要的延迟。

实现要求

• 将令牌缓存在进程内存中并复用。

• 在令牌剩余 30 至 60 秒有效期时主动刷新，而不是等到报错后再处理。

• 刷新操作需加同步锁，避免多线程同时调用 Get Token。

• 遇到鉴权失败时，刷新令牌并只重试一次。若再次失败则记录日志并告警，不得无限重试。

• 任何日志级别下都不得记录令牌内容。

Lưu ý về mã lỗi

VietQR chưa cung cấp bảng mã lỗi. Trong giai đoạn kiểm thử Sandbox, hãy ghi lại nguyên văn mọi phản hồi khác HTTP 200 kèm phần thân phản hồi.

Tập hợp các bản ghi này chính là bảng mã lỗi thực nghiệm, hiện là nguồn thông tin đáng tin cậy nhất mà Đối tác có.

关于错误码的提示

VietQR 尚未提供错误码对照表。在沙箱测试阶段，请原样记录所有非 HTTP 200 的响应及其响应体。

这些记录汇总起来即为实测错误码表，目前这是合作伙伴能获得的最可靠信息来源。

Quyết định này ảnh hưởng trực tiếp đến khả năng đối soát tự động và phải được chốt trước khi viết mã.

该决策直接影响自动对账能力，必须在编码前确定。

Tiêu chí

对比项

QR động (0)

动态码（0）

QR tĩnh (1)

静态码（1）

QR bán động (3)

半动态码（3）

Khuyến nghị của Bluecom

Nếu nghiệp vụ cần đối soát chính xác đến từng đơn hàng, QR động là lựa chọn duy nhất phù hợp.

Với QR tĩnh và QR bán động, dữ liệu callback không mang orderId. Hệ thống sẽ phải suy luận đơn hàng từ tổ hợp số tiền, thời điểm và điểm bán. Cơ chế này không đảm bảo chính xác khi có hai giao dịch cùng số tiền phát sinh gần nhau.

Bluecom 的建议

若业务需要精确到每一笔订单的对账，动态码是唯一合适的选择。

静态码与半动态码的回调数据不携带 orderId。系统只能通过金额、时间和门店的组合来推断订单。当两笔金额相同的交易在相近时间发生时，该方式无法保证准确。

Trường

字段

Ràng buộc

约束

Ví dụ

示例

Trường qrCode trong phản hồi là một chuỗi dữ liệu theo chuẩn EMVCo. Đối tác tự dựng ảnh QR từ chuỗi này bằng thư viện mã QR bất kỳ.

Lưu ý khi dựng ảnh

• Mã hóa chuỗi ở chế độ văn bản, không thêm khoảng trắng hay ký tự xuống dòng.

• Mức sửa lỗi khuyến nghị là M hoặc Q. Mức H làm mã dày hơn, khó quét trên màn hình nhỏ.

• Chừa vùng trắng viền quanh mã. Thiếu vùng trắng là nguyên nhân phổ biến khiến ứng dụng ngân hàng không quét được.

• Kích thước hiển thị tối thiểu khuyến nghị là 200 x 200 điểm ảnh.

响应中的 qrCode 字段是一串符合 EMVCo 标准的数据。合作伙伴使用任意二维码库自行生成图片即可。

生成图片时的注意事项

• 以文本模式编码该字符串，不要添加空格或换行符。

• 建议纠错级别选择 M 或 Q。级别 H 会使码型过密，在小屏幕上不易扫描。

• 务必保留二维码四周的静默区，即白边。缺少白边是银行 App 扫不出码的常见原因。

• 建议屏幕上的最小显示尺寸为 200 × 200 像素。

Kiểm chứng nhanh trước khi viết tiếp

Dựng ảnh QR, mở ứng dụng ngân hàng bất kỳ và quét thử. Nếu ứng dụng hiển thị đúng tài khoản thụ hưởng và đúng số tiền, bước 2 đã hoàn thành.

Không xác nhận thanh toán ở bước kiểm chứng này.

继续编码前的快速验证

生成二维码图片，用任意银行 App 试扫。若 App 正确显示收款账户和金额，则步骤二已完成。

在此验证环节中请勿确认支付。

Ở các bước trước, hệ thống Đối tác là bên gọi. Trong luồng callback, VietQR là bên gọi và Đối tác là bên cung cấp dịch vụ.

Đối tác phải tự xây dựng và công bố hai endpoint: một endpoint để VietQR lấy token truy cập hệ thống Đối tác, và một endpoint để VietQR đẩy dữ liệu giao dịch.

在前面的步骤中，合作伙伴系统是调用方。而在回调流程中，VietQR 是调用方，合作伙伴是服务提供方。

合作伙伴需自行搭建并对外提供两个接口：一个供 VietQR 获取访问合作伙伴系统的令牌，另一个供 VietQR 推送交易数据。

Hạng mục cần VietQR cung cấp trước khi bắt đầu bước này

VietQR hiện chỉ cung cấp đường dẫn tham chiếu tới đặc tả của hai endpoint này, chưa cung cấp nội dung đặc tả bằng văn bản.

Bluecom không dựng payload mẫu giả định, vì một cấu trúc callback tự chế sẽ dẫn đến việc xây dựng sai endpoint và chỉ phát hiện ra khi đã tích hợp xong.

Khuyến nghị coi việc nhận được đặc tả này là điều kiện tiên quyết trước khi cam kết tiến độ. Xem Phụ lục B, mục A-01.

开始本步骤前需 VietQR 提供的内容

VietQR 目前仅提供了这两个接口规范的参考链接，尚未提供书面规范内容。

Bluecom 不会自行编造示例报文，因为凭空拟定的回调结构会导致接口开发方向错误，且往往要到集成完成后才会暴露。

建议将获取该规范作为承诺进度的前置条件。详见附录 B 第 A-01 项。

Các yêu cầu dưới đây được đưa vào vì cơ chế thử lại 10 lần khiến việc bỏ qua chúng gần như chắc chắn gây sự cố vận hành.

下列要求之所以列为强制项，是因为在 10 次重试机制下，忽略它们几乎必然引发运维事故。

1.  Bất biến theo lần gọi. Hệ thống chắc chắn sẽ nhận trùng callback. Dùng referenceNumber làm khóa chống trùng, lưu vào bảng có ràng buộc duy nhất ở tầng cơ sở dữ liệu. Kiểm tra trùng chỉ ở tầng ứng dụng sẽ để lọt hai callback đến đồng thời.

2.  Phản hồi nhanh, xử lý bất đồng bộ. Ghi nhận callback vào hàng đợi và trả HTTP 200 ngay, thay vì xử lý toàn bộ nghiệp vụ trong request. Trả lời chậm có thể bị coi là thất bại và kích hoạt thử lại.

3.  Đối chiếu số tiền trước khi trả dịch vụ. Luôn so khớp amount trong callback với số tiền của đơn hàng trong cơ sở dữ liệu. Không trả dịch vụ chỉ dựa trên sự tồn tại của callback.

4.  Ghi nhật ký toàn bộ payload thô. Lưu nguyên văn phần thân của mọi callback, kể cả callback bị từ chối hay xử lý lỗi. Đây là bằng chứng duy nhất khi cần đối chất với VietQR hoặc ngân hàng.

5.  Giới hạn dải địa chỉ IP nguồn. Chỉ chấp nhận request từ dải IP mà VietQR sử dụng. Đây là lớp phòng vệ bổ sung bên cạnh cơ chế token.

6.  Không tin cậy callback là kênh duy nhất. Bắt buộc xây dựng tác vụ đối soát chủ động ở Bước 4.

1.  幂等处理。系统必然会收到重复回调。请以 referenceNumber 作为去重键，写入带唯一约束的数据库表。仅在应用层判重会漏掉同时到达的两次回调。

2.  快速响应，异步处理。将回调写入队列后立即返回 HTTP 200，不要在请求内完成全部业务处理。响应过慢可能被判定为失败并触发重试。

3.  发放服务前核对金额。务必将回调中的 amount 与数据库中订单金额进行比对。不得仅凭回调存在就发放服务。

4.  记录完整原始报文。原样保存每一次回调的请求体，包括被拒绝或处理失败的回调。这是日后与 VietQR 或银行对质时唯一的凭据。

5.  限制来源 IP 段。仅接受来自 VietQR 所使用 IP 段的请求。这是在令牌机制之外的附加防护层。

6.  不要把回调当作唯一通道。必须按步骤四建设主动对账任务。

@Transactional

public void handleCallback(CallbackPayload p) {

    // 1. Chong trung / 幂等去重 — dua vao rang buoc UNIQUE cua CSDL

    //    Bat exception vi pham rang buoc duy nhat, KHONG dung SELECT truoc INSERT

    try {

        txnLogRepo.insert(p.getReferenceNumber(), rawBody);

    } catch (DuplicateKeyException e) {

        log.info("Callback trung, bo qua: {}", p.getReferenceNumber());

        return;                       // van tra HTTP 200

    }

    // 2. Doi chieu don hang / 核对订单

    Order order = orderRepo.findByOrderId(p.getOrderId());

    if (order == null)                     { alert("Khong tim thay don hang"); return; }

    if (order.getAmount() != p.getAmount()) { alert("Lech so tien"); return; }

    if (order.isPaid())                     { return; }   // da xu ly

    // 3. Cap nhat va tra dich vu / 更新状态并发放服务

    order.markPaid(p.getReferenceNumber());

    serviceQueue.enqueue(order.getId());   // xu ly bat dong bo

}

Vì sao không dùng mẫu kiểm tra rồi mới ghi

Nếu hai callback cho cùng một giao dịch đến đồng thời, cả hai đều có thể vượt qua bước kiểm tra trước khi bất kỳ bản ghi nào được ghi xuống. Kết quả là dịch vụ được trả hai lần.

Ràng buộc duy nhất ở tầng cơ sở dữ liệu loại bỏ hoàn toàn khoảng trống này, vì việc kiểm tra và ghi diễn ra như một thao tác nguyên tử.

为什么不能用「先查询再插入」

如果同一笔交易的两个回调同时到达，在任何一条记录写入之前，两者都可能通过查询检查。结果就是服务被发放两次。

数据库层的唯一约束能彻底消除这一时间窗口，因为判重与写入是同一个原子操作。

Sandbox có API Test Callback để giả lập việc người dùng quét mã và xác nhận thanh toán, không cần giao dịch thật.

Lỗi thường gặp nhất

Trường content truyền vào API Test Callback phải là giá trị lấy từ phản hồi của API sinh QR, tức là giá trị đã có tiền tố đối soát, không phải giá trị mà Đối tác đã gửi lên.

Việc cần làm trong bước này

• Ghi lại nguyên văn payload callback nhận được vào tài liệu nội bộ. Vì VietQR chưa cung cấp đặc tả bằng văn bản, payload thực tế quan sát được chính là đặc tả đáng tin cậy nhất mà Đối tác có.

沙箱环境提供 Test Callback 接口，可模拟用户扫码并确认支付，无需真实交易。

最常见的错误

传入 Test Callback 接口的 content 字段，必须使用生成二维码接口返回的值，即已带对账前缀的值，而不是合作伙伴发送上去的原始值。

本步骤必须完成的事项

• 将收到的回调报文原样记录到内部文档中。由于 VietQR 尚未提供书面规范，实际观测到的报文就是合作伙伴能获得的最可靠规范。

Cơ chế thử lại 10 lần của VietQR chỉ bù trừ cho trường hợp hệ thống Đối tác tạm thời không nhận được dữ liệu.

Nó không bù trừ cho trường hợp ngân hàng không báo giao dịch sang VietQR, vì khi đó VietQR không có gì để gửi đi.

Theo mô tả của VietQR, khi hệ thống ngân hàng nhận quá tải, ngân hàng chỉ lưu thông tin giao dịch mà không thực hiện đối soát, do đó không thông báo giao dịch sang VietQR. Đây là tình huống nằm hoàn toàn ngoài phạm vi của cơ chế thử lại.

Hệ quả nếu bỏ qua bước này: tiền đã vào tài khoản nhưng người dùng không nhận được dịch vụ, và hệ thống không tự phát hiện được.

VietQR 的 10 次重试机制，只能覆盖合作伙伴系统暂时无法接收数据的情形。

它无法覆盖银行未将交易通知 VietQR 的情形，因为此时 VietQR 根本没有数据可推送。

根据 VietQR 的说明，当收款银行系统负载过高时，银行只会保存交易信息而不执行对账，因此不会将交易通知 VietQR。这种情况完全超出重试机制的作用范围。

若省略本步骤，后果是：款项已到账但用户未收到服务，且系统无法自行发现。

1.  Chạy mỗi 2 đến 5 phút, quét các đơn hàng ở trạng thái chờ thanh toán có tuổi đời từ 3 phút trở lên.

2.  Với mỗi đơn hàng, gọi API Check Transaction với type = 0 và value = orderId.

3.  Nếu tìm thấy giao dịch đã thanh toán, xử lý qua đúng luồng callback thông thường: cùng một hàm xử lý, cùng cơ chế chống trùng theo referenceNumber.

4.  Dừng đối soát khi đơn hàng vượt quá thời hạn, khuyến nghị 20 phút; chuyển sang trạng thái quá hạn và ghi nhận để đối soát cuối ngày.

5.  Thiết lập cảnh báo khi tỷ lệ đơn hàng được cứu bởi tác vụ này vượt ngưỡng. Đây là tín hiệu sớm cho thấy kênh callback đang gặp vấn đề.

1.  每 2 至 5 分钟运行一次，扫描处于待支付状态且已创建满 3 分钟的订单。

2.  对每笔订单，以 type = 0、value = orderId 调用交易查询接口。

3.  若查到已支付的交易，走与回调完全相同的处理流程：同一个处理函数，同一套基于 referenceNumber 的去重机制。

4.  订单超过时限后停止对账，建议时限为 20 分钟；将其置为超时状态并记录，纳入日终对账。

5.  当本任务补救的订单占比超过阈值时触发告警。这是回调通道出现问题的早期信号。

Nguyên tắc quan trọng nhất của bước này

Không viết hai nhánh xử lý riêng cho callback và cho đối soát chủ động. Hai nhánh sẽ phân kỳ theo thời gian và tạo ra lỗ hổng rất khó phát hiện.

Đối soát chủ động chỉ nên là một nguồn dữ liệu đầu vào khác cho cùng một hàm xử lý đã dùng cho callback.

本步骤最重要的原则

不要为回调和主动对账分别编写两套处理逻辑。两条分支会随时间推移而产生差异，形成极难排查的漏洞。

主动对账应当只是同一个处理函数的另一个数据来源，与回调复用完全相同的逻辑。

API Check Transaction không khả dụng trên Sandbox. Do đó toàn bộ tác vụ đối soát chủ động không thể kiểm thử đầu-cuối trước khi golive.

Khuyến nghị thiết kế tầng truy cập API có thể thay thế bằng đối tượng giả lập, để ít nhất kiểm thử được phần logic nghiệp vụ trên Sandbox.

交易查询接口在沙箱环境中不可用。因此整个主动对账任务无法在上线前完成端到端测试。

建议将 API 访问层设计为可替换为 Mock 对象，以便至少能在沙箱环境验证业务逻辑部分。

1.  Hoàn tiền luôn gắn với một giao dịch gốc. Không thể tạo lệnh hoàn tiền độc lập; mọi lệnh hoàn đều phải tham chiếu referenceNumber của giao dịch đã thanh toán.

2.  Tổng số tiền hoàn không vượt quá số tiền gốc. Có thể hoàn nhiều lần, nhưng tổng giá trị các lần hoàn bị giới hạn bởi số tiền của giao dịch gốc. Cơ chế này cho phép hoàn từng phần một cách an toàn.

1.  退款必须关联原始交易。不能创建独立的退款指令；每一笔退款都必须引用已支付交易的 referenceNumber。

2.  累计退款金额不得超过原交易金额。可以多次退款，但各次退款金额之和受原交易金额限制。该机制使部分退款可以安全进行。

So tien con co the hoan  =  amount  -  amountRefunded

可退余额                =  amount  -  amountRefunded

(lay tu API Check Transaction / 取自交易查询接口)

1.  Gọi API Check Transaction để lấy trạng thái thực tế của giao dịch gốc, đặc biệt là hai trường refundCount và amountRefunded.

2.  Tính số tiền còn có thể hoàn. Nếu số tiền cần hoàn vượt quá giá trị này, dừng lại và báo lỗi nghiệp vụ, không gọi API Refund.

3.  Sinh và lưu một mã định danh yêu cầu hoàn tiền phía Đối tác, để phân biệt yêu cầu hoàn tiền với lần gọi API. Một yêu cầu có thể phát sinh nhiều lần gọi.

4.  Gọi API Refund. Lưu lại nguyên văn cả request và response.

5.  Nếu thành công, trường message trong phản hồi chứa mã giao dịch hoàn do ngân hàng sinh ra. Lưu giá trị này để đối soát với ngân hàng.

6.  Chờ callback với transType = "D" để xác nhận trạng thái cuối cùng. Đối soát lại bằng Check Transaction.

1.  调用交易查询接口获取原始交易的实际状态，重点关注 refundCount 与 amountRefunded 两个字段。

2.  计算可退余额。若待退金额超过该值，则中止并返回业务错误，不要调用退款接口。

3.  在合作伙伴侧生成并保存一个退款申请编号，用以区分「退款申请」与「接口调用次数」。一个申请可能对应多次调用。

4.  调用退款接口。原样保存请求与响应内容。

5.  成功时，响应中的 message 字段包含银行生成的退款交易号。请保存该值用于与银行对账。

6.  等待 transType = "D" 的回调以确认最终状态，并再次通过交易查询接口核对。

Hai điểm dễ hiểu nhầm

Thứ nhất: trong phản hồi thành công, trường message không chứa thông điệp mô tả mà chứa mã giao dịch hoàn. Nội dung trường này khi thất bại chưa được VietQR mô tả, nên phải kiểm tra status trước rồi mới diễn giải message.

Thứ hai: phản hồi HTTP 200 của API Refund không phải bằng chứng tiền đã về tài khoản người dùng. Nó chỉ xác nhận VietQR đã tiếp nhận và chuyển lệnh sang ngân hàng.

两处容易误解的地方

其一：成功响应中的 message 字段并非描述性提示，而是退款交易号。VietQR 尚未说明失败时该字段的内容，因此必须先判断 status，再解读 message。

其二：退款接口返回 HTTP 200 并不代表款项已到达用户账户，它仅表示 VietQR 已受理并将指令转交银行。

VietQR không có cơ chế thử lại tự động cho API Refund. Cơ chế thử lại 10 lần trong 5 phút áp dụng cho callback, không áp dụng cho lệnh hoàn tiền.

Yêu cầu bắt buộc

• Không tự động thử lại lệnh hoàn tiền khi chưa xác định được nguyên nhân thất bại. Nếu lệnh hoàn thứ nhất thực tế đã thành công nhưng phản hồi bị mất, việc thử lại sẽ hoàn tiền hai lần.

• Trước mỗi lần thử lại, gọi Check Transaction và kiểm tra refundCount cùng amountRefunded để xác định trạng thái thực tế. Đây là nguồn dữ liệu đáng tin cậy hơn phản hồi của chính lệnh hoàn tiền.

• Đưa lệnh hoàn tiền thất bại vào hàng đợi xử lý thủ công có người phê duyệt, kèm đầy đủ nhật ký request và response.

VietQR 未为退款接口提供自动重试机制。5 分钟内重试 10 次的机制适用于回调，不适用于退款指令。

强制要求

• 在未查明失败原因前，不得自动重试退款指令。如果第一次退款实际已成功但响应丢失，重试将导致重复退款。

• 每次重试前，先调用交易查询接口，核对 refundCount 与 amountRefunded 以确认实际状态。该数据源比退款指令自身的响应更可靠。

• 将失败的退款指令转入需人工审批的处理队列，并附上完整的请求与响应日志。

Bảng tổng hợp các lỗi mà đội tích hợp hay mắc phải, kèm cách xử lý.

下表汇总集成团队常见的错误，并给出处理办法。

#

#

Lỗi

错误

Cách xử lý

处理办法

API

接口

Sandbox

沙箱

Production

生产

Hệ quả

影响

Đây là khác biệt quan trọng nhất và là nguyên nhân gây lỗi phổ biến nhất khi chuyển môi trường.

这是最关键的差异，也是切换环境时最常见的故障根源。

Hạng mục

对比项

Sandbox

沙箱

Production

生产

Rà soát bắt buộc trước khi chuyển môi trường

Mọi đoạn mã phụ thuộc vào giá trị của ba trường content, vaAccount và userBankName phải được rà soát lại.

Đoạn mã bóc tách tiền tố từ trường content sẽ chạy đúng trên Sandbox nhưng sai trên Production. Ngược lại, logic đối soát theo vaAccount không thể kiểm thử được trên Sandbox vì trường này luôn rỗng.

Khuyến nghị đối soát theo orderId với QR động, hoặc theo referenceNumber, vì hai khóa này ổn định trên cả hai môi trường.

切换环境前的强制检查

所有依赖 content、vaAccount、userBankName 三个字段取值的代码都必须重新审查。

截取 content 前缀的代码在沙箱环境正确，但在生产环境会出错。反之，按 vaAccount 对账的逻辑无法在沙箱验证，因为该字段始终为空。

建议动态码按 orderId 对账，或统一按 referenceNumber 对账，这两个键在两个环境下都稳定。

Hạng mục

检查项

Trạng thái

状态

Mã

编号

Ca kiểm thử

测试用例

Kết quả kỳ vọng

预期结果

MT

环境

Hạng mục bàn giao bắt buộc của giai đoạn kiểm thử

Toàn bộ payload callback thực tế quan sát được trên Sandbox phải được ghi lại nguyên văn và bàn giao như một tài liệu chính thức.

Toàn bộ phản hồi khác HTTP 200 phải được ghi lại để lập bảng mã lỗi thực nghiệm.

Vì VietQR chưa cung cấp hai nội dung này bằng văn bản, kết quả thực nghiệm chính là tài liệu tham chiếu đáng tin cậy nhất.

测试阶段的强制交付物

在沙箱环境实际观测到的全部回调报文，必须原样记录并作为正式文档交付。

所有非 HTTP 200 的响应必须记录下来，用于编制实测错误码表。

由于 VietQR 尚未以书面形式提供这两项内容，实测结果就是最可靠的参考资料。

Hạng mục

检查项

Trạng thái

状态

Hạng mục

检查项

Trạng thái

状态

Chỉ số

指标

Ý nghĩa

含义

Tên trường / Thuật ngữ

字段名 / 术语

Tiếng Việt

越南语说明

中文

中文说明

Các hạng mục dưới đây chưa được VietQR cung cấp hoặc chưa đủ rõ để hiện thực hóa. Đội phát triển không nên viết mã dựa trên suy đoán cho những phần này.

以下事项 VietQR 尚未提供，或提供的信息不足以直接实现。开发团队不应基于猜测为这些部分编写代码。

Mã

编号

Nội dung cần làm rõ

待确认内容

Rủi ro

风险

Mã

编号

Nội dung cần làm rõ

待确认内容

• Giải đáp thắc mắc kỹ thuật về nội dung tài liệu này và tài liệu đặc tả.

• Làm việc với VietQR để giải quyết các hạng mục trong Phụ lục B.

• Rà soát thiết kế tích hợp và mã nguồn phía Đối tác trước khi golive.

• Đồng hành trong giai đoạn nghiệm thu và chuyển môi trường.

• 解答与本文档及技术规范相关的技术疑问。

• 代表合作伙伴与 VietQR 协调解决附录 B 中的各项事宜。

• 上线前审查合作伙伴侧的集成设计与源代码。

• 在验收阶段与环境切换过程中提供陪同支持。

Hạng mục

项目

Thông tin

信息

Ghi chú cuối

Tài liệu này được biên soạn dựa trên đặc tả do VietQR cung cấp, kết hợp với phân tích kỹ thuật độc lập của Bluecom.

Các đặc tả của VietQR có thể thay đổi theo thời gian. Khuyến nghị liên hệ Bluecom nếu phát hiện khác biệt so với nội dung tài liệu này.

结语

本文档依据 VietQR 提供的规范，并结合 Bluecom 的独立技术分析编制而成。

VietQR 的规范可能随时间调整。若发现与本文档内容存在差异，建议及时联系 Bluecom。