SePay — thanh toán tự động

SePay là cổng thanh toán tự động mà TrolyPage dùng để: (1) sinh mã QR VietQR cho khách, (2) tự xác nhận khi khách chuyển khoản xong (qua webhook). Không cần đối soát thủ công, không cần check sổ ngân hàng.

Vấn đề SePay giải quyết

Trước khi có SePay, khi khách muốn thanh toán:

1. Bạn gửi STK + số tiền qua chat.
2. Khách chuyển khoản.
3. Bạn phải mở app ngân hàng kiểm tra xem tiền về chưa.
4. Khách hỏi “anh ơi chuyển xong rồi” → bạn phải xác nhận bằng tay.
5. Sai số tiền / sai nội dung → đối soát tay đau đầu.

SePay tự hoá toàn bộ 2-3-4-5:

1. AI/operator gửi QR VietQR (có sẵn số tiền + nội dung) trong chat.
2. Khách quét QR chuyển khoản.
3. SePay tự phát hiện giao dịch đến → gửi webhook về TrolyPage.
4. TrolyPage tự xác nhận đơn đã thanh toán → AI báo “Đã nhận thanh toán”.
5. Bạn không cần đụng tay.

2 luồng thanh toán

SePay phục vụ 2 luồng khác nhau, đừng nhầm:

Luồng A — Khách trả tiền cho shop (trên chat)

Khách chat với AI trên Facebook/Zalo/Messenger → đặt hàng → AI gửi QR → khách chuyển → SePay webhook → đơn tự xác nhận.

Bước	Ai làm
1. Đặt hàng	Khách chat với AI
2. AI sinh QR	AI gọi tool GeneratePaymentQR → VietQR + STK + số tiền + nội dung
3. Khách CK	Quét QR với app ngân hàng
4. Webhook SePay	POST /webhook/sepay/{configId} → TrolyPage tự ghi nhận
5. AI báo	AI gọi tool CheckPayment → xác nhận → báo khách “Đã thanh toán”
6. Admin notify	Bạn nhận thông báo + đơn tự chuyển trạng thái “Đã thanh toán”

Luồng B — Shop trả phí TrolyPage (subscription)

Shop đăng ký gói TrolyPage → nhận hóa đơn → vào /app/checkout/{invoiceCode} → QR + thông tin CK → polling 5s → xong hiện confetti.

Bước	Ai làm
1. Nhận invoice	Shop vào /app/billing xem hóa đơn
2. Vào checkout	Bấm Thanh toán ngay → /app/checkout/{invoiceCode}
3. Quét QR	Shop quét VietQR + CK đúng nội dung
4. Webhook	POST /webhook/billing/sepay → TrolyPage tự match
5. Polling	Trang checkout poll 5s → phát hiện paid → confetti
6. Auto-deposit (nếu sai nội dung)	CK khớp Virtual Account → tự nạp ví

Xem chi tiết Luồng B ở Checkout how-to.

QR VietQR — chuẩn Việt Nam

SePay sinh QR theo chuẩn VietQR (NBCL chuẩn hóa VN), dùng dịch vụ công img.vietqr.io:

https://img.vietqr.io/image/{bin}-{stk}-compact2.png?amount=...&addInfo=...&accountName=...

QR này khách quét bằng bất kỳ app ngân hàng VN nào (MB, VCB, ACB, Techcombank…) đều nhận được.

20 ngân hàng được hỗ trợ

Ngân hàng	BIN	Ngân hàng	BIN
Vietcombank	970436	Sacombank	970403
Techcombank	970407	HDBank	970437
MB Bank	970422	OCB	970448
ACB	970416	SHB	970443
VPBank	970432	Eximbank	970431
BIDV	970418	MSB	970426
Vietinbank	970415	Nam A Bank	970428
Agribank	970405	LPBank	970449
TPBank	970423	VIB	970441
		SCB	970429
		BaoViet Bank	970438

Ngân hàng ngoài list vẫn dùng được nếu STK + bank brand match, nhưng BIN không tự resolve.

Nội dung chuyển khoản — quan trọng

SePay match theo nội dung CK (transfer content), KHÔNG phải chỉ theo số tiền. Đừng bao giờ CK nội dung sai:

• Luồng A (đơn hàng): nội dung = mã đơn (vd ORD7XK2P).
• Luồng B (invoice): nội dung = mã hóa đơn (vd PLAB12CD34).

CK sai nội dung = không xác nhận

Nếu khách nhập nội dung linh tinh (“chuyen khoan cho shop”) → SePay không match được → webhook đến nhưng rơi vào unmatched → admin nhận thông báo để đối soát tay. Luôn dặn khách giữ nguyên nội dung.

Webhook tự xác nhận

SePay gọi webhook về TrolyPage khi có giao dịch đến. 2 endpoint:

Endpoint	Phục vụ	Auth
POST /webhook/billing/sepay	Subscription (Luồng B)	Apikey header
POST /webhook/sepay/{configId}	Đơn hàng khách (Luồng A)	Apikey header + id tenant

Idempotent

Cùng 1 giao dịch mà webhook gọi 2 lần → TrolyPage chỉ ghi nhận 1 lần (chống duplicate). Không lo trùng lệnh.

Khi không match được

Webhook đến nhưng không match invoice/đơn nào → rơi vào “unmatched” → admin TrolyPage nhận thông báo để xử lý tay. Trường hợp này thường do khách:

• CK sai nội dung.
• CK sai số tiền (khác mã invoice).
• CK từ tài khoản khác tên.

Tự xác nhận vs thủ công

	Tự xác nhận (SePay OAuth)	Thủ công (VietQR manual)
Cách	OAuth SePay → tự lấy STK + tạo webhook	Nhập STK tay trong tab Thanh toán
Auto-confirm	Có — webhook tự	Không — phải check app ngân hàng rồi duyệt tay
Khuyên dùng	Có	Chỉ khi không có SePay

Luôn ưu tiên kết nối SePay OAuth (Luồng A mới hoạt động trơn). Xem SePay connect how-to.

Nguồn tiền AI gửi QR từ đâu

SePay dùng chính STK ngân hàng bạn kết nối (trong tab Thanh toán) làm nguồn nhận. AI không cần biết STK shop — chỉ gọi tool GeneratePaymentQR + truyền số tiền → SePay sinh QR từ STK đã cấu hình.

1 shop = 1 STK chính

Mỗi shop cấu hình 1 STK ngân hàng chính qua SePay OAuth. Mọi QR AI gửi cho khách đều trỏ về STK này. Nếu có nhiều STK → cấu hình nhiều config, chọn 1 làm default.

Bước tiếp theo

• Kết nối SePay how-to — OAuth wizard 3 bước + multi-gateway.
• Tab Thanh toán & Vận chuyển — tổng quan 2 tab còn lại.
• Checkout how-to — luồng B (trả phí TrolyPage).
• Đơn hàng — đơn tự xác nhận khi khách CK xong.