- APPS
- BIDV Connector 18.0
| Lines of Code | 1424 |
| Technical name | viin_bidv_connector |
| License | OPL-1 |
| Website | https://viindoo.com/apps/modules/18.0/viin_bidv_connector |
| Read description for | v 17.0 |
| Required Apps | Invoicing (account) Discuss (mail) |
| Included Dependencies | Bank Connector API Request Logger |
| Extensions | BIDV Automatic QR Payment |
BIDV tells your system which bill each transfer pays
For companies in Vietnam that collect money through a BIDV account
Connect Odoo with BIDV Open API, the base for automatic QR code payments on sales orders, invoices and the point of sale.
Odoo Community · Odoo Enterprise · OPL-1 · English, Vietnamese
What changes for your team
BIDV setup in one place
Merchant IDs, callback addresses and keys travel between the bank and your team by email.
→ The bank account holds the Merchant ID and Service ID and shows the two addresses BIDV calls, each with a copy button. The accountant sees no secret.
Know that BIDV reached you
A customer says they paid, and nobody can tell whether the bank ever notified the system.
→ Every bill lookup and payment notification from BIDV leaves a row in API Request Logs, accepted or refused, with the answer your system gave.
Debug calls to BIDV without exposing secrets
On a hosted database the administrator cannot read the server, so a refused call to the bank is a guess.
→ Connect Bank and every call a payment app makes to BIDV leave a row with what was sent and what BIDV answered. The access token, refresh token, application secret, passwords, the authorization, signature and client certificate headers are masked in any body format; grant type, client ID, scope, token type and lifetime stay readable.
Features
Connecting the account
- ✓ Merchant ID and Service ID required as soon as BIDV is chosen
- ✓ Sandbox or Production, credentials checked with Connect Bank
- ✓ Access token renewed by itself when missing or expired
Collecting payments
- ✓ Bill lookup and payment notification addresses served by the connector
- ✓ VietQR carries a BIDV payment alias that names the bill
- ✓ A missing QR setting is reported with a clear message
- ✓ Checksum check against your company keys before a payment app acts
Following the bank traffic
- ✓ Each BIDV callback logged with the answer sent
- ✓ Each call to BIDV logged with request and response
- ✓ Secrets masked in every row, whatever the body format
- ✓ Log reading granted with its own API Log Viewer right
Security built in
- ✓ Keys shown to system administrators only
- ✓ The private key appears on no screen
- ✓ Keys kept per company, out of other companies' reach
- ✓ Optional check of the signature on BIDV's answers
- ✓ A key already set is never overwritten
Ready on day one
Keys for every company
The secret code, certificate and symmetric key are generated at installation, and for each company created later.
Addresses to hand over
The Get Bill and Pay Bill addresses exist as soon as the module is installed; no other app is needed for them.
What you set first
The four values BIDV issues (Merchant ID, Service ID, App ID, App Secret), BIDV's NAPAS code on the bank, and a City or State on your company.
Extend it
BIDV Automatic QR Payment
Records each confirmed BIDV transfer on the invoice or sales order it pays.
Before you decide
Does it record payments by itself?
No. Installed alone, it answers BIDV that the customer or bill is unknown. BIDV Automatic QR Payment records transfers on invoices and sales orders; Point of sale - BIDV QR code automatic payment does it at the till.
Who can see the keys and the secrets?
System administrators, for the companies they work in. Other users see no key, the private key is on no screen, and log rows show secrets masked.
Who can read the API log?
Users given the API Log Viewer right read it; administrators read and delete rows. The rows stay in your own database.
We already use BIDV on the previous Odoo series. Do we start again?
No. The upgrade copies the keys stored on your BIDV bank accounts to the company and generates only what is missing. A newly generated key must be sent to BIDV.
What does it take to run?
A BIDV Open API registration and a public web address BIDV can reach. The certificate is valid for 365 days and has no renew button: contact support before it ends.
Try it, then ask us
The Documentation tab walks through setup, the API log and troubleshooting. The store's Live Preview opens the module on a demo database.
Pre-sales & partnership
viindoo.com/contactusTechnical support
viindoo.com/ticketTechnical requirements
- Python packages to install: jwcrypto
BIDV Connector
Note
Extends Bank Connector - see its documentation: viin_bank_connector.
Overview
BIDV Connector links a company bank account held at BIDV to your system. It does four things:
- It builds the VietQR code of the account with a BIDV payment alias, so that BIDV can tell which bill a customer is paying.
- It provides the two web addresses BIDV calls: one to look up a bill (Get Bill URL) and one to announce a payment (Pay Bill URL). No other app has to be installed for these addresses to exist.
- It keeps a journal of every call BIDV makes, in API Request Logs.
- It generates and protects the keys of your company that BIDV needs: a certificate, a symmetric key and a secret code.
What it does not do on its own: it records no payment. Installed alone, the connector answers a bill lookup with "customer unknown" (result code 011) and a payment notification with "bill not found" (result code 021). To have payments recorded you also need one of these apps:
- BIDV Automatic QR Payment for invoices and sales orders.
- Point of sale - BIDV QR code automatic payment for the till.
Who uses this module
| Role | What they do | Access right to assign |
|---|---|---|
| System Administrator | Connects the account to BIDV (App Secret, Connect Bank), gives BIDV the addresses, secret code, certificate and symmetric key, reads the keys. | Administration / Settings |
| Accounting Officer | Opens the company bank account, chooses BIDV as Bank Connector, enters the Merchant ID and the Service ID, reads the callback addresses. | Extra Rights / Contact Creation |
| Accounting or IT support staff | Checks that BIDV reaches the system and what the system answered. | API Log Viewer (see "Checking that BIDV reaches you") |
The roles in this table are the people who typically hold these tasks; your company may split them differently.
Before you start
Ask BIDV for the four values it issues to your company: the Merchant ID, the Service ID, the App ID and the App Secret. Then check two things, because without them no QR code can be built:
- The bank. Open Contacts ‣ Configuration ‣ Bank Accounts ‣ Banks, open BIDV and check that the Bank Identifier Code is the 6-digit NAPAS code of BIDV: 970418. A SWIFT code does not work.
- The account holder. The holder of the account (your company's contact) must have a City or a State filled in. Open Contacts ‣ Contacts, open your company and fill in the City or the State.
Setup (for the System Administrator)
Installation
- Open Apps and search for BIDV Connector.
- Click Install. The Bank Connector app and the Vietnam accounting localization are installed with it.
- Install BIDV Automatic QR Payment and/or Point of sale - BIDV QR code automatic payment if you want payments to be recorded.
When the module is installed, your company receives its secret code, certificate and symmetric key automatically. A company you create later receives them too.
Giving a user the right to work with BIDV
Open Settings ‣ Users & Companies ‣ Users, open the user and tick the access right from the table above:
- Administration / Settings for the administrator.
- Extra Rights / Contact Creation for the accounting officer.
- API Log Viewer for the person who reads API Request Logs. This right is listed under "Technical" and is shown only in developer mode.
Connecting the bank account
The accounting officer and the administrator share this task. The administrator is needed for the App Secret and the Connect Bank button.
- Open Contacts ‣ Configuration ‣ Bank Accounts ‣ Bank Accounts and open the company's account at BIDV (or create it, with BIDV as the bank).
- In the "Bank Connector" group, choose BIDV in Bank Connector.
- Choose the Environment: Sandbox for tests, Production for the real bank.
- Enter the App ID given by BIDV.
- Enter the App Secret (the administrator only - other users do not see this field).
- In the "BIDV" group, enter the BIDV Merchant ID and the BIDV Service ID. Both are required.
- Click Save.
- The administrator clicks Connect Bank.
The accountant sees the same form without the App Secret, the Certificate and the Symmetric Key:
The administrator sees the whole form:
What Connect Bank answers:
- On success, a notification "Connect to BIDV OPEN API successful" with the text "Let start using BIDV OPEN API."
- If the App ID or the App Secret is empty: "App ID and App Secret are required for BIDV connection".
- If BIDV refuses or does not answer: "Error connecting to BIDV:" followed by the reason BIDV gave, or "no response".
- If you are not an administrator, the system refuses with an access error before BIDV is called. Ask an administrator to click the button.
The system asks BIDV for a new access token by itself when it is missing or expired, so you click Connect Bank to check the credentials, not to renew them.
Giving BIDV your side
BIDV needs five items from you. They are all in the system:
| Item for BIDV | Where to find it | Who sees it |
|---|---|---|
| Get Bill URL | Bank account form, "BIDV" group | Accountant and administrator |
| Pay Bill URL | Bank account form, "BIDV" group | Accountant and administrator |
| Certificate | Bank account form, "BIDV" group | Administrator |
| Symmetric Key | Bank account form, "BIDV" group | Administrator |
| Secret Code | Invoicing ‣ Configuration ‣ Settings, block "BIDV Settings" | Administrator |
The two addresses end in /bidv/qrcode/getbill and /bidv/qrcode/paybill. They are served by this module itself. They start with the web address of your system, so check that they show the public address BIDV can reach and not an internal one such as localhost. If they do not, ask your implementer to correct the web address of the system.
Each field has a copy button on its right. Click it and paste the value into the form or the message you send to BIDV.
The certificate is public material: only its first line is shown here, and BIDV needs the whole text. Never send the Secret Code or the Symmetric Key by an open channel; use the secure channel agreed with BIDV.
In the "BIDV" group you also find BIDV Public Certificate. Paste there the certificate BIDV gives you. It is only used if you switch on the check of BIDV signatures (see "Optional: check the signature of BIDV answers").
The Secret Code
The Secret Code belongs to the company you are working in. Click Generate Secret only if the code has leaked or BIDV asks for a new one. The system first asks you to confirm: "Generating a new secret code makes BIDV reject all callbacks until the new secret code is shared with BIDV. Continue?". After you confirm, the new code replaces the old one at once and the page shows "New secret code has been generated. Please copy and share it with BIDV." From that moment on BIDV rejects every call until you send it the new code.
Checking that BIDV reaches you
Every call BIDV makes to the two addresses leaves a row in API Logs ‣ API Request Logs. This menu is shown to users with the API Log Viewer right (they can read) and to administrators (they can read and delete).
How to read a row:
- Name: BIDV getbill is a bill lookup, BIDV paybill is a payment notification.
- URL: the address BIDV called.
- Response Status: always 200. BIDV's own answer code is not here but inside the answer, see below.
- Error Message: filled only when the system failed while handling the call; it names the kind of failure.
- Record: the order, invoice or payment the call is about, when a payment app supplies it.
Open a row and click the "Response Details" tab to read the answer sent to BIDV.
What is kept in a row:
- For a call that passed the signature check, the content of the call (with the checksum hidden) and the answer.
- For every other call, only the size of the call and the answer code. Nothing else of the call is stored.
The connector alone never answers a call as "accepted", so with no payment app installed all rows show the size only. The full content appears once a payment app checks the call.
What the answer code means:
| Code | Meaning | What to do |
|---|---|---|
| 000 | Success. | Nothing. |
| 011 | Customer unknown (Mã khách hàng không đúng/không tồn tại). | BIDV asked about a payment alias the system cannot answer. If no payment app is installed this is expected: install one. Otherwise check that the Merchant ID on the bank account is exactly the one BIDV uses. |
| 021 | Bill not found (Mã hóa đơn không tồn tại). | A payment was announced but no document could be matched. Same checks as 011. |
| 023 | Transaction already settled. | BIDV announced a payment that was already recorded. Nothing to do. |
| 004 | Invalid checksum. | Given by the payment apps when the checksum of the call does not match. The Secret Code or the Symmetric Key BIDV uses is not the one in the system: send BIDV the current values. |
| 031 | Error in the system. | The call failed inside the system. Read the Error Message column and ask your implementer. |
Calls your system makes to BIDV
Connect Bank, and every call a payment app makes to BIDV, also leave a row in API Logs ‣ API Request Logs. The Name shows the method and the address called. Open the row: the "Request Details" tab shows what the system sent, the "Response Details" tab what BIDV answered.
Secrets never stay readable in a row: they are shown as ***MASKED***. For a BIDV row:
- Masked: the application secret sent to get a token, the access token and the refresh token BIDV returns, any password, the Authorization header, and the X-JWS-Signature and X-Client-Certificate headers. This holds whatever the shape of the content (form, JSON or plain text).
- Readable: the grant type, the client ID (your App ID), the scope, the token type and the lifetime of the token, the other headers, the address called, the status, the duration and the messages BIDV returns.
The whole masking rule, which is the same for every connector, is described in API Request Logger.
Keys and who sees them
- The secret code, certificate, private key and symmetric key are generated automatically per company: when the module is installed, when a new company is created and when the module is upgraded. A value that already exists is never replaced.
- Only system administrators see the Certificate, the Symmetric Key and the Secret Code, and only for the companies they are allowed to work in. Other users do not see these fields.
- The private key is shown on no screen.
- The certificate is valid for 365 days from the day it was generated. In developer mode, the field Certificate Info on the bank account shows its subject, serial number and valid-from and valid-until dates.
- This version has no button to renew the certificate or the symmetric key. When the certificate approaches its end date, or if you must replace the symmetric key, contact your implementer or Viindoo support.
Optional: check the signature of BIDV answers
By default the system does not verify the signature of BIDV's answers to the calls it makes. To require it, an administrator turns developer mode on, opens Settings ‣ Technical ‣ Parameters ‣ System Parameters and creates a parameter with the key viin_bank_connector.verify_jws and the value True. This parameter does not exist after installation. Once it is set:
- The answer of BIDV must carry a signature; if the signature is missing or malformed, the system raises "The BIDV response is not signed, its signature cannot be verified."
- The signature is checked with the BIDV Public Certificate of the bank account. If the check fails, the system raises "JWS Signature verification failed:" followed by the reason.
This applies to the calls the payment apps make to BIDV. It does not change how BIDV's calls to you are checked. Delete the parameter or set it to False to switch the check off.
Upgrading from Odoo 17
On 17.0 the keys were kept on the BIDV bank accounts. When the module is upgraded to 18.0, for each company the upgrade does the following:
- If the company has no certificate and no private key, it copies the pair from the oldest BIDV account of the company's own contact that has both.
- If the company has no symmetric key, it copies it from the oldest BIDV account that has one.
- It generates whatever is still missing: certificate and private key, symmetric key, and a secret code if the company has none.
A key the company already has is never overwritten. If the upgrade generates a new secret code or key, send it to BIDV, otherwise BIDV rejects the calls.
Troubleshooting
The QR code cannot be built
When the QR code cannot be built, the reason is one of these messages:
| Message | Cause | Fix |
|---|---|---|
| Missing Merchant City or State. | The account holder has neither a City nor a State. | Fill in the City or the State of your company's contact. |
| Missing Bank Identifier Code. | The bank of the account has no Bank Identifier Code. | Open Contacts ‣ Configuration ‣ Bank Accounts ‣ Banks, open BIDV and enter 970418. |
| The Bank Identifier Code must be the 6-digit NAPAS BIN, BIDV is 970418, not the SWIFT code. | The code on the bank is not six digits. | Replace it by 970418. |
| Missing BIDV Merchant ID or Service ID. | One of the two is empty on the bank account. | Enter both in the "BIDV" group. |
| The payment alias must start with the BIDV Merchant ID. | The payment reference used by the document does not begin with the Merchant ID of the account. | Check that the Merchant ID is typed exactly as BIDV issued it, and that the payment app uses the same account. |
| Missing Merchant Account Information. | The account information of the QR code could not be built. | Check the bank and the Merchant ID of the account, then ask your implementer. |
The connection to BIDV fails
| Message | Cause | Fix |
|---|---|---|
| App ID and App Secret are required for BIDV connection | One of them is empty. | Enter both (the App Secret is entered by an administrator), save, click Connect Bank. |
| Error connecting to BIDV: ... | BIDV refused the credentials, or could not be reached. The text after the colon is the reason BIDV gave, or "no response". | Check the App ID and App Secret, check that the Environment matches the credentials (Sandbox or Production), then try again. |
| Error calling BIDV API: ... | A call made by a payment app was refused or did not get an answer. | Click Connect Bank to check the credentials, then read the reason after the colon. |
| BIDV rejects every call after you generated a new secret code | BIDV still holds the old secret code. | Send BIDV the current Secret Code. |
This software and associated files (the "Software") may only be used (executed, modified, executed after modifications) if you have purchased a valid license from the authors, typically via Odoo Apps, or if you have received a written agreement from the authors of the Software (see the COPYRIGHT file).
You may develop Odoo modules that use the Software as a library (typically by depending on it, importing it and using its resources), but without copying any source code or material from the Software. You may distribute those modules under the license of your choice, provided that this license is compatible with the terms of the Odoo Proprietary License (For example: LGPL, MIT, or proprietary licenses similar to this one).
It is forbidden to publish, distribute, sublicense, or sell copies of the Software or modified copies of the Software.
The above copyright notice and this permission notice must be included in all copies or substantial portions of the Software.
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.