Cách nhận thanh toán tự động qua SePay cho bot bán hàng Telegram

Để bot Telegram tự xác nhận chuyển khoản, bạn liên kết tài khoản ngân hàng với SePay, tạo một webhook trỏ về máy chủ chạy bot, rồi khai báo khóa xác thực webhook trong cấu hình bot. Khi khách chuyển tiền, SePay phát hiện biến động số dư và gửi ngay một HTTP POST chứa thông tin giao dịch tới bot; bot đối chiếu nội dung chuyển khoản với mã đơn rồi giao hàng. Toàn bộ diễn ra trong khoảng mười giây, không cần người trực.

Bài này đi qua đủ cả phần cấu hình lẫn phần xử lý các tình huống hay hỏng: webhook bị gửi lại nhiều lần, khách chuyển sai nội dung, và đường dự phòng khi webhook chết.

Vì sao không nên đối soát bằng tay

Bán hàng số mà đối soát thủ công có ba vấn đề không thể khắc phục bằng cách chăm chỉ hơn:

• Độ trễ. Khách hàng số quen với việc nhận hàng ngay. Chờ mười phút đã là lâu, chờ tới sáng hôm sau thì phần lớn đã hủy.
• Sai sót. Đọc nhầm số tiền, bỏ sót một giao dịch giữa hàng chục dòng biến động, giao hai lần cho một lần chuyển khoản.
• Không ngủ được. Đơn hàng số về vào mọi khung giờ, kể cả 2 giờ sáng.

SePay hoạt động thế nào

SePay kết nối với tài khoản ngân hàng của bạn, phát hiện biến động số dư và bắn webhook đến hệ thống của bạn, toàn bộ diễn ra trong khoảng mười giây. Nói cách khác, SePay đóng vai người ngồi canh màn hình ngân hàng, nhưng làm việc đó liên tục và không bao giờ đọc nhầm.

Luồng đầy đủ khi ghép với một bot bán hàng:

1. Khách chọn sản phẩm trong bot, bot tạo đơn có mã riêng.
2. Bot sinh mã QR chuyển khoản với đúng số tiền và nội dung chứa mã đơn.
3. Khách quét QR và chuyển khoản.
4. SePay phát hiện tiền vào, gửi POST tới webhook của bot.
5. Bot đọc nội dung chuyển khoản, tìm ra đơn tương ứng, kiểm tra số tiền.
6. Bot lấy một suất hàng từ kho và giao ngay trong chat, kèm file để khách lưu.

Cần chuẩn bị gì

• Một tài khoản SePay, đăng ký tại my.sepay.vn.
• Một tài khoản ngân hàng thuộc danh sách SePay hỗ trợ, đã liên kết và xác nhận qua OTP.
• Một tên miền trỏ được về máy chủ chạy bot - webhook cần một URL công khai trên Internet.
• Bot đã cài xong và chạy được trên VPS.

Sáu bước cấu hình

1. Liên kết tài khoản ngân hàng

   Đăng nhập SePay, thêm tài khoản ngân hàng và xác nhận qua OTP. Sau bước này SePay bắt đầu đọc được biến động số dư của tài khoản đó. Kiểm tra kỹ số tài khoản: đây phải đúng là tài khoản bạn sẽ in lên mã QR cho khách.

2. Tạo khóa xác thực webhook

   Sinh một chuỗi ngẫu nhiên đủ dài làm API key, ví dụ bằng lệnh:

   openssl rand -base64 48

   Chuỗi này sẽ được khai báo ở cả hai phía - trong SePay và trong cấu hình bot. Nó chính là thứ ngăn người lạ giả mạo thông báo thanh toán để lấy hàng miễn phí.

3. Tạo webhook trên SePay

   Trong SePay, tạo webhook mới với đường dẫn trỏ về bot, ví dụ https://ten-mien-cua-ban.com/hooks/sepay-payment. SePay hỗ trợ bốn phương thức xác thực: HMAC-SHA256, API Key, OAuth 2.0 và không xác thực; với API Key, SePay gửi header Authorization dạng "Apikey" kèm khóa của bạn. Chọn API Key và dán chuỗi vừa sinh. Đặt bộ lọc chỉ theo dõi tiền vào.

4. Khai báo trong cấu hình bot

   Mở file cấu hình của bot và điền các giá trị tương ứng:

   WEBHOOK_HOST=127.0.0.1
   WEBHOOK_PORT=8080
   WEBHOOK_PATH=/hooks/sepay-payment
   WEBHOOK_API_KEY=chuoi-ban-vua-sinh
   PAYMENT_SOURCE=webhook,sheet
   BANK_ACCOUNT=so-tai-khoan-nhan-tien
   ORDER_PREFIX=VQ

   Giữ WEBHOOK_HOST là 127.0.0.1. Bot chỉ lắng nghe nội bộ, việc đưa ra Internet để cho bước sau lo.

5. Đưa webhook ra Internet qua Cloudflare Tunnel

   Thay vì mở cổng 8080 ra ngoài, dùng Cloudflare Tunnel để đẩy lưu lượng từ tên miền về 127.0.0.1:8080. Cách này an toàn hơn hẳn: máy chủ không lộ cổng nào ra Internet, và bạn được chặn tấn công ở tầng Cloudflare. Sau khi bật tunnel, kiểm tra:

   curl -i https://ten-mien-cua-ban.com/health

   Phải nhận về HTTP 200. Nếu không, webhook chưa chạy hoặc tunnel chưa trỏ đúng.

6. Chạy thử trước khi mở bán

   Tạo một sản phẩm thử giá 0đ để kiểm tra luồng bot và kho trước. Sau đó tạo một đơn giá nhỏ, tự chuyển khoản, và xác nhận ba việc: mã QR đúng tài khoản, hàng được giao đúng một lần, và không còn đơn nào mắc kẹt ở trạng thái chờ.

Chống giao trùng - phần quan trọng nhất

Đây là chỗ nhiều người tự làm bị sai và chỉ phát hiện khi đã mất hàng.

SePay tự động gửi lại webhook tối đa 7 lần trong khoảng 33 phút khi endpoint gặp lỗi. Ngoài ra bạn có thể gửi lại thủ công, hoặc lỡ cấu hình nhiều webhook cùng trỏ về một địa chỉ. Hệ quả: cùng một giao dịch có thể tới endpoint của bạn nhiều lần.

Nếu hệ thống giao hàng ngay mỗi lần nhận webhook mà không kiểm tra, một lần khách chuyển khoản có thể lấy đi ba bốn suất hàng trong kho.

Cách xử lý đúng: đặt cột mã giao dịch là UNIQUE trong cơ sở dữ liệu rồi ghi nhận trước khi xử lý. Lần webhook thứ hai của cùng một giao dịch sẽ bị cơ sở dữ liệu chặn, hệ thống trả về 200 và bỏ qua, không giao thêm lần nữa.

Nếu bạn tắt bộ lọc mã thanh toán

SePay cho phép chỉ gửi webhook khi nội dung giao dịch có chứa mã thanh toán. Bật bộ lọc này thì webhook sạch, nhưng khách sửa nội dung là giao dịch đó không về tới bạn và bạn không hề biết có người vừa trả tiền.

Tắt bộ lọc thì ngược lại: mọi khoản tiền vào đều sinh webhook, bạn không bỏ sót giao dịch nào, nhưng hệ thống phải tự lọc. Khi đó handler cần kiểm tra thêm bốn điều trước khi giao hàng: đúng loại tiền vào, đúng tài khoản nhận, tìm được mã đơn trong nội dung, và số tiền không nhỏ hơn giá đơn. Giao dịch không khớp thì vẫn ghi nhận và trả về thành công, chỉ đơn giản là không làm gì thêm.

Đừng trả mã lỗi cho những giao dịch không liên quan. SePay sẽ coi là gửi thất bại và thử lại nhiều lần cho một giao dịch vốn chẳng liên quan gì tới đơn hàng của bạn.

Đường dự phòng khi webhook chết

Webhook nhanh nhưng phụ thuộc vào việc máy chủ của bạn còn sống và tên miền còn phân giải được. Nếu VPS khởi động lại đúng lúc khách chuyển tiền, webhook đó có thể mất.

Cách chắc ăn là chạy song song hai nguồn xác nhận: webhook lo tốc độ, và một nguồn đọc lại danh sách giao dịch theo chu kỳ lo phần sót. Cả hai cùng đi qua một cơ chế chống trùng theo mã giao dịch, nên chạy song song không gây giao hai lần.

Ngoài ra nên có sẵn một lệnh quản trị để rà những đơn đã nhận tiền nhưng chưa giao đủ và giao lại - phòng trường hợp cả hai nguồn cùng lỡ.

Bốn lỗi hay gặp

Về trường hợp khách sửa nội dung chuyển khoản: đây là tình huống không tránh được hoàn toàn, vì một số ứng dụng ngân hàng tự thêm chữ vào nội dung. Cách giảm thiểu là dùng tiền tố mã đơn ngắn, dễ gõ, và hướng dẫn khách quét QR thay vì nhập tay - QR đã điền sẵn đúng nội dung.

Câu hỏi thường gặp

SePay có giữ tiền của tôi không?

Không. Tiền vào thẳng tài khoản ngân hàng của bạn như một giao dịch chuyển khoản thông thường. SePay chỉ đọc thông tin giao dịch và gửi thông báo cho hệ thống của bạn, không phải cổng thanh toán trung gian giữ tiền.

Không có tên miền thì dùng webhook được không?

Không. Webhook cần một địa chỉ công khai để SePay gửi POST tới. Bạn cần một tên miền, và nên đưa ra Internet qua Cloudflare Tunnel thay vì mở cổng trực tiếp trên máy chủ.

Nếu webhook của tôi chết vài phút thì giao dịch có mất không?

SePay tự gửi lại webhook tối đa 7 lần trong khoảng 33 phút khi endpoint lỗi, nên sự cố ngắn thường tự khắc phục. Với sự cố dài hơn, nên có thêm một nguồn xác nhận dự phòng đọc lại danh sách giao dịch theo chu kỳ.

Khách chuyển sai nội dung thì xử lý thế nào?

Giao dịch vẫn về tài khoản nhưng hệ thống không khớp được với đơn nào. Bạn cần một màn hình quản trị để tra cứu đơn đang chờ và giao tay cho khách đó. Cách giảm thiểu là hướng dẫn khách quét mã QR thay vì nhập nội dung bằng tay.

Có thể dùng nhiều tài khoản ngân hàng cùng lúc không?

Được, nhưng phải khai báo đủ để hệ thống đối chiếu. Khi đổi sang tài khoản mới, hãy giữ tài khoản cũ trong danh sách một thời gian vì vẫn có thể còn đơn với mã QR cũ chưa thanh toán.