Thanh toán trong Zalo Mini App: các cách tích hợp và điều kiện cần có
Tất cả blog / Hướng dẫn / Thanh toán trong Zalo Mini App: các cách tích hợp và điều kiện cần có
Lộc Nguyễn15 thg 11, 20269 phút đọc
Zalo Mini App có thanh toán phải tích hợp Checkout SDK của nền tảng. Có hai giải pháp: nền tảng làm trung gian xử lý với ZaloPay, MoMo, VNPay, PayME, hoặc tự xử lý giao dịch khi được duyệt. Điều kiện cần có gồm xác thực chủ sở hữu và máy chủ nhận kết quả.
Tôi viết bài này cho chủ cửa hàng sắp bán hàng trên mini app và cho lập trình viên nhận việc tích hợp. Thông tin lấy từ tài liệu Checkout SDK và chính sách kiểm duyệt của Zalo Mini App, mở ngày 09/11/2026. Thứ tự: khi nào bắt buộc dùng Checkout SDK, hai giải pháp, các phương thức có sẵn, luồng bốn bước, điều kiện hồ sơ, lỗi hay gặp, điểm bất lợi, câu hỏi thường gặp. Phí giao dịch của từng cổng tôi không ghi, vì mỗi cổng có hợp đồng riêng và tài liệu Zalo không công bố.
Khi nào bắt buộc dùng Checkout SDK
Trang «Giới thiệu» của Checkout SDK ghi rằng nền tảng yêu cầu tất cả đối tác có tính năng thanh toán phải tích hợp Checkout SDK. Mục đích là mọi phương thức thanh toán đều khai báo trên hệ thống và mọi giao dịch đều được người dùng xác nhận, có dữ liệu ghi nhận. Chính sách kiểm duyệt nói cụ thể hơn: Mini App có phát sinh đơn hàng, có chức năng thanh toán và hiển thị giá tiền trực tiếp thì cần Checkout SDK.
Nếu chưa tích hợp, chính sách yêu cầu không hiển thị giá sản phẩm hay dịch vụ và đổi chức năng mua hàng, thanh toán thành «Liên hệ» hoặc «Tư vấn». Nghĩa là mini app chỉ làm danh thiếp hay catalog vẫn đi được mà không cần thanh toán, nhưng mini app bán hàng có giá thì phải có.
Hai giải pháp tích hợp
Tài liệu cho đối tác chọn một trong hai:
Tiêu chí
Giải pháp 1
Giải pháp 2
Cách hoạt động
Đối tác khai báo kênh thanh toán, hệ thống xử lý giao dịch với Payment Provider rồi trả kết quả
Hệ thống hiển thị phương thức cho người dùng chọn, đối tác tự xử lý giao dịch và khai báo kết quả
Điều kiện áp dụng
Mini App có tính năng thanh toán
Chỉ một số đối tác nhất định, cần nền tảng kiểm duyệt
Khoá của cổng thanh toán
Phải khai báo cả Secret Key do Payment Provider cấp
Không yêu cầu Secret Key
Hợp với
Doanh nghiệp chưa có luồng thanh toán, muốn làm nhanh
Doanh nghiệp đã có sẵn luồng thanh toán riêng
Với cửa hàng nhỏ, tôi thường chọn giải pháp 1 vì nó là con đường mặc định, không cần xin duyệt riêng, và nền tảng đã kết nối sẵn nhiều cổng.
Các phương thức thanh toán có sẵn
Trang «Mã phương thức thanh toán» liệt kê các mã dùng khi tạo đơn. Mỗi mã có bản SANDBOX để thử, chỉ hiện với người dùng có vai trò Administrator hoặc Developer, hoặc người dùng thử nghiệm.
Mã
Phương thức
ZALOPAY
ZaloPay
MOMO
MoMo
VNPAY
VNPay
ATM, CC
ZaloPay ATM, ZaloPay CC
PAYME_ATM, PAYME_CC
PayME ATM, PayME CC
COD
Thanh toán khi nhận hàng
BANK
Chuyển khoản ngân hàng
Ngoài ra đối tác có thể khai báo «phương thức riêng» cho cổng mà SDK chưa hỗ trợ, gồm mã, tên và logo phương thức.
Luồng thanh toán bốn bước
Tài liệu mô tả luồng giải pháp 1 theo bốn bước. Điểm cốt lõi: mini app chỉ hiển thị kết quả; việc giao hàng phải căn cứ kết quả máy chủ nhận được.
Luồng thanh toán: giỏ hàng, cổng thanh toán, máy chủ cửa hàng nhận xác nhận rồi mới giao hàng.
Bước 1: khai báo phương thức thanh toán
Vào trang quản lý ứng dụng, chọn Mini App, vào mục Checkout SDK, chọn Cấu hình chung. Phần thông tin chung gồm Callback URL (nơi nhận kết quả khi trừ tiền thành công), Private key (để chứng thực callback), Security Method mặc định là HmacSHA256, và trạng thái ứng dụng. Mỗi cổng có trường riêng: ví dụ ZaloPay cần Merchant App ID, Key 1 và Key 2; MoMo cần Partner Code, Access Key, Secret Key, Public Key; VNPay cần Terminal ID, phiên bản API và Secret Key. Mỗi Mini App chỉ có một cấu hình chuyển khoản ngân hàng.
Bước 2: tạo đơn bằng createOrder
Mini app gọi CheckoutSDK.createOrder với các tham số amount, item, desc và mac; extradata và method là tuỳ chọn, kiểu JSON String. Tài liệu ghi từ ZMP SDK 2.45.0, tham số mac là bắt buộc và Checkout SDK không xử lý yêu cầu thiếu mac. Mã mac phải tạo tại máy chủ của doanh nghiệp bằng Private key, không tạo trong mini app. Gọi thành công thì hệ thống tự mở trang thanh toán cho người dùng chọn phương thức và trả về orderId.
Bước 3: nhận kết quả trên mini app
Khi người dùng xong, Checkout SDK đưa họ về mini app. Mini app lắng nghe sự kiện PaymentDone, rồi gọi checkTransaction để xem resultCode: 1 là thành công, 0 là đang xử lý hoặc chờ, -1 là thất bại, -2 là người dùng thoát mà không chọn phương thức. Tài liệu nhấn mạnh bước này chỉ để điều hướng và hiển thị cho người dùng.
Bước 4: xử lý kết quả phía máy chủ
Với ZaloPay, MoMo, VNPay, PayME, Checkout SDK Server gửi callback tới Callback URL; máy chủ dùng Private key kiểm tra mac và overallMac, và đối chiếu amount ứng với orderId phải khớp số tiền anh chị đã lưu. Tài liệu yêu cầu đối tác cho phép (whitelist) danh sách IP của Checkout SDK Server. Nếu sau 20 phút máy chủ chưa nhận kết quả, gọi getOrderStatus để tra kết quả cuối cùng. Với COD và chuyển khoản, nền tảng gọi notify tới Notify URL khi người dùng chọn phương thức, và đối tác phải tự cập nhật kết quả cho Checkout SDK qua API updateOrderStatus.
Điều kiện pháp lý và hồ sơ
Checkout SDK không đứng riêng. Mini App muốn phát hành phải xác thực chủ sở hữu (qua OA đã xác thực hoặc nộp tài liệu KYB), theo trang xác thực áp dụng từ ngày 15/10/2025. Ngành có điều kiện cần thêm giấy phép con; riêng nhóm tài chính, danh sách trong trang xác thực có cả dịch vụ trung gian thanh toán, yêu cầu giấy phép hoạt động dịch vụ trung gian thanh toán. Doanh nghiệp bán hàng thông thường chỉ dùng cổng của bên thứ ba thì không rơi vào nhóm này, nhưng anh chị đối chiếu kỹ với danh mục hàng hoá, dịch vụ cấm, hạn chế hoặc có điều kiện của nền tảng. Ví dụ rượu bia, thuốc lá nằm trong nhóm hạn chế. Chính sách cũng cấm mini app có giao dịch mua bán vật phẩm ảo hay nội dung số như khoá học online, gói nghe nhạc.
Ngoài hồ sơ với Zalo, anh chị cần hợp đồng riêng với từng cổng thanh toán định dùng để có khoá. Phần này tôi không có số liệu, hỏi trực tiếp từng cổng.
Các lỗi hay gặp khi tích hợp
Gọi getOrderStatus hoặc updateOrderStatus từ trong mini app. Tài liệu xếp hai API này vào nhóm phải gọi từ máy chủ vì cần khoá bí mật.
Thiếu mac với ZMP SDK từ 2.45.0 trở lên.
Sai kiểu dữ liệu khi tạo mac.extradata và method phải là JSON String; item chuyển về String khi tạo mac.
Giao hàng theo kết quả trên mini app. Người dùng có thể đóng ứng dụng giữa chừng; hãy dựa vào callback ở máy chủ.
Bỏ qua kiểm tra số tiền. Callback phải khớp số tiền đã lưu theo orderId.
Thử trong trình duyệt hoặc simulator. Luồng createOrder chỉ chạy được trong môi trường Zalo thật, nên cần chế độ Device.
ZMP SDK dưới 2.45.0. Phải xử lý riêng từng phương thức qua các sự kiện như OpenApp, PaymentClose hoặc OnDataCallback.
Điểm bất lợi và rủi ro
Cần máy chủ có mã nguồn riêng. Tạo mã mac, nhận callback, đối chiếu đơn đều ở máy chủ. Cửa hàng không có đội kỹ thuật sẽ phải thuê.
Phụ thuộc hợp đồng với cổng thanh toán. Nền tảng giữ vai trò hiển thị và xử lý, nhưng khoá, phí và đối soát là việc của anh chị với từng cổng.
COD và chuyển khoản không tự ghi nhận tiền. Anh chị phải gọi updateOrderStatus khi đã nhận tiền.
Phương thức chuyển khoản chỉ một cấu hình mỗi Mini App. Đổi sang loại tích hợp khác thì cấu hình mới thay cấu hình cũ sau khi lưu thành công.
Giải pháp 2 cần được duyệt riêng. Không phải ai cũng được chọn.
Chính sách có thể đổi. Tài liệu Checkout SDK có trang changelog; trước khi làm, anh chị mở lại.
Với quán ăn, tôi xếp thứ tự làm Zalo Mini App như sau: thực đơn và đặt món trước, mã QR tại bàn thứ hai, tích điểm thành viên thứ ba, đặt bàn thứ tư, giao hàng sau cùng. Lý do là mỗi bước dùng lại phần đã làm ở bước trước và rủi ro duyệt tăng dần.
Trong Zalo Mini App, anh chị lấy số điện thoại bằng hàm getPhoneNumber của zmp-sdk. Người dùng đồng ý trên màn hình xin quyền, mini app nhận một mã token, rồi máy chủ của doanh nghiệp đổi mã đó lấy số qua Zalo Open API. Mã chỉ dùng được một lần và hết hạn sau 2 phút.
Mini App phải qua hai việc trước khi mở cho mọi người dùng: xác thực chủ sở hữu và xét duyệt phiên bản. Theo chính sách, thời gian kiểm duyệt là 3 ngày làm việc. Hồ sơ cần chuẩn bị gồm giấy tờ xác thực, giấy phép con nếu ngành có điều kiện, và bản Testing đã chạy ổn.