View source | Discuss this page | Page history | Printable version Integration/User Documentation



Authorize.Net is a payment gateway service provider allowing merchants to accept credit card and electronic check payments through their Web site and over an IP (Internet Protocol) connection. Authorize.Net claims a user base of over 375,000 merchants and $88 billion of annual transacting volume, which would make them the Internet's largest payment gateway service provider.

Openbravo fully supports the integration with through an external module called Integration and distributed under the Openbravo Commercial License. This document shows the way to install, configure and use this module.


The Openbravo's integration supports the following features:


The module can be directly installed from the Central Repository using the Openbravo's Modules Management window as usual. Take into account that these modules are distributed under a commercial license that requires acquiring an activation key before the installation.

Obautn installation.png

Payment Gateway Side Configuration

The payment gateway configuration is a complex task full of details that are intimately related to the customer's preferences. This chapter doesn't pretend to cover all the possible scenarios, but only the most important ones for a successful integration with Openbravo. To know more about the configuration you can take a look at the Merchant Interface Online Help Files or contact directly.

Buy Account & Extra Services

Obviously, the very first step you must complete is to sign up for a new account. The basic account allows your users to pay their invoices manually by entering the credit card number into a secured popup provided by (it's what we call SIM Integration).

However, to take advantage of the other features provided by the Openbravo's integration, you will need these extra services:

API Login ID and Transaction Key

Once your account is ready, you need to create the API Login ID and Transaction key, which are used by Openbravo to communicate and authenticate against the servers.

This step and the rest of the side configurations are done in your user's interface at Account > Settings:

Obautn authorize settings.png

Follow this manual to get yours.

Write down your API Login ID and Transaction Key, because you will need to enter these values when configuring the Openbravo's side.

Obautn authorize apilogin.png

MD5 Hash Code

The MD5 Hash Code is a string defined by you which gateway uses to encrypt the response of the transactions submitted by your users when paying invoices.

It's very important to define a complex MD5 Hash Code (mixing capital and lower letter, numbers, symbols, etc.) to make the encrypted response stronger.

The Hash Code is defined in your user's interface at Account > Settings > Security Settings. Follow this manual to define yours, and write it down because you will need to enter it when configuring the Openbravo's side.

Obautn authorize hash.png

Transaction Details API

The Transaction Details API is used by Openbravo to retrieve the real time transaction status from the servers. Please ensure this feature is enabled in your account.

Obautn authorize transaction API.png

Time Zone

The Time Zone is used when displaying transaction information in the Merchant Interface. It's recommend to set your Time Zone from the Time Zone drop-down list. Example: Pacific Time, Central Time, etc.

Obautn authorize timezone.png

Email Receipt

Inside this section you can configure to automatically send an email to your customer each time a transaction is captured. The email's header and footer can include the text you want (up to 255 characters).

Obautn authorize email.png

Payment Form

The Payment Form settings page allows you to customize the basic appearance of the payment gateway hosted payment form (manual payments) and specify which information fields you would like to include and/or require for transactions (both manual and automatic payments).

This step is critical for a successful integration with Openbravo, so please pay special attention to this instructions.

The most important part to configure inside this section is the Form Fields that will be displayed and/or required for transactions:

Obautn authorize paymentform config.png

Both manual and automatic payments share this configuration, so it's very important to configure it such a way where both payment methods can work together. In this case the fewer required fields, the better. The recommended configuration is the one shown in the above screenshot, where only Invoice No. and Description fields are set as View.

It's very important to set the Card Code field as not required, otherwise the automatic payments (CIM Integration) will not work. The reason is that the card code is not stored into the servers when registering a credit card for automatic payments. So, if the card code field is required, the CIM integration will fail because that value can't be retrieved. Note that disabling the card code shouldn't be a problem, because in general your member portal users are trusted users that have gotten credentials from the administrator. Moreover remember that any transaction done by your users is always audited by Openbravo.

Here you have an example of how the manual payment form looks like with the recommended configuration:

Obautn authorize paymentform run.png

Relay Response

The Relay Response is another critical configuration for a successful integration with Openbravo, specially for manual payments (SIM transactions).

Each time a user manually pays an invoice (entering the credit card or bank account number), Openbravo sends the payment to If successfully captures it, it sends an encrypted response back to Openbravo with all the information. After that Openbravo analyzes the response to verify it really comes from, registers a new Payment In with the paid amount and sets the Sales Invoice as paid.

The Relay Response is the URL where must send the response when receiving a SIM transaction. It's very important to properly configure it, otherwise Openbravo won't realize the invoice has been successfully captured by and it will remain as unpaid in the ERP.

This URL must follow the following format:

https://<your openbravo instance URL>/<your openbravo context>/


Obautn authorize relayreponse.png

Openbravo Side Configuration Dataset

To simplify the configuration process, the Integration Module provides a dataset with the very basic configuration. It's mandatory to apply this configuration at * Organization.

Please note that this dataset depends on the Member Portal Roles, so please ensure to select it too in case you haven't applied it before:

Obautn dataset.png

The dataset includes important configuration like:

Financial Configuration

The next step is to declare the financial account where the customer's payments will be received. This is done by checking the Subscription flag in the Financial Account window. Note that this must correspond to the bank account number you have already defined into the portal.

Apart from that, you must also include the two payment methods related to the dataset have created:

Obautn financialaccount.png

Note: Only one financial account checked as Subscription per legal entity is allowed. The same rule applies for Payment methods.

Client Configuration

The most important step is to configure the API Access Credentials and the fee percentage we want to apply for credit card transactions (if any). This is done at the Integration field group in the Client window:

Obautn client.png

Email Configuration

Openbravo is able to automatically send an email to the customer each time he/she subscribes or unsubscribes to the automatic payment. So it's important to properly define the Email Configuration at Client level. Please follow the user manual if you haven't configured before.

Apart from this kind of emails, payment gateway will automatically send an email to the customer for each payment executed against his account. This is configured directly into the portal Email Receipt section, so it's not necessary to configure anything more in Openbravo's side.

Organization Configuration Integration can be configured at Organization Level (Only for legal entities) and it overrides the Client configuration described above. At the Integration field group in the Organization window you will find the following fields:

Auth net org.png

Member Portal Configuration

One of the most important features of the Openbravo integration with is its compatibility with the Member Portal. Thus your users can independently manage their configuration without your intervention. For example, the portal users can register payment methods to be used to pay the invoices (by entering the credit card or bank account number), they can register/unregister to automatic payment or, in case they are not registered to automatic payment, they can manually pay the pending invoices. Everything is directly done into the Member Portal by using only two widgets: My Invoices and Payment Method distributed with the module:

Obautn portal.png

Configure Organization Access for Roles

The first thing you must do is to configure the allowed organizations your member portal users will have access to. This is done through the Role window, Org Access tab.

After applying the Member Portal Roles dataset, you will see that 2 new roles have been created: Member Portal Admin and Member Portal User. By default both roles share exactly the same configuration, and they both have access to the same widgets. Optionally you can add or remove other widgets too.

The only step pending is to assign the organization(s) the users associated to this role will have access to. You must include at least the organization that will be used for creating the invoices. Remember to do it for both payment methods:

Obautn roles.png

Configure Member Portal Workspace

The configuration is almost ready, we just need to configure the workspace that the member portal users will see when entering into the portal. This is done through the Administrate widgets for other clients or roles functionality.

Remember to configure the Member Portal User and Admin roles to define the right widgets for you. Example:

Obautn configure workspace.png

Modify Payment Method Widget Text

As you can see, the Payment Method widget includes a generic text that must be replaced with the information you want to show to your member portal users. This can be easily done through a Template, by modifying the Application Dictionary Messages that start with OBAUTN_SUBSCR_. If you don't know how to do it, please read the article How To Create a Configuration Script or contact to your Openbravo Partner.

Obautn messages.png

Obviously, you can also use this technique to customize other parts of the application, like for example the widget's titles.

Granting Access to Member Portal Users

The configuration is ready, it's time now to define the users who will have access to the member portal.

This can be manually done by the administrator creating an user (with username and password), associating to the business partner, the right member portal role, and communicating the username and password to the user.

However, in order to simplify that process, there is a new button at Business Partner window, Contact tab called Grant Portal Access that will execute all these steps, and it will send an email to the user with his/her username (which is the email address), and the password (which is randomly generated). Once the user logs into the Member Portal, he/she can change it.

Working with the Integration

The system is designed to work on an independent way with almost no intervention from the client administrator. Everything is done by the users, either paying manually their invoices, or subscribing to the automatic payment. In any case the client administrator workload is very low, and he/she just needs to sit down and see how the system manages everything on their own.

Manual Payment (SIM Integration)

By default the customers are not subscribed to the automatic payment. This means that, in order to pay their invoices, they will need to log in the Member Portal, select the invoice(s) they want to pay into the My Invoices widget and press the Pay Now button (or the Overdue: Pay Now in case there is an overdue). After that they will see an embedded popup where they can choose to pay it using a credit card or a bank account (called ACH Push):

Obautn online1.png

Once selected the right method, the system will show a secured frame where the user can safely enter the sensitive data. Please note that Openbravo never reads or stores sensitive data from the user, and this operation is done outside the Openbravo's control:

Obautn online2.png

If everything is OK, Openbravo will immediately show the invoice as paid, generating the Payment In record associated to the Online Payment Method. In case of errors, like for example wrong data introduced by the user or missing mandatory fields, they will be shown in that embedded popup. Depending on the kind of error, the user may fix it and try to pay the invoice again (for example wrong credit card number).

Here is a flow diagram with a summary of the steps in this process:

Obautn online flow.png

Automatic Subscription (CIM Integration)

Alternatively to the manual payment, the user has the opportunity to subscribe to automatic payments by using the Payment Method widget. The user enters the credit card or bank account information just one time using a secured embedded popup provided directly by This information is safely stored into the servers and Openbravo never reads, writes or stores it.

Obautn automatic.png

After the information is entered, the user must authorize Openbravo to charge the provided credit card or bank account for the new invoices and the pending amount to pay (if any).

Obautn automatic2.png

Later on the user can modify the payment method information, for example to change the credit card number or to use a new bank account, or alternatively he can also unsubscribe and go back to manual payments.

For unsubscribing, the user just needs to delete all the payment method information registered before.

Here is a flow diagram with a summary of the steps in this process:

Obautn automatic flow.png

In case the user registers more than one payment method (for example several credit cards or bank accounts), the system will use always one of the defined bank accounts (randomly), and if no bank accounts are defined, the system will use any credit card (randomly). So it's recommended to just define one payment method to avoid confusions.

Finally, when a user registers to automatic payment, the old Financial Account and Payment Method associated to the Business Partner are replaced by the Financial Account configured for and the right Payment Method (Online or Subscription).

Once subscribed, if the user wants to go back to online payment (removing all the sensitive payment method information in the Payment Method widget), Openbravo will automatically associate again the old Financial Account and Payment Method defined at Business Partner level.

Payment Execution

The Subscription Payment Method is associated to the CIM Integration Execution Process, which is in charge of sending the payment to and receiving the reply.

In the Payment Methods configuration from the module's dataset, this execution process is configured to be executed immediately. Remember that if you want to manually execute this process, you should set the Payment Method's Deferred flag to Yes.

Besides, you can configure the Execute Pending Payments Process Request to be executed on a regular basis, for example on a daily basis. This process checks and executes Payment In and Payment Out linked to a payment method having an "Automatic" Payment Execution Process, which are not set as "Deferred" and do not required any input to be executed, which is the case of the CIM Integration Execution Process. This is a way to ensure the automatic payments are always executed without the user's intervention.

On the other hand, when the user manually pays an invoice (SIM Integration), the execution process is always executed immediately, so you don't need to worry about it. Transaction Statuses

When an invoice is paid through the payment gateway (either using the online or subscription payment methods), Openbravo automatically generates a new Payment In that reflects the paid amount and keeps track of the unique transaction identifier for each line (Transaction ID column). If you want to get more details about this transaction status, you can directly search for this ID into the portal.

When a payment is successfully authorized and captured by, the Authorization Date, Captured and Capture Date columns are automatically populated. In this moment, the invoice(s) associated to the payment are automatically set as paid, however this doesn't necessary mean that the payment amount has been already settled.

Obautn transaction details.png

As you can see in the image above, there are two columns called Transaction Status and Transaction Status Updated that show the status this transaction had in that moment reported by

When a payment is sent to it is not settled instantly. Usually the settlement process takes some hours or even days in the case of ACH transactions (through bank accounts). During this time the transaction status may change; some examples are: Captured, which means the transaction has been captured by the portal, Pending Settlement, Settled Successfully when the amount is in the bank account, etc.

To get a transaction status update, you can either:

To make things easier for the client administrator, there is a background process called Update Status that can be scheduled to run on a regular basis to update the status of all the transactions that are in a transitory status (example: Authorized, Captured, Pending Settlement, Pending Review, etc.). As usual, this can be configured from the Process Request window.

Voiding Payments

We have said before that when an invoice is paid through, the invoice is shown as paid, although this doesn't mean the amount is already settled in our bank. The reason, as you can suppose, is the transaction status.

Imagine that the credit card used for paying the invoice has no funds. In this case, when tries to settle the amount, the credit card's bank owner will reject the transaction. However Openbravo hasn't detect it yet, so the invoice remains as paid.

The way to fix it depends on the way you prefer to manage your business. You can either control this kind of scenarios manually and take the actions you prefer, like manually voiding the payment, or you can let Openbravo to do it for you. The former just requires you to take a look at the Transaction Details Report, search for the declined transactions, go back to Openbravo and void the related payments. The latter is simpler because you can configure the Update Status process (both manual and automatic process share the same configuration) to automatically void the payments when the updated transaction status is any of the ones configured at the Void Payment Configuration window:

Onautn void.png

Voiding the payment means that the invoice will be shown as unpaid again, so the user can try to pay it again.

If you don't want the Update Status process to automatically void the payments, just deactivate the record in the window's header.


As you can see, the integration for Openbravo is a very powerful tool designed to simplify the Openbravo administrator's life. However the configuration implies a lot of steps that must be properly followed to get it working. With the configuration shown in this guide, the integration should work fine; but any other change, specially at the's side, may create problems with Openbravo, so do it at your own risk.

Apart from the configuration, the integration obviously requires a deep testing from your side to ensure it works as you want before deploying it into a production environment. Remember that your Openbravo partner can help you with the Openbravo's configuration side, and that any other problem related to the side must be directly reported to

Retrieved from ""

This page has been accessed 9,394 times. This page was last modified on 7 April 2014, at 21:27. Content is available under Creative Commons Attribution-ShareAlike 2.5 Spain License.