Khách MONA làm phần mềm SaaS hay lập trình viên nội bộ hay hỏi tụi em cách tích hợp cổng thanh toán vào phần mềm qua API sao cho ổn định, không phải tự viết tay từng dòng đọc SMS ngân hàng. Tụi em từng thấy nhiều đội kỹ thuật thử tự cào tin nhắn biến động số dư, rồi sập ngay trong vòng 1 tuần khi ngân hàng đổi định dạng SMS. Sập là mất khách ngay. MONA Pay được dựng để giải đúng bài toán này bằng một chuẩn API và webhook chung, không phụ thuộc vào việc đọc màn hình điện thoại của ai cả. Tụi em tự dùng nó cho chính MONA từ 2022, khách hàng của MONA đã thanh toán qua đúng luồng đó trước khi công khai.
Nỗi đau của đội kỹ thuật khi phần mềm thiếu thanh toán tự động
Khách MONA bán phần mềm dạng SaaS thường có số lượng giao dịch mỗi ngày rất lớn, khách nạp tiền lẻ tẻ từ vài chục nghìn đến vài triệu đồng. Nếu không có hệ thống nhận diện dòng tiền tự động, kế toán phải đăng nhập app ngân hàng liên tục trong khoảng 30 phút mỗi lần, dò từng mã giao dịch rồi báo lại cho bộ phận kỹ thuật để mở dịch vụ. Một lỗi nhìn nhầm số 0 trong lúc dò cũng đủ khiến khách chờ thêm cả buổi, trong khi đúng ra chỉ cần 2 giây là xong. Tụi em thấy đúng lỗi này lặp lại ở rất nhiều đội kỹ thuật tự làm. Chờ vậy là mất khách.
Nhiều lập trình viên từng thử viết mã cào dữ liệu SMS hoặc đọc email báo biến động số dư, nhưng các giải pháp chắp vá này hoạt động rất thiếu ổn định. Ngân hàng thay đổi cấu trúc tin nhắn là mã nguồn lỗi ngay lập tức, máy chủ điện thoại cắm sạc liên tục để đọc SMS cũng tiềm ẩn rủi ro bảo mật không nhỏ. Doanh nghiệp cần một phương án chuẩn kỹ thuật hơn, giao tiếp trực tiếp máy chủ với máy chủ.
Cách MONA Pay tự đóng gói từ chính hạ tầng của MONA
Từ 2022, MONA đã tự xây hệ thống nhận diện dòng tiền để thu tiền cho chính MONA, và khách hàng mới của MONA đã thanh toán qua đúng luồng đó trước khi công khai thành MONA Pay năm 2026. Ở MONA Host, một tài khoản ACB chung gánh cho hàng nghìn khách khác nhau, mỗi sản phẩm có một mã đầu riêng trong nội dung chuyển khoản để hệ thống biết chính xác tiền thuộc mảng nào. Đúng bài toán mà một phần mềm SaaS bán nhiều gói cũng gặp phải. Tụi em giải nó một lần rồi dùng lại cho mọi sản phẩm khác.
Tháng 9/2026, một lần cấu hình lại máy chủ làm rớt mất khoá bí mật của webhook, webhook vẫn bắn ra khi tiền vào nhưng mang khoá rỗng, hệ thống nhận trả lỗi 401 và khách đã trả tiền mà dịch vụ chưa mở. Tụi em soát lại lịch sử webhook, bổ sung khoá HMAC-SHA256, gửi lại toàn bộ webhook lỗi trong chưa tới 2 giờ. Đau nhưng học được nhiều.
Luồng gọi API và nhận webhook chạy ra sao
Phần mềm của anh chị gọi API để tạo lệnh thanh toán, gói tin gửi đi chứa số tiền, mã đơn hàng và thông tin khách. Hệ thống MONA Pay tiếp nhận, sinh ra mã VietQR động, phần mềm hiển thị mã này để khách quét bằng app ngân hàng và xác nhận chuyển. Ngay khi ngân hàng ghi nhận, webhook ký HMAC-SHA256 kèm header X-Mona-Signature bắn thẳng về máy chủ của anh chị, toàn bộ quá trình từ lúc tiền vào tới lúc đơn đổi trạng thái chỉ mất khoảng 2 giây. Nhanh và gọn.
Đoạn mã xử lý webhook của anh chị cần kiểm tra chữ ký để loại giả mạo, và cần ràng buộc mã giao dịch duy nhất trong cơ sở dữ liệu để tránh cộng tiền hai lần nếu webhook bắn lại do chưa nhận phản hồi HTTP 200. Hệ thống MONA Pay từ chối yêu cầu lệch giờ quá 5 phút, đây là ngưỡng chống phát lại chứ không phải webhook bắn định kỳ mỗi 5 phút. Không kiểm kỹ là dễ dính lỗi cộng trùng.
Những cái bẫy kỹ thuật khi tự đấu nối ngân hàng
Ngân hàng không phải lúc nào cũng gửi dữ liệu đúng như tài liệu kỹ thuật mô tả. Có lần một ngân hàng gửi header dồn sai vị trí, hệ thống chuẩn của tụi em trả lỗi 422 và loại luôn giao dịch đó, buộc tụi em viết lại lớp đọc dữ liệu cho đúng cấu trúc rồi phát lại các giao dịch bị rớt. Làm nghề báo có tự động, cái khó không nằm ở vẽ mã QR cho đẹp, mà nằm ở những lần dữ liệu ngân hàng về không giống tài liệu một chữ nào trong suốt 4 năm tụi em vận hành hệ thống này. Không đoán được trước đâu.
Với phần mềm order tại quầy, tốc độ phản hồi phải tính bằng mili giây, thu ngân không thể để khách đứng đợi 3 phút chỉ để xác nhận. Máy chủ phải xử lý bất đồng bộ, lưu dữ liệu webhook ngay lập tức rồi đẩy các việc nặng như gửi email hay tính hoa hồng vào hàng đợi xử lý sau. Đây là chỗ khách MONA hay bỏ sót khi tự viết lần đầu.
Chi phí và cách bắt đầu tích hợp
Gói miễn phí xử lý 500 giao dịch mỗi tháng, tức khoảng 16 đơn một ngày, đủ cho phần lớn dự án đang chạy thử. Vượt mức đó, gói cố định từ 99.000 đồng mỗi tháng cho 2.000 giao dịch, không thu phần trăm trên số tiền ở bất kỳ gói nào. Developer có thể xem tài liệu API của MONA Pay để lấy mã mẫu cho nhiều ngôn ngữ lập trình, hoặc đọc riêng hướng dẫn tích hợp webhook an toàn trước khi bật cho khách thật dùng.
Với các dự án thiết kế phần mềm quản lý bán hàng hay phần mềm order, luồng thu tiền tự động ghép được ngay vào hệ thống hiện có mà không cần đập đi xây lại. Anh chị có thể vào MONA Pay mở tài khoản tại my.monapay.vn, thử sandbox trước khi cấp API key thật cho developer viết mã. Chỉ mất vài phút. Cần tư vấn kỹ thuật, gọi 1900 636 648, tụi em có kỹ sư trực máy hỗ trợ trong vòng 1 buổi làm việc.
Câu hỏi thường gặp
Tích hợp API mất bao lâu để hoàn thiện?
Nhanh thôi. Với tài liệu kỹ thuật có sẵn, một lập trình viên quen việc mất khoảng 2 đến 4 giờ để cấu hình xong luồng tạo QR và nhận webhook.
API có xử lý được giao dịch lỗi không?
Có endpoint riêng. Anh chị chủ động truy vấn trạng thái giao dịch bất cứ lúc nào, mọi giao dịch bất thường được ghi log chi tiết trên dashboard my.monapay.vn.
Phần mềm nội bộ không có IP public thì tích hợp được không?
Cần có cách nhận webhook trước đã. Máy chủ cần IP tĩnh public hoặc dùng công cụ forward port an toàn trong khoảng 5 phút cấu hình, vì webhook giao tiếp qua môi trường internet tiêu chuẩn.
Có cần chứng chỉ bảo mật đặc biệt không?
Máy chủ hỗ trợ SSL để dữ liệu không bị nghe lén. Chỉ cần vậy thôi. Xác thực tin nhắn đã có sẵn cơ chế chữ ký HMAC-SHA256 trong tài liệu.
