Đ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.

Tích hợp trực tiếp với Odoo Enterprise Accounting

Phiên bản Enterprise này kết nối SePay trực tiếp với Odoo Enterprise Accounting. Module sử dụng các công cụ gốc của Odoo Enterprise như Online Bank Synchronization, Bank Journal Dashboard, Bank Statement Lines và Bank Reconciliation thay vì tạo một workflow kế toán riêng.

Các công cụ Odoo Enterprise được sử dụng:

• Online Bank Synchronization: SePay được kết nối như một nhà cung cấp đồng bộ ngân hàng online, sử dụng các model online bank gốc của Odoo Enterprise.
• Bank Journal Dashboard: Người dùng có thể kết nối SePay từ dashboard của bank journal và theo dõi giao dịch đã fetch từ dashboard kế toán tiêu chuẩn.
• Bank Statement Lines: Giao dịch SePay sau khi import sẽ trở thành dòng sao kê ngân hàng gốc của Odoo, không phải bản ghi kế toán custom.
• Bank Reconciliation Widget: Kế toán đối soát giao dịch SePay bằng màn hình đối soát tiêu chuẩn của Odoo Enterprise.
• Reconciliation Models: Module có thể chuẩn bị reconciliation model theo mã tham chiếu chính xác để hỗ trợ match tự động an toàn hơn.

Lưu ý Enterprise: Module này được thiết kế cho Odoo Enterprise Accounting. Module yêu cầu account_accountant và account_online_synchronization. Module này khác với bản Community Financial Account Connector Engine.

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 và 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 ngân hàng sẽ xuất hiện 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ộ sau khi bấm Connect trong wizard SePay. Sau đó kế toán cần map tài khoản SePay với đúng một bank journal trong Odoo.

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

Webhook cho phé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.

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. Nhập tên webhook, ví dụ Odoo Webhook.
4. Dán URL webhook do Odoo tạo 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 trả lỗi để SePay thử gửi lại nếu Odoo tạm thời không phản hồi.

Quan trọng: Không tự nhập URL nhận webhook thủ công. Người dùng nên copy URL này từ field SePay Webhook URL trên form kết nối SePay trong 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.

Trong 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 đã được 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.

Trong 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, vào 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, email hoặc chat. Khi chụp ảnh hướng dẫn, hãy che Secret Key và toàn bộ thông tin tài khoản thật.

Cấu hình SePay trong Odoo Enterprise

Sau khi kết nối tài khoản ngân hàng và tạo webhook trong SePay, người dùng hoàn tất cấu hình trong Odoo Enterprise. Module lưu thông tin SePay trên online bank synchronization link của Odoo và map tài khoản ngân hàng SePay với bank journal trong Odoo.

1. Mở SePay Connection Wizard

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

1. Mở ứng dụng Accounting hoặc Invoicing.
2. Vào Accounting Dashboard.
3. Trên bank journal của công ty Việt Nam, bấm Connect SePay nếu nút này hiển thị.
4. Có thể vào thêm từ Accounting / Configuration / Banks / SePay Connections.
5. Tạo kết nối SePay mới hoặc mở một SePay online synchronization link đã có.

Map tài khoản SePay với Bank Journal trong Odoo

Sau khi API token được xác thực, Odoo sẽ lấy danh sách tài khoản ngân hàng đã liên kết với tài khoản SePay. Người dùng sau đó map mỗi tài khoản ngân hàng online của SePay với một bank journal trong Odoo bằng luồng account-to-journal linking gốc của Odoo Enterprise.

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

1. Bấm Connect trong SePay wizard.
2. Odoo lấy danh sách tài khoản ngân hàng liên kết với SePay API Token.
3. Chọn tài khoản SePay online cần kết nối.
4. Map tài khoản SePay online với đúng bank journal trong Odoo.
5. Odoo Enterprise đặt nguồn sao kê của journal sang online synchronization.
6. Nên dùng một Odoo bank journal cho mỗi tài khoản ngân hàng SePay.

Khuyến nghị: Tiền tệ của Odoo bank journal nên khớp với tiền tệ của tài khoản SePay. Module này tập trung vào biến động ngân hàng Việt Nam và import tài khoản SePay bằng VND.

Copy Odoo Webhook URL sang SePay

Nếu webhook được bật trong Odoo, Odoo sẽ tạo SePay Webhook URL trên online synchronization link. Copy URL này sang SePay để SePay có thể thông báo cho Odoo khi có biến động ngân hàng.

Lưu ý production: Nếu webhook URL được tạo vẫn chứa localhost hoặc domain test, hãy cấu hình domain public của Odoo trước khi copy sang SePay. SePay phải gọi được URL này từ internet.

Đối soát thủ công bằng Odoo Enterprise

Giao dịch SePay được import vào Odoo dưới dạng dòng sao kê ngân hàng gốc của Odoo. Kế toán có thể đối soát các giao dịch này từ Bank Reconciliation widget tiêu chuẩn của Odoo Enterprise, sử dụng gợi ý tự động, bút toán có sẵn hoặc manual operations.

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

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

1. Mở Accounting Dashboard.
2. Tìm bank journal đã kết nối với SePay.
3. Bấm Reconcile Items trên thẻ bank journal.
4. Odoo mở bank reconciliation widget gốc với các dòng sao kê SePay đã import.

Đồng bộ và Audit Logs

Module Enterprise này import giao dịch SePay qua pipeline online synchronization gốc của Odoo. Dữ liệu từ SePay API polling và webhook được lưu trong audit log trước khi tạo dòng sao kê ngân hàng.

Hành vi chính:

• Webhook event được Odoo nhận và lưu vào SePay transaction audit log.
• Scheduled synchronization lấy lại các giao dịch bị lỡ hoặc bị trễ từ SePay API v2.
• Dữ liệu webhook và API được chống trùng trước khi tạo dòng sao kê.
• Giao dịch import được chuyển thành dòng sao kê ngân hàng gốc của Odoo Enterprise.
• Lỗi được lưu trên SePay transaction log để Accounting Manager kiểm tra.

Thứ tự thao tác khuyến nghị:

1. Kết nối SePay trong Odoo Enterprise.
2. Fetch tài khoản ngân hàng SePay.
3. Link mỗi tài khoản SePay với một Odoo bank journal.
4. Copy Odoo Webhook URL sang SePay.
5. Dán SePay Secret Key ngược lại vào Odoo.
6. Dùng Odoo Accounting Dashboard để đối soát các dòng sao kê đã import.

SePay Account Requirements

To use this module, users need an active SePay account and at least one bank account linked in SePay. API and Webhook access depends on the SePay package used by the customer.

Required items:

• A SePay account.
• At least one Vietnamese bank account linked in SePay.
• A SePay API Token so Odoo can call the API server-side.
• A public Odoo URL so SePay can send HTTP POST requests.
• HTTPS/SSL for production webhooks.
• A suitable SePay package for the expected monthly incoming transaction volume.

Pricing Note

SePay publicly lists a FREE package with 50 incoming transactions per month and Webhook/API support. If the monthly transaction limit is exceeded, SePay may charge overage fees or require an upgrade to a higher package.

Vietnamese Banks Supported through SePay

According to public SePay information, SePay has direct API connections 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.

Supported banks, API access, package limits, and pricing are managed by SePay and may change over time.

Built for Odoo Enterprise Accounting

This Enterprise edition connects SePay directly with Odoo Enterprise Accounting. It uses Odoo's native Online Bank Synchronization, Bank Journal Dashboard, Bank Statement Lines, and Bank Reconciliation tools instead of creating a separate accounting workflow.

Odoo Enterprise tools used by this connector:

• Online Bank Synchronization: SePay is connected as an online synchronization provider using Odoo Enterprise's native online bank models.
• Bank Journal Dashboard: Users can connect SePay from the Odoo bank journal dashboard and monitor fetched transactions from the standard accounting dashboard.
• Bank Statement Lines: Imported SePay transactions become native Odoo bank statement lines, not custom accounting records.
• Bank Reconciliation Widget: Accountants reconcile SePay transactions using the standard Odoo Enterprise reconciliation screen.
• Reconciliation Models: The connector can prepare an exact-reference matching model for safer automatic matching.

Enterprise note: This module is designed for Odoo Enterprise Accounting. It requires account_accountant and account_online_synchronization. It is different from the Community Financial Account Connector Engine.

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 after clicking Connect in the SePay wizard. 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.

Configure SePay in Odoo Enterprise

After connecting a bank account and creating a webhook in SePay, users complete the setup in Odoo Enterprise. The connector stores SePay credentials on the Odoo online bank synchronization link and maps SePay bank accounts to Odoo bank journals.

1. Open the SePay Connection Wizard

Steps:

1. Open the Accounting or Invoicing app.
2. Go to the Accounting Dashboard.
3. On a Vietnamese bank journal, click Connect SePay if the button is available.
4. You can also go to Accounting / Configuration / Banks / SePay Connections.
5. Create a new SePay connection or open an existing SePay online synchronization link.

Link SePay Accounts to Odoo Bank Journals

After the API token is validated, Odoo fetches the bank accounts linked to the SePay account. The user then maps each SePay online bank account to an Odoo bank journal using the native Odoo Enterprise account-to-journal linking flow.

Steps:

1. Click Connect in the SePay wizard.
2. Odoo fetches the bank accounts linked to the SePay API Token.
3. Select the SePay online account to connect.
4. Map the SePay online account to the correct Odoo bank journal.
5. Odoo Enterprise sets the journal bank statement source to online synchronization.
6. Use one Odoo bank journal for each SePay bank account.

Best practice: The Odoo bank journal currency should match the SePay account currency. This connector is focused on Vietnamese bank movements and imports SePay accounts in VND.

Copy the Odoo Webhook URL to SePay

If webhook is enabled in Odoo, Odoo generates a SePay Webhook URL on the online synchronization link. Copy this URL into SePay so SePay can notify Odoo when a bank movement arrives.

Production note: If the generated webhook URL still contains localhost or a test domain, configure Odoo's public domain before copying it to SePay. SePay must be able to call this URL from the internet.

Manual Reconciliation with Odoo Enterprise

SePay transactions are imported into Odoo as native bank statement lines. Accountants can reconcile them from the standard Odoo Enterprise bank reconciliation widget, using automatic suggestions, existing entries, or manual operations.

1. Open the Bank Reconciliation Screen

Steps:

1. Open the Accounting Dashboard.
2. Find the bank journal connected to SePay.
3. Click Reconcile Items on the bank journal card.
4. Odoo opens the native bank reconciliation widget with imported SePay statement lines.

Synchronization and Audit Logs

This Enterprise connector imports SePay transactions through the native Odoo online synchronization pipeline. SePay API polling and webhook records are stored in an audit log before creating bank statement lines.

Main behavior:

• Webhook events are received by Odoo and stored in the SePay transaction audit log.
• Scheduled synchronization fetches missed or delayed transactions from SePay API v2.
• Webhook and API records are deduplicated before creating statement lines.
• Imported transactions are converted into native Odoo Enterprise bank statement lines.
• Errors are stored on the SePay transaction log for accounting manager review.

Recommended operation order:

1. Connect SePay in Odoo Enterprise.
2. Fetch SePay bank accounts.
3. Link each SePay account to an Odoo bank journal.
4. Copy the Odoo Webhook URL to SePay.
5. Paste the SePay Secret Key back into Odoo.
6. Use the Odoo Accounting Dashboard to reconcile imported statement lines.