Chuyển tới nội dung chính

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.

Chuyển khoản ngân hàng (Beta)

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.

Checkout Popup trong luồng Nạp điện thoại

Đă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​

  1. Người dùng chọn sản phẩm/dịch vụ và xác nhận thanh toán.
  2. 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.
  3. 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.

checkout-popup.js
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ểuBắt buộcMô tả
amountnumbertrueSố tiền thanh toán.
orderDescriptionstringfalseNộ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.
qrContentstringtrueChuỗ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.
methodstringfalseNhậ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: -1404Phiê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ế.
Yêu cầu phiên bản

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ểuBắt buộcMô tả
appIdstringtrueMã định danh của Mini App.
orderIdstringtrueMã đơn hàng nhận được từ openCheckoutPopup.
resultCodenumbertrueTrạng thái giao dịch: 1 thành công, 0 đã hoàn tiền, -1 thất bại.
macstringtrueMã 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)

mac.js
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.
thông tin

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ụ.