Webhook chỉ chạy được nếu tài khoản ngân hàng đã liên kết với SePay và ngân hàng hỗ trợ loại giao dịch đó. Bên dưới là danh sách ngân hàng nào làm được gì và cách cấu hình từng loại.
Hai loại VA
VA chính thức: ngân hàng cấp cho bạn một số tài khoản VA riêng. Khách chuyển tiền trực tiếp vào số VA đó, ngân hàng và SePay nhận diện giao dịch theo số đó.
VA nội dung (TKP): không có số tài khoản riêng. Khách chuyển vào tài khoản chính của bạn, kèm mã TKP trong nội dung chuyển khoản. SePay đối soát theo nội dung để biết giao dịch thuộc về đâu.
| Loại | Có số tài khoản VA riêng? | Cách nhận diện giao dịch |
|---|---|---|
| VA chính thức | Có (mỗi VA một số) | Theo số tài khoản VA khách chuyển vào |
| VA nội dung (TKP) | Không | Theo nội dung chuyển khoản |
Cả hai loại đều cấu hình tại chi tiết tài khoản ngân hàng trên Dashboard. TKP là viết tắt của "Tài khoản phụ", dùng khi cần phân bổ giao dịch theo đơn hàng hoặc chi nhánh mà ngân hàng không cấp VA chính thức. Mã TKP nằm đâu trong nội dung chuyển khoản cũng được, miễn khớp với TKP đã cấu hình.
Ở phía webhook, cả hai loại đều nằm ở trường subAccount trong payload, server của bạn xử lý y hệt nhau.
Ngân hàng hỗ trợ
Ngân hàng làm được gì còn tùy loại tài khoản bạn chọn khi liên kết: cá nhân, hộ kinh doanh hay doanh nghiệp.
| Ngân hàng | Loại tài khoản | Nhận tiền ở tài khoản chính | VA chính thức | Tiền vào | Tiền ra |
|---|---|---|---|---|---|
| ACB | Cá nhân, hộ kinh doanh, doanh nghiệp | Có | Có | Có | Có |
| BIDV | Cá nhân, hộ kinh doanh | Không, chỉ qua VA | Có | Có | Không |
| BIDV | Doanh nghiệp | Có | Có | Có | Có |
| KienlongBank | Cá nhân, hộ kinh doanh, doanh nghiệp | Không, chỉ qua VA | Có | Có | Không |
| MBBank | Cá nhân, hộ kinh doanh, doanh nghiệp | Có | Có | Có | Có |
| MSB | Cá nhân, hộ kinh doanh, doanh nghiệp | Không, chỉ qua VA | Có | Có | Không |
| OCB | Cá nhân, hộ kinh doanh, doanh nghiệp | Không, chỉ qua VA | Có | Có | Không |
| Sacombank | Cá nhân, hộ kinh doanh | Có | Có | Có | Có |
| Shinhan Bank | Doanh nghiệp | Có | Có | Có | Có |
| TPBank | Cá nhân, hộ kinh doanh, doanh nghiệp | Có | Không | Có | Có |
| Vietcombank | Doanh nghiệp, hộ kinh doanh | Không, chỉ qua VA | Có | Có | Không |
| VietinBank | Cá nhân, hộ kinh doanh | Có | Không | Có | Có |
| VietinBank | Doanh nghiệp dùng dịch vụ Thu hộ định danh MAP | Không, chỉ qua VA | Có | Có | Không |
| VietinBank | Doanh nghiệp không dùng MAP | Có | Có | Có | Không |
| VPBank | Cá nhân (VPBank NEO) | Tùy cách liên kết (xem dưới bảng) | Có | Có | Không |
| VPBank | Hộ kinh doanh (VPBank NEO) | Tùy cách liên kết (xem dưới bảng) | Có | Có | Không |
| VPBank | Hộ kinh doanh (VPBank NEOBiz) | Tùy cách liên kết (xem dưới bảng) | Có | Có | Không |
| VPBank | Doanh nghiệp (VPBank NEOBiz) | Có | Không | Có | Có |
Tài khoản ghi "Không, chỉ qua VA" không nhận giao dịch chuyển thẳng vào số tài khoản chính: bạn tạo ít nhất 1 VA chính thức và cho khách chuyển vào số VA. Tài khoản nhận tiền ở tài khoản chính mà ngân hàng không cấp VA chính thức (TPBank, VietinBank cá nhân và hộ kinh doanh, VPBank doanh nghiệp) vẫn phân bổ được giao dịch bằng TKP.
Khi liên kết VPBank cá nhân hoặc hộ kinh doanh, bạn chọn Công nghệ tài khoản ảo (VA) và có thể chọn thêm Đồng bộ tài khoản chính (chỉ tiền vào). Chỉ chọn VA thì tài khoản chỉ nhận tiền qua VA chính thức. Chọn thêm tài khoản chính thì nhận cả giao dịch chuyển thẳng vào số tài khoản chính, nhưng VPBank sắp ngừng nhận liên kết mới theo cách này.
Ngân hàng không có trong bảng thì chưa hỗ trợ webhook. Danh sách mới nhất ở Dashboard → Tài khoản ngân hàng → Thêm tài khoản: sau khi chọn ngân hàng và loại tài khoản, màn hình liệt kê đúng các tính năng của loại đó.
Liên kết tài khoản với SePay
Mỗi tài khoản cần liên kết trước khi webhook dùng được. Vào Dashboard → Tài khoản ngân hàng → Thêm tài khoản.
Bước 1: Chọn ngân hàng, chọn loại tài khoản (cá nhân, hộ kinh doanh hoặc doanh nghiệp), nhập số tài khoản.
Bước 2: Kết nối API. Điền thông tin đăng nhập internet banking hoặc kết nối qua OAuth (tuỳ ngân hàng). SePay chạy bước kiểm tra, thành công thì tài khoản chuyển sang trạng thái Hoạt động.
Bước 3: Tạo VA (nếu cần). Tài khoản ghi "Không, chỉ qua VA" trong bảng trên bắt buộc có ít nhất 1 VA. Tài khoản khác chỉ tạo VA khi cần phân bổ giao dịch.
Bước 4: Kiểm tra. Trạng thái tài khoản phải là Hoạt động (chấm xanh). Chuyển số tiền nhỏ vào tài khoản, vào Giao dịch kiểm tra SePay có nhận được không.
Tài khoản tạm ngưng hoặc mất kết nối sẽ không tạo giao dịch. Lúc này webhook không gửi không phải do webhook lỗi. Kiểm tra trạng thái tài khoản trước.
Chọn tài khoản cho webhook
Khi tạo webhook, chọn 1 trong 2 chế độ:
Tất cả tài khoản: webhook nhận mọi giao dịch từ mọi tài khoản bạn đã liên kết. Thêm tài khoản mới sau này, webhook tự nhận luôn.
Chọn cụ thể: bạn chọn tài khoản nào gắn vào webhook. Giao diện gồm 2 cột, bên trái là những tài khoản chưa chọn, bên phải là tài khoản đã thêm. Bấm để thêm hoặc bấm ✕ để bỏ. Mở rộng một tài khoản đã chọn sẽ hiện phần cấu hình VA.
Cấu hình VA cho từng ngân hàng
Mở rộng tài khoản đã chọn, bạn thấy:
Checkbox Tài khoản chính: nếu bật thì webhook nhận mọi giao dịch trên tài khoản, kể cả những giao dịch không qua VA. Nếu tắt, webhook chỉ nhận khi giao dịch khớp với VA đã tick phía dưới.
Danh sách VA: tick từng VA cần theo dõi. Webhook chỉ gửi khi subAccount của giao dịch trùng VA đã chọn.
Với tài khoản chỉ nhận qua VA (BIDV cá nhân và hộ kinh doanh, KienlongBank, MSB, OCB, Vietcombank): checkbox Tài khoản chính tự khoá, bắt buộc chọn ít nhất 1 VA. VietinBank doanh nghiệp dùng MAP cũng chỉ nhận qua VA nhưng checkbox không tự khoá: bật Tài khoản chính cũng không nhận thêm giao dịch nào, nên chỉ cần tick các VA cần theo dõi.
Trong cùng một webhook, Ngân hàng A có thể nhận hết, còn Ngân hàng B chỉ nhận qua VA. Không cần tạo 2 webhook riêng.
Lưu ý khi chọn Chỉ tiền ra
Loại Tất cả và Chỉ tiền vào dùng cho mọi ngân hàng. Riêng Chỉ tiền ra chỉ chọn được cho tài khoản có cột Tiền ra là Có trong bảng ngân hàng hỗ trợ, và không lọc theo VA chính thức được: cần lọc theo VA thì dùng TKP.
Giao diện sẽ chặn và báo nếu bạn cố lưu cấu hình không hợp lệ.
Ví dụ cấu hình
Công ty có 3 tài khoản: MBBank, BIDV cá nhân và TPBank. Yêu cầu:
- MBBank: nhận mọi giao dịch.
- BIDV: chỉ nhận VA mã
ORDER001. - TPBank: bỏ qua hoàn toàn.
Các bước:
- Chế độ chọn: Chọn cụ thể.
- Thêm MBBank và BIDV vào cột đã chọn. Không thêm TPBank.
- Mở rộng MBBank: bật Tài khoản chính.
- Mở rộng BIDV: Tài khoản chính tự khoá (BIDV cá nhân chỉ nhận qua VA), tick VA
ORDER001.
Kết quả:
| Giao dịch | Webhook gửi? |
|---|---|
| Tiền vào MBBank không qua VA | Có |
| Tiền vào MBBank qua VA bất kỳ | Có |
Tiền vào BIDV qua VA ORDER001 | Có |
Tiền vào BIDV qua VA ORDER002 | Không |
| Tiền vào TPBank | Không (không trong danh sách) |
Tiếp theo
- Tạo webhook: form 4 bước, bộ lọc và gửi thử
- Tích hợp webhook: payload và phản hồi hợp lệ
- Webhook không gửi?: checklist chẩn đoán
Thay đổi cấu hình tài khoản có hiệu lực ngay với giao dịch tiếp theo. Giao dịch đã gửi trước đó không bị ảnh hưởng.