AZUL Payment Provider for Odoo 19
Connect Odoo eCommerce, customer invoices, and portal payments to the AZUL-hosted Payment Page for card transactions in the Dominican Republic.
Built for organizations that already have, or plan to obtain, an AZUL merchant account and the credentials required for their chosen environment.
A regional payment flow inside Odoo
AZUL Payment Provider adds an Odoo payment provider for businesses serving customers in the Dominican Republic. It brings the payment initiation and transaction lifecycle into the standard Odoo 19 payment framework while keeping the primary card-entry step on the hosted AZUL Payment Page. Your commercial relationship, account approval, processing conditions, and credentials remain between your organization and AZUL.
Customers can select AZUL during eCommerce checkout, open a secure invoice payment link, or pay from an Odoo portal flow. Odoo creates the payment transaction, prepares the AZUL fields, calculates the request signature, and redirects the browser. After the customer finishes on the hosted page, AZUL returns the browser to the callback configured by the module so that Odoo can process the result.
Supported customer journeys
- Odoo eCommerce card checkout
- Customer invoice payment links
- Authenticated or signed portal payment flows
- Approved and declined browser returns
- Customer cancellation returns protected by a transaction token
How the hosted Payment Page workflow works
1. Start in Odoo
A customer selects AZUL from an eligible checkout, invoice, or portal payment. Odoo creates a transaction and prepares the order reference, monetary values, locale, and callback addresses.
2. Pay on AZUL
The browser is redirected to the AZUL-hosted Payment Page. Card PAN and CVV entry takes place there; the redirect integration does not capture those values in an Odoo checkout form.
3. Process the result
AZUL returns the browser for approval or decline processing. Odoo validates the signed response before applying the corresponding transaction state. A separate protected route handles cancellation.
AuthHash and return validation
The module generates the AZUL request AuthHash with HMAC SHA-512 from the required ordered fields and the configured AZUL Auth Key. For approved and declined browser returns, it recalculates the expected HMAC SHA-512 AuthHash and uses a secure comparison. A missing or invalid AuthHash on a browser return is rejected rather than accepted as a payment result.
Amount checking is deliberately conditional on the actual response: when AZUL returns an Amount field, the module compares it with the Odoo transaction amount in minor units and rejects a mismatch. The listing does not assume that every AZUL return always includes an amount.
Approved, declined, and canceled outcomes
An AZUL response with the expected approval response code and ISO code is marked done in Odoo. Declined responses and AZUL error responses are recorded as transaction errors with the available response detail. These states help users review the result within Odoo's normal payment transaction workflow.
AZUL cancellation callbacks do not use the same response payload. The module therefore creates a random, transaction-specific token, includes it in that transaction's cancellation URL, and checks it with a secure comparison before marking the transaction canceled.
Optional DataVault and WebServices operations
The basic hosted Payment Page flow uses the redirect credentials. Additional capabilities are conditional. If DataVault is enabled for the AZUL merchant, an approved response may provide a token that Odoo can save as a payment token. The integration can use a saved DataVault token for a server-to-server sale. It also implements refund and void requests through AZUL WebServices.
Test and production environments
The Odoo provider state selects the AZUL environment. Test mode sends transactions to AZUL's sandbox Payment Page and WebServices endpoints. Enabled mode uses the production endpoints. Sandbox and production credentials are separate and must match the selected environment.
Complete approved, declined, and canceled scenarios in the sandbox with current test details supplied by AZUL before enabling production. A sandbox result does not replace production account activation or an end-to-end operational review of your deployment.
Deployment compatibility
This module is designed for self-hosted Odoo 19 Community, self-hosted Odoo 19 Enterprise, and Odoo.sh environments that allow custom third-party Python modules. Use the repository branch and package matching the installed Odoo major version.
It is not compatible with Odoo Online SaaS, because that service does not permit installation of arbitrary third-party Python modules. Deployment compatibility still requires testing with the exact edition, localization, website, company, currency, and merchant setup.
Installation and configuration overview
-
Place the
payment_azuldirectory in an Odoo addons path, restart Odoo, update the Apps list, and install AZUL Payment Provider. - Open the AZUL payment provider and enter the Merchant ID, Auth Key, merchant name, merchant type, and AZUL currency code supplied for the selected sandbox or production environment.
- Choose Test mode for sandbox validation. Publish and enable the provider only when its Odoo website, company, payment method, currency, and country settings make it eligible for the intended customer flow.
- Configure WebServices channel, Auth1, Auth2, and any required certificate only if the merchant will use enabled token charges, refunds, or voids.
Data transmitted to AZUL
Transparency matters for payment integrations. During the redirect workflow, Odoo sends the configured merchant identifiers and attributes, transaction and order references, the amount and calculated ITBIS, currency and locale values, approved and declined return URLs, the tokenized cancellation callback URL, optional custom reference fields, the DataVault preference, and the generated AuthHash. These fields allow AZUL to identify, present, and return the payment.
When optional WebServices operations are used, Odoo additionally sends the applicable operation type, merchant store and channel, amount and ITBIS, currency, order and reconciliation references, AZUL transaction identifiers, and, for token payments, the saved DataVault token. WebServices authentication is carried in the separate AZUL credentials configured for the provider. Administrators should review their AZUL agreement, Odoo access controls, retention practices, and customer disclosures before processing live data.
Requirements and known limitations
- An external AZUL merchant account, merchant approval, and credentials for each intended environment are required and are not included with the app.
- The public Odoo base URL must be correctly configured, use HTTPS, resolve to the right database, and remain reachable for browser redirects and callbacks. Reverse-proxy and multi-database routing are operational responsibilities of the deployment owner.
- The module validates signed browser-return data but does not perform an additional authoritative server-to-server status query after every browser return. Operations teams must account for interrupted or delayed browser navigation in their reconciliation procedures.
- DataVault, token sales, refunds, voids, mutual TLS, and production access remain subject to AZUL merchant enablement, credentials, and service rules.
| Availability |
Odoo Online
Odoo.sh
On Premise
|
| Odoo Apps Dependencies |
•
Invoicing (account)
• Discuss (mail) |
| Lines of code | 649 |
| Technical Name |
payment_azul |
| License | OPL-1 |
| Website | https://cesarmunoz.dev/ |
Odoo Proprietary License v1.0 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.
Please log in to comment on this module