Zalo Mini Apps
Trang chủCase StudyBlogLiên hệĐăng nhập0945 031 039Liên hệ với chúng tôi

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ó

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 1Giả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ụngMini App có tính năng thanh toánChỉ 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ánPhải khai báo cả Secret Key do Payment Provider cấpKhông yêu cầu Secret Key
Hợp vớiDoanh nghiệp chưa có luồng thanh toán, muốn làm nhanhDoanh 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
ZALOPAYZaloPay
MOMOMoMo
VNPAYVNPay
ATM, CCZaloPay ATM, ZaloPay CC
PAYME_ATM, PAYME_CCPayME ATM, PayME CC
CODThanh toán khi nhận hàng
BANKChuyể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.

Giỏ hàng đi qua 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
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

  1. 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.
  2. Thiếu mac với ZMP SDK từ 2.45.0 trở lên.
  3. 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.
  4. 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ủ.
  5. Bỏ qua kiểm tra số tiền. Callback phải khớp số tiền đã lưu theo orderId.
  6. 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.
  7. 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.

Nếu anh chị mới bắt đầu, hãy đọc trước cách tạo Zalo Mini App đầu tiên và quy trình duyệt. Các trường hợp đội tôi đã làm nằm ở trang case study.

Câu hỏi thường gặp về thanh toán trong Zalo Mini App

Cửa hàng nhỏ có bắt buộc phải làm thanh toán online không?

Không. Chính sách cho phép mini app chưa dùng Checkout SDK, với điều kiện không hiển thị giá và chuyển nút mua sang «Liên hệ» hoặc «Tư vấn».

Có nhận được tiền ngay vào tài khoản của cửa hàng không?

Tài liệu không mô tả thời gian đối soát. Đó là điều khoản giữa anh chị và từng cổng thanh toán; tôi không có số liệu để ghi.

Thanh toán thất bại thì mini app làm gì?

Mini app đọc resultCode từ checkTransaction và hiển thị trạng thái tương ứng: thành công, đang xử lý, thất bại, hoặc người dùng chưa chọn phương thức.

Có thử thanh toán mà không mất tiền thật không?

Có. Mỗi phương thức có bản SANDBOX, chỉ hiện với Admin, Developer hoặc người dùng thử nghiệm.

Có thu COD được không?

Có. COD là một phương thức có sẵn; nền tảng gọi notify khi người dùng chọn, và anh chị cập nhật kết quả bằng updateOrderStatus.

Nguồn: docs.zaloplatforms.com/docs/MA/checkoutSdk (intro, method, apis/createOrder, apis/checkTransaction, integration-process/overview/setting, order, maResult, serverResult, webhooks/callback, webhooks/notify), getting-started/frequently-solved-issues; miniapp.zaloplatforms.com/documents (zalo-mini-app-censorship-policy, mini-app-verification, regulated-products-and-services), kiểm ngày 09/11/2026.

Thanh toán trong Zalo Mini App: cách tích hợp Checkout SDK