Chuyển khoản ngân hàng (Beta)
Checkout Popup là giao diện thanh toán chuẩn của Nền tảng dành cho phương thức chuyển khoản ngân hàng. Popup sử dụng mã QR động theo chuẩn VietQR, chứa sẵn thông tin đơn hàng, giúp người dùng hoàn tất thanh toán nhanh chóng và tiện lợi.
Tính năng tích hợp Chuyển khoản ngân hàng theo hình thức tùy chỉnh hiện đang trong giai đoạn thử nghiệm (Beta). Đối tác cần chủ động tích hợp và xử lý giao dịch theo tài liệu hướng dẫn.
Giai đoạn thử nghiệm dự kiến kéo dài đến hết tháng 03/2027. Mọi thông tin cập nhật sẽ được thông báo tới đối tác trước khi kết thúc giai đoạn thử nghiệm.
Tổng quan
Đối với các đối tác đã triển khai tài khoản động (tạo mã QR riêng cho từng đơn hàng), Checkout Popup tiếp nhận nội dung mã QR (qrContent) và tự động xử lý toàn bộ luồng điều hướng người dùng sang ứng dụng ngân hàng. Popup hiển thị các thông tin sau:
- Logo và tên đối tác cung cấp dịch vụ.
- Số tiền và mô tả đơn hàng.
- Ứng dụng ngân hàng dùng để chuyển khoản: mặc định là ngân hàng người dùng đã có thao tác gần nhất trên Zalo, người dùng có thể chọn ngân hàng khác.
Ví dụ minh họa
Ví dụ dưới đây minh họa luồng Nạp điện thoại: sau khi người dùng xác nhận thanh toán trong Mini App, Checkout Popup hiển thị để người dùng chọn ngân hàng, sau đó tự động chuyển sang ứng dụng ngân hàng với thông tin thanh toán đã được điền sẵn.
Đăng ký sử dụng
Trước khi tích hợp, đối tác cần khai báo phương thức thanh toán Chuyển khoản ngân hàng theo loại hình Tích hợp tùy chỉnh. Xem hướng dẫn tại Bước 1 - Khai báo phương thức thanh toán.
Luồng người dùng
- Người dùng chọn sản phẩm/dịch vụ và xác nhận thanh toán.
- Người dùng được chuyển sang ứng dụng ngân hàng, thông tin thanh toán được điền sẵn từ
qrContent. - Người dùng xác nhận giao dịch trên ứng dụng ngân hàng.
Hướng dẫn tích hợp
Bước 1. Nâng cấp zmp-sdk
Nâng cấp zmp-sdk lên phiên bản mới nhất (zmp-sdk@latest).
Bước 2. Mở Checkout Popup
Khi người dùng chọn phương thức Chuyển khoản ngân hàng, gọi Payment.openCheckoutPopup và truyền vào nội dung mã QR động do hệ thống của đối tác tạo theo chuẩn VietQR.
import { Payment } from "zmp-sdk/apis";
try {
const rs = await Payment.openCheckoutPopup({
amount: 10000,
orderDescription: "Test CK",
qrContent: "00020101021238570010A000000727012700069704220113VQRQAAU....5",
method: "BANK", // hoặc "BANK_SANDBOX"
});
if (rs.status === "pay") {
// Người dùng chọn chuyển qua ứng dụng ngân hàng. Nếu có truyền method và
// method này đang cấu hình thông tin tài khoản động, rs sẽ có trường orderId
console.log(rs?.orderId);
} else if (rs.status === "close") {
// Người dùng đóng popup
}
} catch (error) {
if (error.code === -1404) {
// Phiên bản Zalo hiện tại chưa hỗ trợ API
}
}
Tham số
| Tham số | Kiểu | Bắt buộc | Mô tả |
|---|---|---|---|
| amount | number | true | Số tiền thanh toán. |
| orderDescription | string | false | Nội dung chuyển khoản. Trường hợp qrContent đã chứa nội dung chuyển khoản, giá trị trong qrContent sẽ được ưu tiên. |
| qrContent | string | true | Chuỗi mã QR động do đối tác tạo theo chuẩn VietQR, chứa đầy đủ thông tin cần thiết để thực hiện thanh toán. |
| method | string | false | Nhận giá trị "BANK" hoặc "BANK_SANDBOX". Nếu truyền tham số này và phương thức thanh toán tương ứng sử dụng thông tin tài khoản động, kết quả trả về sẽ có thêm trường orderId. |
Xử lý kết quả
| Kết quả | Ý nghĩa |
|---|---|
status: "pay" | Người dùng chọn chuyển khoản qua ứng dụng ngân hàng. Nếu có truyền method và phương thức thanh toán sử dụng thông tin tài khoản động, kết quả trả về sẽ kèm theo orderId. |
status: "close" | Người dùng đóng popup. |
error.code: -1404 | Phiên bản Zalo hiện tại chưa hỗ trợ API. Đối tác cần bắt lỗi này để có phương án xử lý thay thế. |
Checkout Popup khả dụng trên Zalo iOS từ phiên bản 674 và Zalo Android từ phiên bản 25081840 trở lên. Đối tác cần luôn xử lý trường hợp lỗi -1404 để không làm gián đoạn luồng thanh toán trên các phiên bản cũ hơn.
Bước 3. Khai báo trạng thái giao dịch
Checkout Popup chỉ đảm nhận phần giao diện và không cập nhật trạng thái thanh toán. Khi hệ thống backend của đối tác ghi nhận thay đổi trạng thái giao dịch (đã nhận tiền, đã hoàn tiền hoặc thất bại), đối tác cần chủ động gọi API updateOrderStatus với orderId nhận được từ Payment.openCheckoutPopup để cập nhật trạng thái đơn hàng trên Nền tảng.
Endpoint
POST https://payment-mini.zalo.me/api/transaction/{Mini-App-ID}/purchase-payment
Tham số
| Tham số | Kiểu | Bắt buộc | Mô tả |
|---|---|---|---|
| appId | string | true | Mã định danh của Mini App. |
| orderId | string | true | Mã đơn hàng nhận được từ openCheckoutPopup. |
| resultCode | number | true | Trạng thái giao dịch: 1 thành công, 0 đã hoàn tiền, -1 thất bại. |
| mac | string | true | Mã xác thực đơn hàng. Xem cách tạo tại mục bên dưới. |
Tạo mã xác thực (mac)
const data =
`appId=${appId}&orderId=${orderId}` +
`&resultCode=${resultCode}&privateKey=${privateKey}`;
const mac = HMAC("HmacSHA256", privateKey, data);
Nghiệm thu
Trước khi phát hành, đối tác cần kiểm tra đầy đủ các kịch bản sau:
- Popup hiển thị chính xác logo, tên đối tác, số tiền và mô tả đơn hàng.
- Hệ thống tự động chọn ngân hàng người dùng thao tác gần nhất và cho phép chọn ngân hàng khác.
- Ứng dụng ngân hàng đã được cài đặt: tự động chuyển sang ứng dụng và điền sẵn chính xác ngân hàng nhận, số tài khoản, số tiền và nội dung chuyển khoản.
- Ứng dụng ngân hàng chưa được cài đặt: chuyển đến App Store / Google Play.
- Ngân hàng chưa được Zalo hỗ trợ (ví dụ: SCB): hiển thị mã QR để người dùng tự quét.
Tài liệu này chỉ mô tả luồng tích hợp Checkout Popup. Vui lòng liên hệ bộ phận Kinh doanh (Business) để được tư vấn chi tiết về chính sách và điều khoản dịch vụ.