Webhook là gì, VietQR là gì, tài khoản ảo là gì (giải thích dễ hiểu)
Video hướng dẫn
Xem transcript video (8 phần)
Bảy từ cần hiểu
Bạn mở dashboard rồi gặp một loạt từ như VA, VietQR, webhook, HMAC và khóa API, đọc riêng từng chữ thì khó hình dung chúng nối với nhau ra sao. Trong vài phút, mình sẽ giải thích bảy khái niệm bằng một luồng bán hàng dễ hiểu, sau đó ghép chúng lại thành quy trình hoàn chỉnh. Xem hết, bạn biết công cụ nào dành cho khách chuyển tiền, công cụ nào báo cho phần mềm và công cụ nào giúp kiểm tra không bỏ sót giao dịch.
Tài khoản ảo là gì
Tài khoản ảo, viết tắt là VA, là số tài khoản phụ do ACB cấp. Tiền chuyển vào VA vẫn về tài khoản chính của bạn. Mỗi đơn hoặc mỗi khách có thể dùng một số khác nhau, nên hệ thống biết tiền thuộc về đâu mà không phụ thuộc hoàn toàn vào nội dung khách gõ. Lập trình viên tạo VA qua POST /api/v1/acb/virtual-account/registration, hoặc bạn quản lý tại mục Ngân hàng & VA trên dashboard.
VietQR động
VietQR là mã QR chuyển khoản theo chuẩn ngân hàng Việt Nam. Mã QR động của MONA Pay có sẵn số tài khoản, số tiền và nội dung, nên khách quét rồi xác nhận thay vì nhập tay. Khi gọi API tạo QR, bốn dữ liệu quan trọng là orderId, amount, description và thông tin tài khoản. amount là số nguyên VND, tối đa một tỷ; description tối đa hai trăm năm mươi lăm ký tự.
Webhook báo tiền vào
Webhook giống một cuộc gọi từ MONA Pay sang phần mềm của bạn khi có tiền vào. Hệ thống gửi một gói JSON gồm số tiền, nội dung, thời gian, mã giao dịch và tài khoản nhận. Endpoint trả HTTP 200, 201 hoặc 202 trong mười giây thì lần gửi được tính là thành công. Trường transaction_code, nghĩa là mã giao dịch, là khóa chống trùng để một khoản tiền không làm đơn hàng được ghi nhận hai lần.
Chữ ký HMAC
HMAC là chữ ký chống giả cho webhook công khai. Hai bên giữ chung một secret, tức mã bí mật. MONA Pay ký từ X-Mona-Timestamp, dấu chấm và raw body, rồi gửi kết quả trong X-Mona-Signature. Máy chủ tính lại, chữ ký khớp mới nhận. Timestamp lệch quá năm phút thì từ chối để ngăn phát lại gói cũ. Điểm dễ sai là framework parse JSON trước; phải kiểm chữ ký trên raw body đúng từng byte.
Khóa API và Telegram
Khóa API là chìa khóa để máy chủ gọi MONA Pay nhằm tạo VA, tạo QR hoặc xem giao dịch. Bạn đặt tên riêng cho từng khóa để lộ khóa nào thì thu hồi đúng khóa đó. access_token được gửi dạng Bearer cho mọi request; lệnh ghi còn thêm X-Client-Secret là client_secret. Với Telegram, bạn chỉ cần thông báo tiền vào cho nhóm: chọn mọi tài khoản hoặc một VA, đặt mẫu tin rồi bấm Gửi thử.
Đối soát chống sót
Đối soát là lưới đỡ cho webhook. Máy chủ có thể bảo trì đúng lúc tiền vào, nên mỗi giờ hoặc cuối ngày hãy gọi danh sách giao dịch, tối đa một trăm giao dịch mỗi trang, rồi so transaction_code với dữ liệu của mình. Nếu còn phân vân chọn VA hay VietQR, tài liệu khuyên dùng cả hai: QR giúp khách chuyển đúng, VA giúp hệ thống phân biệt đúng đơn. Tiền vẫn nằm trong tài khoản ACB của bạn.
Ghép thành một luồng
Ghép lại như sau: mỗi đơn có VA hoặc VietQR động, khách chuyển tiền, ACB báo giao dịch, MONA Pay gửi webhook có HMAC, web đổi đơn sang đã thanh toán, nhóm Telegram nhận tin, cuối ngày hệ thống đối soát. Bạn không cần ghi nhớ mọi thuật ngữ ngay; chỉ cần nhớ vai trò của từng lớp. Đọc lại tại monapay.vn/docs/khai-niem, đăng ký tại my.monapay.vn, hoặc gọi một chín không không, sáu ba sáu, sáu bốn tám khi cần hỗ trợ.
Khi dùng MONA Pay bạn sẽ gặp 7 từ: tài khoản ảo (VA), VietQR, webhook, Telegram, HMAC, API key và đối soát. Trang này giải thích từng từ theo cách chủ shop hay kế toán đọc là hiểu, mỗi mục có thêm vài dòng cho lập trình viên. Đọc xong trang này, bạn đủ hiểu để cấu hình dashboard mà không cần hỏi dev.
Tài khoản ảo (VA)
Cho người dùng. Tài khoản ảo là một số tài khoản phụ do ACB cấp, tiền chuyển vào đó vẫn về tài khoản chính của bạn. Điểm hay là bạn tạo được nhiều số ảo khác nhau, mỗi số gắn cho một đơn hàng hoặc một khách. Khách chuyển vào số nào, hệ thống biết ngay tiền của đơn nào, không cần khách gõ đúng nội dung chuyển khoản. Ví dụ đơn hàng số 1052 được gắn VA MONA1052..., khách chuyển vào đó là đơn 1052 tự đổi sang đã thanh toán.
Cho lập trình viên. VA được tạo theo đầu số (prefix) bạn đăng ký với ACB, quản lý trong dashboard mục Ngân hàng & VA hoặc qua API POST /api/v1/acb/virtual-account/registration. Webhook cấu hình được theo từng VA, nên bạn tách luồng tiền học phí, tiền hosting, tiền đơn lẻ vào các endpoint khác nhau. Chi tiết ở Tài khoản ảo (VA).
VietQR
Cho người dùng. VietQR là mã QR chuyển khoản chuẩn của các ngân hàng Việt Nam, app ngân hàng nào cũng quét được. MONA Pay tạo mã QR “động”: trong mã đã có sẵn số tài khoản, số tiền và nội dung. Khách quét là màn hình chuyển khoản hiện đủ thông tin, chỉ bấm xác nhận, không gõ sai được. Đơn 350.000đ thì QR ghi đúng 350.000đ.
Cho lập trình viên. Gọi POST /api/v1/acb/qr-payment/generate với orderId, amount (số nguyên VND, tối đa 1.000.000.000), description (tối đa 255 ký tự) và thông tin tài khoản. Khách quét và chuyển xong, ACB báo về, MONA Pay bắn webhook y như giao dịch qua VA. Hủy mã bằng DELETE /api/v1/acb/qr-payment/{qr_code_id}/cancellation. Xem QR thanh toán.
Webhook
Cho người dùng. Webhook là cách MONA Pay “gọi điện” cho phần mềm của bạn mỗi khi có tiền vào. Bạn cho MONA Pay một địa chỉ web (URL), có giao dịch là MONA Pay gửi một gói thông tin tới địa chỉ đó: số tiền, nội dung, thời gian, mã giao dịch. Phần mềm nhận được thì tự làm việc tiếp, ví dụ đổi trạng thái đơn, gửi email cho khách, mở khoá khoá học.
Cho lập trình viên. MONA Pay POST JSON tới URL của bạn, mặc định Content-Type: application/json. Endpoint trả HTTP 200, 201 hoặc 202 trong 10 giây là thành công. Payload 7 trường, khoá chống trùng là transaction_code. Xem Tích hợp webhook và Định dạng payload.
Telegram
Cho người dùng. Nếu bạn chỉ cần biết tiền vào, không cần phần mềm xử lý gì, thì thông báo Telegram là đủ. Thêm bot MONA Pay vào nhóm Telegram của công ty, mỗi lần tiền vào là cả nhóm nhận một tin: ngân hàng, số tài khoản, số tiền, thời gian, nội dung. Kế toán ngồi đâu cũng thấy, không phải đăng nhập app ngân hàng.
Cho lập trình viên. Cấu hình trong dashboard mục Telegram: nhập group_id (và topic_id nếu nhóm chia chủ đề), chọn VA hoặc mọi tài khoản, sửa mẫu tin nhắn, có nút gửi thử. API tại /api/v1/telegram-configs. Xem Telegram.
HMAC (chữ ký webhook)
Cho người dùng. Webhook là một địa chỉ web công khai, về lý thuyết ai biết địa chỉ cũng gửi được một gói giả “có tiền vào”. HMAC là chữ ký chống giả: bạn và MONA Pay giữ chung một mật khẩu bí mật (secret), mỗi gói MONA Pay gửi đều kèm một chữ ký tính từ secret đó. Phần mềm của bạn tính lại chữ ký, khớp thì tin, không khớp thì bỏ. Kẻ gian không có secret nên không làm giả được.
Cho lập trình viên. Header X-Mona-Signature: sha256=<hex> với hex = HMAC-SHA256(secret, "<X-Mona-Timestamp>.<raw_body>"). Timestamp là unix giây, lệch quá 5 phút thì từ chối để chặn gửi lại gói cũ (replay). Phải ký trên raw body đúng từng byte. Xem Bảo mật webhook.
API key và Bearer token
Cho người dùng. API key là chìa khoá để phần mềm của bạn gọi vào MONA Pay (tạo VA, tạo QR, xem giao dịch). Tạo trong dashboard mục API Keys, mỗi khoá đặt một tên để biết khoá nào đang dùng ở đâu, lộ khoá nào thì thu hồi khoá đó mà không ảnh hưởng chỗ khác.
Cho lập trình viên. Hai lớp: đăng nhập POST /api/v1/client/login lấy access_token gửi dạng Bearer cho mọi request; các request POST, PUT, DELETE thêm header X-Client-Secret là client_secret sinh từ POST /api/v1/client-keys/generate. client_secret chỉ hiện 1 lần. Mọi response chung khung {"success": true, "message": "...", "data": {...}}. Xem Xác thực và API keys.
Đối soát
Cho người dùng. Đối soát là việc so sổ của bạn với danh sách giao dịch ngân hàng để chắc không sót khoản nào. Webhook lo phần thời gian thực, nhưng máy chủ của bạn có lúc bảo trì hay mất mạng đúng lúc tiền vào. Đối soát định kỳ (mỗi giờ hoặc cuối ngày) là lưới đỡ cho những lúc đó.
Cho lập trình viên. Kéo danh sách bằng GET /api/v1/acb/virtual-account/transactions?virtual_account_number=...&page=1&limit=100, tối đa 100 giao dịch mỗi trang, so transaction_code với bảng giao dịch của bạn và bổ sung bản ghi thiếu. Xem Đối soát giao dịch.
Ghép các khái niệm lại
Một web bán hàng điển hình dùng như sau: mỗi đơn tạo một mã VietQR động (hoặc gắn một VA), khách quét và chuyển. ACB báo cho MONA Pay, MONA Pay bắn webhook có chữ ký HMAC tới web, web kiểm chữ ký rồi đổi đơn sang đã thanh toán. Nhóm Telegram của kế toán nhận tin cùng lúc. Cuối ngày một cron gọi API đối soát để chắc không sót. Toàn bộ chuỗi này không có người nào phải mở app ngân hàng.
Câu hỏi nhanh
Tiền có nằm ở MONA Pay lúc nào không? Không. VA là số phụ của chính tài khoản ACB của bạn, tiền vào là nằm trong tài khoản ngân hàng của bạn ngay. MONA Pay chỉ nhận thông báo.
Không có VA thì webhook có chạy không? Có. Sau khi nối tài khoản ACB và đăng ký nhận thông báo (2 lần OTP), mọi giao dịch vào tài khoản đều báo về. VA chỉ giúp khớp đơn tự động.
Nên dùng VA hay VietQR? Dùng cả hai. VietQR động là cách khách thanh toán tiện nhất, còn VA là cách hệ thống phân biệt tiền của đơn nào. Mã QR động của MONA Pay đã gắn sẵn số tiền và nội dung nên khớp đơn rất chắc.
HMAC có bắt buộc không? Không bắt buộc nhưng đội MONA khuyên bật luôn từ đầu. Chỉ tốn khoảng 10 dòng code ở đầu nhận, đổi lại không ai giả được thông báo tiền vào.