Tổng quan
Hạ Tầng Thanh toán nhận chuyển khoản VietQR thẳng vào tài khoản ngân hàng của chính bạn, báo cho server của bạn ngay khi tiền về, và có thể phát hành hóa đơn điện tử cho đơn hàng.
Hạ Tầng không giữ tiền. Người mua chuyển vào tài khoản của bạn; Hạ Tầng đọc biến động số dư của tài khoản và khớp với đơn hàng. Tiền không nằm trong ví chờ rút về, và không có tài khoản trung gian nào ở giữa.
Dành cho ai
- Website bán hàng: mã QR riêng cho từng đơn, tự xác nhận khi khách chuyển khoản.
- Cửa hàng, quầy thu ngân: một mã QR in sẵn, và thông báo cho mọi giao dịch có mã đơn của bạn.
- SaaS, dịch vụ thuê bao: thu tiền gói và tự phát hành hóa đơn điện tử khi đã thanh toán.
- Nền tảng, phần mềm kế toán: đồng bộ giao dịch ngân hàng và hóa đơn qua API và webhook.
Người mua thấy gì
Luồng hoạt động
- Bạn liên kết tài khoản ngân hàng một lần (dashboard → Cài đặt thanh toán → Tài khoản ngân hàng).
- Bạn tạo một payment cho mỗi đơn, hoặc chỉ cần đưa số tài khoản và để Hạ Tầng báo mọi giao dịch.
- Người mua quét VietQR bằng app ngân hàng bất kỳ tại Việt Nam, hoặc chuyển khoản thủ công với mã thanh toán trong nội dung.
- Ngân hàng báo cho Hạ Tầng. Hạ Tầng khớp mã với payment và gọi server của bạn: IPN tới URL bạn khai báo cho payment đó, và webhook cho toàn doanh nghiệp.
- Nếu bạn yêu cầu, Hạ Tầng tạo hóa đơn tại nhà cung cấp của bạn, gửi ký, rồi trả về số hóa đơn và mã tra cứu.
Ngân hàng
Mỗi ngân hàng liên kết theo cách riêng. Những ngân hàng bạn chọn được ở mỗi môi trường được liệt kê tại Cài đặt thanh toán → Tài khoản ngân hàng → Thêm tài khoản ngân hàng.
| Ngân hàng | provider | Cách liên kết | Hạ Tầng biết tiền về bằng cách | Môi trường |
|---|---|---|---|---|
| MB Bank | mbbank | MB nhắn mã tới chủ tài khoản | Thông báo biến động số dư theo thời gian thực | production |
| BIDV | bidv | Bạn đăng ký dịch vụ thông báo biến động số dư tại BIDV; tài khoản kích hoạt khi BIDV gửi tin đầu tiên | Thông báo biến động số dư theo thời gian thực | production |
| ACB | acb | Chủ tài khoản đồng ý trên trang của ACB (Open API theo Thông tư 64/2024/TT-NHNN) | Đọc lịch sử tài khoản mỗi 10 phút | production |
| Pay2S | pay2s | Bạn tạo Hook trên Pay2S và dán token của nó; tài khoản kích hoạt khi có giao dịch đầu tiên | Pay2S đẩy về theo thời gian thực | production |
| Ngân hàng giả lập | simulator | Mã 000000 | Giả lập bằng API | development |
Pay2S đọc được tài khoản tại Vietcombank, VietinBank, Techcombank, BIDV, ACB, MB Bank và TPBank. Với bất kỳ ngân hàng nào, bạn cũng có thể khôi phục giao dịch bằng cách nhập sao kê.
Nhà cung cấp hóa đơn điện tử
| Nhà cung cấp | development | production |
|---|---|---|
| Mắt Bão | Sandbox demo của nhà cung cấp, không gửi cơ quan thuế | Hóa đơn thật theo mã số thuế của bạn |
Ba cách tích hợp
| Chỉ nhận giao dịch | Đơn hàng | Đơn hàng + hóa đơn điện tử | |
|---|---|---|---|
| Tạo gì cho mỗi đơn | Không | POST /payments | POST /payments kèm invoice |
| Người mua ghi gì vào nội dung | Mã đơn của bạn (vd DH1001) | Mã thanh toán (vd HTBF7RDGVQ, hoặc code của bạn) | Như bên trái |
| Hạ Tầng báo gì | transaction.received kèm mã tìm được | Đã trả, trả thiếu, trả thừa, hết hạn | Như bên trái, kèm số hóa đơn |
| Trang checkout và hạn thanh toán | Không | Có | Có |
| Hóa đơn điện tử | Chỉ khi bạn tự tạo (POST /einvoices kèm transaction_id) | Không | Tự tạo khi đã thanh toán |
| Hướng dẫn | Nhận giao dịch | Tạo thanh toán | Hóa đơn điện tử |
Có thể dùng lẫn các cách trên cùng một tài khoản ngân hàng. Giao dịch luôn được khớp với payment trước, nên một payment không bao giờ bị báo hai lần.
Bạn có gì
- Tiền về thẳng tài khoản của bạn, không qua ví, không chờ rút.
- Xác nhận trong vài giây với ngân hàng đẩy biến động số dư.
- Tự động khớp mã thanh toán, xử lý cả trả thiếu, trả thừa, hết hạn và tiền về muộn.
- Tự phát hành hóa đơn điện tử khi đơn đã thanh toán, kèm báo cáo đối soát tiền vào chưa có hóa đơn.
- Trang checkout có sẵn, cập nhật trực tiếp, không cần đăng nhập.
- Hai môi trường tách biệt, có ngân hàng giả lập để test trọn luồng.
- Lời gọi có chữ ký: HMAC-SHA256 cho IPN, chữ ký Svix cho webhook, mỗi loại gửi tối đa 8 lần.
- SDK Node.js có các hàm xác minh chạy được cả trên Bun, Deno, Vercel và Cloudflare Workers.
Bước tiếp theo
- Bắt đầu nhanh: nhận khoản thanh toán đầu tiên ở môi trường development trong khoảng mười phút.
- Môi trường và sandbox: development và production khác nhau thế nào.
- Tạo thanh toán: mọi trường, trạng thái và tình huống đặc biệt.
- Tham chiếu REST API: toàn bộ endpoint.