Điều kiện cần có từ SePay

Để sử dụng module này, người dùng cần có tài khoản SePay đang hoạt động và ít nhất một tài khoản ngân hàng đã liên kết trong SePay. Quyền truy cập API và Webhook phụ thuộc vào gói dịch vụ SePay mà người dùng đang sử dụng.

Các điều kiện cần có:

• Tài khoản SePay.
• Ít nhất một tài khoản ngân hàng Việt Nam đã liên kết trong SePay.
• API Token SePay để Odoo gọi API server-side.
• URL Odoo public để SePay có thể gửi HTTP POST.
• HTTPS/SSL cho webhook production.
• Gói SePay phù hợp với số lượng giao dịch tiền vào dự kiến mỗi tháng.

Lưu ý về chi phí

SePay công khai gói FREE với 50 giao dịch tiền vào mỗi tháng và có hỗ trợ Webhook/API. Nếu vượt giới hạn giao dịch của gói, SePay có thể tính phí vượt mức hoặc yêu cầu nâng cấp gói cao hơn.

Ngân hàng Việt Nam được hỗ trợ qua SePay

Theo thông tin công khai từ SePay, SePay đã kết nối API trực tiếp với các ngân hàng lớn tại Việt Nam, gồm:

• Vietcombank
• BIDV
• VietinBank
• MB
• ACB
• VPBank
• TPBank
• Sacombank
• MSB
• OCB
• KienLongBank

Các ngân hàng còn lại có thể được kết nối qua SMS Banking tùy theo hỗ trợ của SePay.

Ngân hàng hỗ trợ, quyền truy cập API, giới hạn gói và chi phí do SePay quản lý và có thể thay đổi theo thời gian.

Module này làm được gì?

Cấu hình ở sepay

Bước 1: Kết nối tài khoản ngân hàng trong SePay

Trước khi cấu hình Odoo, người dùng cần vào SePay để liên kết tài khoản ngân hàng muốn đồng bộ. Module chỉ có thể lấy dữ liệu từ các tài khoản ngân hàng đã được kết nối thành công trong SePay.

Các bước thực hiện:

1. Đăng nhập SePay.
2. Vào menu Ngân hàng.
3. Bấm Kết nối mới.
4. Chọn ngân hàng cần kết nối, ví dụ Vietcombank, ACB, BIDV, MB, VPBank hoặc ngân hàng khác được SePay hỗ trợ.
5. Hoàn tất quy trình liên kết tài khoản theo hướng dẫn của SePay.
6. Sau khi kết nối thành công, tài khoản sẽ hiển thị trong danh sách tài khoản ngân hàng của SePay.

Lưu ý: Trong Odoo, tài khoản ngân hàng này sẽ được đồng bộ bằng nút Sync Accounts. Sau đó kế toán cần map tài khoản SePay với đúng một sổ nhật ký ngân hàng trong Odoo.

Bước 2: Tạo Webhook trong SePay

Webhook giúp SePay gửi thông báo giao dịch ngân hàng về Odoo gần như realtime. Người dùng cần tạo webhook trong SePay và dán URL webhook do Odoo tạo ra.

Các bước thực hiện:

1. Trong SePay, vào menu Tích hợp WebHooks.
2. Bấm Thêm webhook.
3. Đặt tên webhook, ví dụ Odoo Webhook.
4. Dán URL webhook được tạo từ Odoo vào ô URL nhận webhook.
5. Chọn Loại giao dịch là Tất cả nếu muốn đồng bộ cả tiền vào và tiền ra.
6. Chọn Định dạng dữ liệu là JSON.
7. Có thể bật tự động gửi lại khi server lỗi nếu muốn SePay retry khi Odoo tạm thời không phản hồi.

Quan trọng: URL nhận webhook không tự nhập tùy ý. Người dùng cần copy URL này từ field SePay Webhook URL trong form kết nối SePay của Odoo.

Bước 3: Chọn tài khoản và bảo mật Webhook trong SePay

Sau khi nhập URL webhook, người dùng nên giới hạn webhook theo đúng tài khoản ngân hàng cần đồng bộ và chọn phương thức xác thực an toàn.

Ở tab Tài khoản:

1. Chọn Tùy chọn nếu chỉ muốn webhook áp dụng cho một số tài khoản cụ thể.
2. Chọn đúng tài khoản ngân hàng đã kết nối trong SePay.
3. Không cần bật Dùng để xác thực thanh toán nếu module chỉ dùng để đồng bộ giao dịch ngân hàng vào Odoo Accounting.

Ở tab Bảo mật:

1. Chọn HMAC-SHA256.
2. Tạo hoặc nhập Secret Key.
3. Copy Secret Key này sang Odoo, field SePay Webhook Secret.
4. Lưu webhook trong SePay.

Bảo mật: Không đưa Secret Key lên ảnh mô tả app, tài liệu public, GitHub hoặc email/chat. Khi chụp ảnh hướng dẫn, hãy che Secret Key và các thông tin tài khoản thật.

Bước 4: Điền gì trong Odoo?

Sau khi cấu hình SePay, người dùng quay lại Odoo để hoàn tất kết nối. Odoo cần API Token để polling giao dịch và cần Webhook Secret để xác thực request từ SePay.

Thứ tự thao tác trong Odoo:

1. Nhập API Token.
2. Bấm Test Connection.
3. Bấm Sync Accounts.
4. Map tài khoản SePay với journal ngân hàng trong Odoo.
5. Copy SePay Webhook URL từ Odoo sang SePay.
6. Dán Secret Key từ SePay về Odoo.
7. Bật Auto Fetch nếu muốn đồng bộ định kỳ.

Cấu hình kết nối SePay trong Odoo

Sau khi đã kết nối tài khoản ngân hàng và tạo webhook trong SePay, người dùng cần quay lại Odoo để tạo kết nối SePay, nhập API Token, cấu hình webhook secret và bật lịch đồng bộ tự động.

1. Mở màn hình Bank Connector

Các bước thực hiện:

1. Vào ứng dụng Invoicing hoặc Accounting.
2. Trên thanh menu, mở Configuration.
3. Trong nhóm Bank Connector, chọn Connections.
4. Bấm New để tạo kết nối mới hoặc mở kết nối SePay đã có.

Tài khoản ngân hàng SePay đã liên kết

Mỗi tài khoản ngân hàng từ SePay được map với đúng một sổ nhật ký ngân hàng trong Odoo. Module lưu số tài khoản, chủ tài khoản, thông tin ngân hàng, tiền tệ, số dư hiện tại và trạng thái đồng bộ để kế toán dễ kiểm tra.

Khuyến nghị:

• Một tài khoản SePay nên map với một sổ nhật ký ngân hàng Odoo.
• Tiền tệ của journal cần khớp với tiền tệ giao dịch.
• Nên dùng journal riêng cho từng tài khoản ngân hàng riêng.
• Có thể kiểm tra số dư hiện tại và thời gian giao dịch cuối cùng khi SePay cung cấp dữ liệu.

Log giao dịch trước khi tạo dữ liệu kế toán

Giao dịch SePay sau khi import sẽ được lưu vào log giao dịch riêng trước khi tạo dòng sao kê ngân hàng trong Odoo. Cách này giúp đồng bộ an toàn hơn, dễ audit hơn và dễ xử lý lại khi cần kiểm tra cấu hình hoặc dữ liệu từ nhà cung cấp.

Log giao dịch giúp bạn:

• Theo dõi trạng thái pending, processed, ignored và error.
• Lưu payload từ webhook và API để kế toán hoặc quản trị viên kiểm tra.
• Xử lý lại giao dịch lỗi sau khi sửa cấu hình.
• Mở trực tiếp dòng sao kê ngân hàng đã tạo từ log giao dịch.

An toàn khi kết hợp Webhook và API Polling

Tạo sao kê và đối soát

Lưu ý quan trọng

• Module này dành cho người dùng SePay tại Việt Nam và tập trung vào biến động tài khoản ngân hàng Việt Nam.
• Module này không phải sản phẩm chính thức của SePay.
• Module này không phải cổng thanh toán và không xử lý thanh toán thẻ hoặc checkout online.
• Người dùng cần có tài khoản SePay, tài khoản ngân hàng đã liên kết, API Token và gói SePay phù hợp.
• Giới hạn giao dịch, giao dịch miễn phí, phí vượt mức và ngân hàng hỗ trợ do SePay quản lý và có thể thay đổi.
• Nên test quyền truy cập Webhook/API với tài khoản SePay của bạn trước khi dùng cho production.
• Đối soát tự động được thiết kế thận trọng. Các trường hợp không rõ ràng sẽ được giữ lại để kế toán kiểm tra.

Tài liệu SePay tham khảo

• Bảng giá và giới hạn gói SePay: https://sepay.vn/bang-gia.html
• Ngân hàng hợp tác với SePay: https://sepay.vn/ngan-hang-hop-tac.html
• Bắt đầu nhanh với SePay API v2: https://developer.sepay.vn/vi/sepay-api/v2/bat-dau-nhanh
• Tổng quan SePay Webhooks: https://developer.sepay.vn/vi/sepay-webhooks
• Xác thực webhook SePay: https://developer.sepay.vn/vi/sepay-webhooks/xac-thuc

Important SePay Account Requirement

This module requires an active SePay account with bank accounts linked in SePay. SePay API and webhook access are provided by SePay packages. Please check SePay pricing, monthly incoming-transaction limits, and overage rules before using the connector in production.

Required items:

• A SePay account.
• At least one Vietnamese bank account linked in SePay.
• A SePay API token for server-side polling.
• A public Odoo URL that SePay can reach by HTTP POST.
• HTTPS/SSL for production webhook delivery.
• A suitable SePay package for your expected monthly incoming transactions.

Pricing Note

SePay publicly lists a FREE package with 50 incoming transactions per month and support for Webhook/API. If your monthly incoming transactions exceed the package limit, SePay may charge overage or require a higher package.

Supported Vietnamese Banks

SePay states that it connects directly by API with major Vietnamese banks, including:

• Vietcombank
• BIDV
• VietinBank
• MB
• ACB
• VPBank
• TPBank
• Sacombank
• MSB
• OCB
• KienLongBank

Other banks may be connected through SMS Banking depending on SePay support.

Actual bank availability, API access, package limits, and pricing are controlled by SePay and may change over time.

What the Connector Does

SePay Configuration

Step 1: Connect a Bank Account in SePay

Before configuring Odoo, users need to go to SePay and link the bank account they want to synchronize. The module can only fetch data from bank accounts that have been successfully connected in SePay.

Steps:

1. Log in to SePay.
2. Go to the Bank menu.
3. Click New Connection.
4. Select the bank to connect, for example Vietcombank, ACB, BIDV, MB, VPBank, or another bank supported by SePay.
5. Complete the bank-linking process following SePay's instructions.
6. After the connection is successful, the bank account will appear in the SePay bank account list.

Note: In Odoo, this bank account will be synchronized using the Sync Accounts button. After that, the accountant needs to map the SePay account to exactly one bank journal in Odoo.

Step 2: Create a Webhook in SePay

The webhook allows SePay to send bank transaction notifications to Odoo almost in realtime. Users need to create a webhook in SePay and paste the webhook URL generated by Odoo.

Steps:

1. In SePay, go to the WebHooks Integration menu.
2. Click Add Webhook.
3. Enter a webhook name, for example Odoo Webhook.
4. Paste the webhook URL generated by Odoo into the Webhook Receiving URL field.
5. Set Transaction Type to All if you want to synchronize both incoming and outgoing transactions.
6. Set Data Format to JSON.
7. Optionally enable automatic retry when the server returns an error, so SePay can retry if Odoo is temporarily unavailable.

Important: Do not enter the webhook receiving URL manually. Users should copy this URL from the SePay Webhook URL field on the SePay connection form in Odoo.

Step 3: Select Accounts and Secure the Webhook in SePay

After entering the webhook URL, users should limit the webhook to the correct bank account that needs to be synchronized and choose a secure authentication method.

In the Accounts tab:

1. Select Custom if you only want the webhook to apply to specific accounts.
2. Select the correct bank account that has been connected in SePay.
3. You do not need to enable Use for payment verification if this module is only used to synchronize bank transactions into Odoo Accounting.

In the Security tab:

1. Select HMAC-SHA256.
2. Generate or enter a Secret Key.
3. Copy this Secret Key to Odoo, into the SePay Webhook Secret field.
4. Save the webhook in SePay.

Security: Do not include the Secret Key in app description images, public documentation, GitHub, email, or chat. When taking screenshots for the guide, hide the Secret Key and all real account information.

Step 4: What to Fill in Odoo?

After configuring SePay, users return to Odoo to complete the connection. Odoo needs the API Token to poll transactions and the Webhook Secret to verify requests from SePay.

Recommended Odoo operation order:

1. Enter the API Token.
2. Click Test Connection.
3. Click Sync Accounts.
4. Map the SePay account to an Odoo bank journal.
5. Copy the SePay Webhook URL from Odoo to SePay.
6. Paste the Secret Key from SePay back into Odoo.
7. Enable Auto Fetch if you want periodic synchronization.

Configure the SePay Connection in Odoo

After the bank account and webhook have been configured in SePay, users need to return to Odoo to create the SePay connection, enter the API Token, configure the webhook secret, and enable automatic synchronization.

1. Open the Bank Connector Screen

Steps:

1. Open the Invoicing or Accounting app.
2. On the top menu, open Configuration.
3. Under the Bank Connector section, select Connections.
4. Click New to create a new connection, or open an existing SePay connection.

Linked SePay Bank Accounts

Each SePay bank account is mapped to exactly one Odoo bank journal. The connector keeps account number, holder name, bank information, currency, current balance, and synchronization status for review.

Best practice:

• One linked SePay account should map to one Odoo bank journal.
• The journal currency must match the transaction currency.
• Use separate Odoo bank journals for separate bank accounts when needed.
• Review current balance and last transaction time when SePay provides them.

Transaction Log Before Accounting Records

Imported SePay transactions are stored in a dedicated transaction log before being processed into Odoo bank statement lines. This makes synchronization safer, easier to audit, and easier to recover when provider data or accounting configuration needs review.

The transaction log helps you:

• Track pending, processed, ignored, and error transactions.
• Keep SePay webhook payload and API payload for accounting managers.
• Reprocess failed transactions after fixing configuration issues.
• Open generated Odoo statement lines directly from the transaction log.

API Polling + Webhook Safety

Statement Creation and Reconciliation

Important Notes

• This connector is for SePay users in Vietnam and is focused on Vietnamese bank account movements.
• This module is not an official SePay product.
• This module is not a payment acquirer and does not process card payments or checkout payments.
• A SePay account, linked bank account, API token, and suitable SePay package are required.
• SePay package limits, free transactions, overage fees, and supported banks are controlled by SePay and may change.
• Webhook/API access should be tested with your SePay account before using the connector in production.
• Automatic reconciliation is intentionally conservative. Unclear matches stay open for accountant review.

Official SePay References

• SePay pricing and package limits: https://sepay.vn/bang-gia.html
• SePay partner banks: https://sepay.vn/ngan-hang-hop-tac.html
• SePay API v2 quick start: https://developer.sepay.vn/vi/sepay-api/v2/bat-dau-nhanh
• SePay Webhooks overview: https://developer.sepay.vn/vi/sepay-webhooks
• SePay webhook authentication: https://developer.sepay.vn/vi/sepay-webhooks/xac-thuc