ZaloPay Payment Provider
by Viindoo
| Lines of Code | 1299 |
| Technical name | payment_zalopay |
| License | OPL-1 |
| Website | https://viindoo.com/apps/modules/19.0/payment_zalopay |
| Read description for | v 13.0 v 14.0 v 15.0 v 16.0 v 17.0 v 18.0 |
| Required Apps | Invoicing (account) Discuss (mail) |
| Included Dependencies | Viindoo Base Accounting Foundation Payment Gateway Currency Conversion |
Take ZaloPay payments in VND and leave no order pending
For Vietnamese online shops and sales teams collecting VND payments on orders and invoices
ZaloPay online payments for Vietnamese customers
Is this you?
Customers who prefer ZaloPay cannot pay you the way they want.
You send payment links through chat and email, then check the ZaloPay site to see who paid.
Orders sit pending because a confirmation never arrived.
Refunds happen on the ZaloPay site and get typed back into your records.
You need the shop name on the payment page so customers recognise the order.
What changes
Customers cannot pay with ZaloPay
→ Customers pay by QR code, ZaloPay wallet, ATM card, bank account or international card, according to the options you switch on
Checking the ZaloPay site
→ A paid order is confirmed as soon as ZaloPay sends its signed notification
Orders left pending
→ When the customer comes back, Odoo asks ZaloPay for the order's state straight away
Refunds outside Odoo
→ Refund in full from Odoo, or in part for ZaloPay wallet payments
Anonymous payment page
→ The order description shows your own merchant name
How it works
System Administrator connects ZaloPay
Enter the App ID and keys, choose the payment options (ZaloPay wallet, ATM cards and bank accounts, international cards) and the merchant name shown on the order.
Accounts Receivable Clerk offers ZaloPay
ZaloPay appears next to the other payment methods on sales orders and invoices, and at checkout on your website, for Vietnam customers paying in VND.
Customer pays on ZaloPay
The customer has 15 minutes to pay the order on the ZaloPay page.
Odoo confirms
The payment is recorded when ZaloPay sends its signed notification, never from data the customer's browser passes back.
Odoo asks ZaloPay on return
When the customer comes back, Odoo asks ZaloPay for the order's state, and cancels an unpaid order only when ZaloPay reports it expired.
Refund if needed
Refund from Odoo; the outcome ZaloPay reports right after the request is shown on the refund.
Key Features
ZaloPay Provider Credentials
Connect your ZaloPay merchant application so Odoo can create and verify ZaloPay payments.
ZaloPay Payment Options
Choose which ZaloPay methods customers may use: ZaloPay wallet, ATM cards and bank accounts, international cards.
ZaloPay Order Description
Show customers your own merchant name on the ZaloPay payment page, so they recognise the order.
ZaloPay Availability Rules
Offer ZaloPay only to Vietnam customers paying in VND, the only currency ZaloPay accepts.
Automatic Payment Confirmation
Confirm a paid order as soon as ZaloPay sends its signed notification, with no manual step.
Payment and Refund Status Sync
Pick up payments and refunds that ZaloPay never reports back, so no pending order is left behind.
Who it is for
Owner or finance director
You want orders paid on the spot with the wallet or card your customers already use. Customers choose from the ZaloPay options you enable.
Accounts receivable lead or clerk
You send links and chase exceptions. No pending order is left behind, and refunds start from Odoo.
System administrator
You want confirmation you can trust. Payments are confirmed by ZaloPay's signed notification or a status query to ZaloPay.
Best for: Vietnamese online shops and sales teams that take VND payments from customers who use ZaloPay and want payments and refunds confirmed and recorded in Odoo.
Connect your ZaloPay merchant application
Choose payment options and the merchant name
Send a ZaloPay payment link from an invoice or sales order
Customers pay with ZaloPay at checkout
Refund from the payment record
Refund in full, or in part for wallet payments
Frequently Asked Questions
What if ZaloPay's notification never arrives?
When the customer comes back to the shop, Odoo asks ZaloPay for the order's state, so the payment is still recorded. Otherwise, check that your website is reachable at the callback address.
Which payment options can customers use?
The ones you switch on: ZaloPay wallet, ATM cards and bank accounts, international cards.
Can I refund part of a payment?
Yes for payments made with the ZaloPay wallet. Other payments are refunded in full; if ZaloPay refuses a partial refund, Odoo tells you to refund in full.
Can customers fake a payment through the return page?
No. A payment is never confirmed from data passing through the customer's browser.
Which currency does it support?
VND only, for customers in Vietnam. For documents in another currency, the administrator can opt in by setting the provider's Default Converted Currency to VND, which needs the currency-difference module this app depends on.
Will customers recognise my business on the ZaloPay page?
Yes. The order description shows the merchant name you set, or your company name if you leave it empty.
Need help with ZaloPay Payment Provider?
Technical Support
apps.support@viindoo.comTechnical Requirement
- Odoo version: 19.0
- Editions: Odoo Community, Odoo Enterprise
- Required modules: payment, to_currency_conversion_diff
- License: OPL-1
ZaloPay Payment Provider
Overview
Customers in Vietnam expect to pay online with the tools they already use every day. This module adds ZaloPay as a payment provider in Odoo, so your customers can pay a sales order, an invoice or a payment link on the ZaloPay payment page with the ZaloPay wallet, an ATM card or bank account, or an international card. Odoo records each confirmed payment automatically, and you can refund a ZaloPay payment without leaving Odoo.
How a ZaloPay payment moves through your company
- The System Administrator connects Odoo to the ZaloPay merchant account and chooses which ZaloPay payment options customers may use (see Setup (for the System Administrator)).
- The Accounts Receivable Clerk sends the customer a payment link from a sales order or an invoice, or the customer pays from the customer portal or the website.
- The customer pays on the ZaloPay page. ZaloPay confirms the payment to Odoo, and Odoo records it against the order or invoice.
- If the customer has to be repaid, the Accounts Receivable Clerk refunds the payment from Odoo.
Who uses this module
| Role | What they do | Access right to assign |
|---|---|---|
| System Administrator | Installs the module, enters the ZaloPay App ID and keys, chooses the payment options and the merchant name shown to customers, and makes ZaloPay available. | Administration / Settings |
| Accounts Receivable Clerk | Offers ZaloPay on sales orders and invoices through payment links, follows the payment transactions and refunds ZaloPay payments. | Invoicing / Billing (or any access right that lets the person work with customer payments) |
Note
ZaloPay accepts payments in Vietnamese Dong (VND) only, and ZaloPay is offered to customers whose country is Vietnam. See Frequently asked questions for payment documents in another currency.
Setup (for the System Administrator)
Installation
- Open Apps.
- Remove the default filter and search for ZaloPay Payment Provider.
- Click Install.
The module installs the Payment features it relies on, together with the Currency Conversion Difference app, which it uses to record payments of documents that are not in Vietnamese Dong.
Get your ZaloPay credentials
Sign in to the ZaloPay merchant portal and open your merchant application. Note down three values:
- the App ID of your application,
- Key 1, which Odoo uses to sign the requests it sends to ZaloPay,
- Key 2, which Odoo uses to check that a notification really comes from ZaloPay.
ZaloPay gives you one set of credentials for its test environment (sandbox) and another for the real, production environment. Keep the two apart.
Tell ZaloPay where to send payment notifications
ZaloPay confirms a successful payment by sending a notification to your Odoo website. Odoo includes the address of the notification with every order it creates. If the merchant portal also asks for a callback address for your application, enter:
https://<your Odoo web address>/payment/zalopay/callback
Replace <your Odoo web address> with the address customers use to reach your Odoo website. It must be reachable from the internet, because ZaloPay calls it from outside your network.
Configure the ZaloPay payment provider
Open Invoicing ‣ Configuration ‣ Online Payments ‣ Payment Providers (or Sales ‣ Configuration ‣ Online Payments ‣ Payment Providers) and open ZaloPay. Each company has its own ZaloPay provider: make sure the company selected in the top bar is the one that receives the money.
On the Credentials tab, fill in ZaloPay App ID, ZaloPay Key 1 and ZaloPay Key 2. The two keys are hidden while you type and are shown only to administrators.
Choose the State:
- Test Mode sends payments to the ZaloPay sandbox. Use it with your sandbox credentials while you check the setup. No real money moves.
- Enabled sends payments to ZaloPay production. Use it with your production credentials when you are ready to receive real payments.
- Disabled hides ZaloPay from customers.
The App ID and both keys are required as soon as the state is not Disabled.
Note
The ZaloPay keys can be changed only by an administrator. Other users who open the provider cannot read or edit them. Do not share the keys by email or chat.
Choose how customers may pay
Open the Configuration tab. In ZaloPay Payment Options, tick the ways customers may pay on the ZaloPay page:
- Allow payments with ZaloPay Wallet (ticked by default),
- Allow payments with ATM Cards and Bank Accounts,
- Allow payments with International Cards.
Tick at least one option. Odoo refuses to save the provider when none is ticked and shows the message "Enable at least one way of paying with the ZaloPay payment provider".
Choose the merchant name shown on the ZaloPay order
In ZaloPay Order Description, type the name customers should recognise in ZaloPay Merchant Code, for example your shop name. When the field is empty, Odoo uses the company name. The order shown on ZaloPay reads "<merchant name> - Payment for <order reference>". ZaloPay Description Preview shows the text with a sample reference, so you can check it before saving.
Check availability and publish
On the same tab, Currencies is set to VND and Countries to Vietnam: ZaloPay is offered only to customers in Vietnam who pay in Vietnamese Dong. Leave both as they are. When you are ready, switch State to Enabled, then use the Unpublished / Published button at the top of the form to show ZaloPay to website visitors.
Give each person the right access
Open Settings ‣ Users & Companies ‣ Users, open the user and set the Access Rights:
- the System Administrator needs Administration / Settings,
- the Accounts Receivable Clerk needs the Invoicing access right Billing to refund payments.
Accounts Receivable Clerk: collect and refund payments
Send a payment link
Use a payment link when you sell outside the website and want the customer to pay online.
- Open the sales order (Sales ‣ Orders ‣ Orders) or the customer invoice (Invoicing ‣ Customers ‣ Invoices).
- Click the Actions menu (the gear icon) and choose Generate a Payment Link.
- Check the Amount, then click Generate and Copy Payment Link.
- Paste the link into an email or a chat message to the customer.
The customer must be a customer whose country is Vietnam, and the document must be in Vietnamese Dong, otherwise ZaloPay is not offered on the payment page.
What the customer sees at checkout
The customer opens the link, or pays from the portal or the website checkout, and chooses Zalopay in the Payment method list. After the customer clicks Pay, Odoo creates the order at ZaloPay and sends the customer to the ZaloPay page, where the customer pays with the ZaloPay wallet, the ATM card or bank account, or the international card you allowed.
The customer has 15 minutes to pay the ZaloPay order. After that, ZaloPay no longer accepts the payment, and the customer has to start a new payment from the document.
Follow the payment
Open Invoicing ‣ Configuration ‣ Online Payments ‣ Payment Transactions to see every payment attempt with its status. This menu is only visible in developer mode: activate developer mode first (add ?debug=1 to the address of your Odoo page, or use the developer mode link in Settings):
- Draft or Pending: the customer has not finished paying, or ZaloPay has not reported the result yet.
- Confirmed: ZaloPay confirmed the payment. The order or invoice is updated and the payment is recorded in the Bank journal (the Payment Journal of the provider).
- Canceled: the order expired without being paid.
- Error: ZaloPay could not charge the payment. The message on the transaction gives the reason.
How payments are confirmed
You never confirm a ZaloPay payment by hand. Odoo confirms it in two ways:
- Notification from ZaloPay. When a customer pays, ZaloPay sends a signed notification to your Odoo website. Odoo checks the signature with ZaloPay Key 2 and only then confirms the payment. A notification without a valid signature is ignored.
- Return of the customer. When the customer comes back from the ZaloPay page, Odoo asks ZaloPay for the state of the order straight away and follows its answer.
An order is cancelled only when ZaloPay itself reports that it expired or was not found and its 15 minutes are over. While the order may still be paid, it is left as it is. ZaloPay notifies successful payments only: an order the customer never paid stays draft.
Refund a ZaloPay payment
- Open the payment: Invoicing ‣ Customers ‣ Payments, then the ZaloPay payment.
- Click Refund.
- In the Refund window, check Maximum Refund Allowed and enter the Refund Amount.
- Click Refund.
Keep these rules in mind:
- Partial refunds work only for payments made with the ZaloPay wallet. A payment made with an ATM card, a bank account or an international card must be refunded in full. If you enter a smaller amount for such a payment, ZaloPay refuses it and Odoo shows the message "ZaloPay refunds only ZaloPay wallet payments in part: refund this payment in full". Refund the full amount instead.
- The refund takes the outcome ZaloPay reports right after the request. Odoo sends the request and asks ZaloPay for the outcome straight away: the refund becomes confirmed, or shows ZaloPay's reason when it is refused. If ZaloPay has not settled it yet, the refund stays pending with the message "The refund is being processed by ZaloPay". ZaloPay does not notify Odoo about refunds, so check its outcome in the ZaloPay merchant portal. Do not click Refund again while a refund is pending.
- A payment can be refunded only after ZaloPay has reported its transaction number, which happens when the payment is confirmed.
Troubleshooting
| Problem | What to do |
|---|---|
| ZaloPay is not shown on the payment page. | Check that the provider State is Enabled (or Test Mode), that the customer's country is Vietnam, and that the document is in Vietnamese Dong. For the website, also check that the provider is Published. The company of the document must be the company of the provider. |
| Odoo will not save the provider and asks for the App ID or the keys. | Fill in ZaloPay App ID, ZaloPay Key 1 and ZaloPay Key 2, or set the state back to Disabled. |
| Odoo will not save the provider and says to enable at least one way of paying. | On the Configuration tab, tick at least one option in ZaloPay Payment Options. |
| The customer sees an error instead of the ZaloPay page. | The message comes from ZaloPay, for example "ZaloPay could not create the payment order". Check the App ID and Key 1, and that the credentials match the state (sandbox credentials in Test Mode, production credentials in Enabled). |
| The customer paid but the order is still waiting. | Check the ZaloPay Key 2 and that your Odoo website is reachable from the internet at the callback address given in the setup chapter, so that ZaloPay's notification can arrive. |
| A notification is ignored. | The notification was not signed with your ZaloPay Key 2. Check that Key 2 is the one of the same environment (sandbox or production) as the state of the provider. |
| The refund is refused for a card or bank payment. | Refund the whole payment: partial refunds are possible only for ZaloPay wallet payments. |
| The refund stays pending. | ZaloPay had not settled the refund when Odoo asked, and ZaloPay does not notify Odoo about refunds. Check the refund in the ZaloPay merchant portal. |
| The Refund button is missing. | The payment is not a confirmed ZaloPay payment, it is already fully refunded, or your user lacks the Invoicing Billing access right. |
Frequently asked questions
- Can I test without real money?
- Yes. Set the State to Test Mode and use the sandbox credentials of your ZaloPay merchant application. Switch to Enabled with the production credentials to go live.
- How long does the customer have to pay?
- 15 minutes from the moment the customer clicks Pay.
- Which currency does ZaloPay accept?
- Vietnamese Dong only. The ZaloPay provider is offered to customers in Vietnam.
- Can I charge a document that is not in Vietnamese Dong?
- Yes, if you choose to. On the Configuration tab, set Default Converted Currency to Vietnamese Dong. The customer is then charged in Vietnamese Dong at the exchange rate of the day, and the payment is recorded in Vietnamese Dong. The Currency Conversion Difference setup of your company must be complete, otherwise Odoo asks you to finish it when you save the provider.
- Who can read the ZaloPay keys?
- Only administrators.
- Can several companies use ZaloPay?
- Yes. Each company has its own ZaloPay provider with its own App ID, keys and options.
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.