Toolbox

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 Authorize.net through an external module called Authorize.net Integration and distributed under the Openbravo Commercial License. This document shows the way to install, configure and use this module.

Features

The Openbravo's Authorize.net integration supports the following features:

Credit Card Not Present transactions. It allows to pay any invoice using a credit card number directly introduced by the user, i.e. without physically reading the credit card through a dataphone.
eCheck.Net: It enables you to accept and process payments from bank accounts through the ACH network.
Server Integration Method (SIM): It allows any Member Portal User to directly pay pending invoices by entering either the credit card information or the bank account number directly into a secured hosted form provided by Authorize.net
Customer Information Manager (CIM): The Member Portal Users can register at once their favorite payment method (credit card or bank number) into a secured form provided by Authorize.net. The data is securely stored into the Authorize.net servers (note that Openbravo never stores or reads sensitive data from the user). Thus the user subscribes to automatic payments, which means that any invoice generated in the future (and the pending amount if any) will be automatically paid through the registered payment method. In any moment the user can unsubscribe (or subscribe again) to the automatic payments
Transaction Details: It allows to monitor the transaction status detail on real time: the authorization status, the settlement status (pending, accepted, rejected), etc.

Installation

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.

Payment Gateway Side Configuration

The Authorize.net 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 Authorize.net configuration you can take a look at the Authorize.net Merchant Interface Online Help Files or contact Authorize.net directly.

Buy Authorize.net Account & Extra Services

Obviously, the very first step you must complete is to sign up for a new Authorize.net account. The basic account allows your users to pay their invoices manually by entering the credit card number into a secured popup provided by Authorize.net (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:

eCheck.net only if you want to allow your users to pay using a bank account (ACH push).
Customer Information Manager (CIM): To allow your member portal users to subscribe to the Automatic Payment feature. The credit card or bank account number information (the latter only if eCheck.net is available) is safely stored into the Authorize.net servers, and it can be used on demand to pay new invoices.

API Login ID and Transaction Key

Once your Authorize.net 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 Authorize.net servers.

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

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.

MD5 Hash Code

The MD5 Hash Code is a string defined by you which Authorize.net 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 Authorize.net 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.

Transaction Details API

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

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.

Email Receipt

Inside this section you can configure Authorize.net 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).

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:

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 Authorize.net 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:

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 Authorize.net. If Authorize.net 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 Authorize.net, registers a new Payment In with the paid amount and sets the Sales Invoice as paid.

The Relay Response is the URL where Authorize.net 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 Authorize.net and it will remain as unpaid in the ERP.

This URL must follow the following format:

https://<your openbravo instance URL>/<your openbravo context>/org.openbravo.authorize.net.ad_forms/PayNowResponse.html

Example:

https://www.mycompanyopenbravoerp.com/openbravo/org.openbravo.authorize.net.ad_forms/PayNowResponse.html

Openbravo Side Configuration

Authorize.net Dataset

To simplify the configuration process, the Authorize.net 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:

The Authorize.net dataset includes important configuration like:

Payment Methods:
- Authorize.net Online Payment, used for online payments, i.e. when the user needs to enter the credit card or bank account number each time he/she wants to pay an invoice
- Authorize.net Subscription, used when the user subscribes to automatic payments

Authorize.net Fee G/L Item. In case we want to collect a fee for credit card transactions (we will see it later on), the fee amount will be associated to this G/L Item.

Access for the Member Portal Roles to the widgets distributed into the Authorize.net module

Basic configuration for automatically voiding payments based on the transaction status detail (defined at the Authorize.net Void Payment Configuration)

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 Authorize.net Subscription flag in the Financial Account window. Note that this must correspond to the bank account number you have already defined into the Authorize.net portal.

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

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

Client Configuration

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

Production Payment Gateway: This flag indicates whether we want to communicate to a production payment gateway or to a testing one. Authorize.net provides testing payment gateways where users and developers can test the integration using dummy credit cards or bank accounts without creating real life settlements. Configure this flag depending on the type of payment gateway you want to use. Please note that unchecking this flag in a real production environment can be very dangerous, because any payment sent to the gateway when this flag is unchecked will be considered as paid by Openbravo although it will never be settled in real life!

Login ID: which corresponds to the API Login ID defined when creating the Authorize.net account. You can find it inside the Security Settings of your Authorize.net account. This value is encrypted in the database.

Transaction Key: You must define a Transaction Key from the Security Settings of your Authorize.net account. The transaction key can be changed at any time, but if you do so, you must remember to update the value inside Openbravo too.

Currency: The currency your transactions will use. Currently the following currencies are allowed: USD, CAD, GBP

MD5 Hash: As you know the MD5 Hash Code is used only when the customer pays an invoice entering the credit card number or bank account directly into the hosted form provided by Authorize.net (SIM integration). This code allows to authenticate transaction responses from the payment gateway. You may establish a unique MD5 Hash value that the payment gateway will use when encrypting responses for transactions submitted for your account. It's highly recommended to define a complex MD5 Hash code to avoid crackers to manipulate the Authorize.net response. You can define it at the Security Settings of your Authorize.net account.

Credit Card Fee %: In case you want to apply a fee for credit card transactions, you must define here the percentage. When the system detects the customer has used a credit card, it will automatically calculate the extra amount based on this percentage. Obviously you can leave this field empty if you don't want to charge an extra fee.

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, Authorize.net payment gateway will automatically send an email to the customer for each payment executed against his account. This is configured directly into the Authorize.net portal Email Receipt section, so it's not necessary to configure anything more in Openbravo's side.

Organization Configuration

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

Has Authorize.net configuration: This flag indicates if this legal entity will have its own Authorize.net configuration. This field is only shown if the Organization Type is Legal Entity.

Production Payment Gateway: This flag indicates whether we want to communicate to a production payment gateway or to a testing one. Authorize.net provides testing payment gateways where users and developers can test the integration using dummy credit cards or bank accounts without creating real life settlements. Configure this flag depending on the type of payment gateway you want to use. Please note that unchecking this flag in a real production environment can be very dangerous, because any payment sent to the gateway when this flag is unchecked will be considered as paid by Openbravo although it will never be settled in real life!. Only shown if Has Authorize.net configuration is checked.

Login ID: which corresponds to the API Login ID defined when creating the Authorize.net account. You can find it inside the Security Settings of your Authorize.net account. This value is encrypted in the database. Only shown if Has Authorize.net configuration is checked.

Transaction Key: You must define a Transaction Key from the Security Settings of your Authorize.net account. The transaction key can be changed at any time, but if you do so, you must remember to update the value inside Openbravo too. Only shown if Has Authorize.net configuration is checked.

Currency: The currency your transactions will use. Currently the following currencies are allowed: USD, CAD, GBP

MD5 Hash: As you know the MD5 Hash Code is used only when the customer pays an invoice entering the credit card number or bank account directly into the hosted form provided by Authorize.net (SIM integration). This code allows to authenticate transaction responses from the payment gateway. You may establish a unique MD5 Hash value that the payment gateway will use when encrypting responses for transactions submitted for your account. It's highly recommended to define a complex MD5 Hash code to avoid crackers to manipulate the Authorize.net response. You can define it at the Security Settings of your Authorize.net account. Only shown if Has Authorize.net configuration is checked.

Credit Card Fee %: In case you want to apply a fee for credit card transactions, you must define here the percentage. When the system detects the customer has used a credit card, it will automatically calculate the extra amount based on this percentage. Obviously you can leave this field empty if you don't want to charge an extra fee. Only shown if Has Authorize.net configuration is checked.

Member Portal Configuration

One of the most important features of the Openbravo integration with Authorize.net is its compatibility with the Member Portal. Thus your users can independently manage their Authorize.net 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 Authorize.net and Payment Method distributed with the Authorize.net module:

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 Authorize.net 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:

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:

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.

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 Authorize.net 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 Authorize.net 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):

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:

If everything is OK, Openbravo will immediately show the invoice as paid, generating the Payment In record associated to the Authorize.net 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:

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 Authorize.net. This information is safely stored into the Authorize.net servers and Openbravo never reads, writes or stores it.

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

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:

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 Authorize.net and the right Authorize.net 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 Authorize.net Subscription Payment Method is associated to the Authorize.net CIM Integration Execution Process, which is in charge of sending the payment to Authorize.net and receiving the reply.

In the Authorize.net 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 Authorize.net CIM Integration Execution Process. This is a way to ensure the Authorize.net 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.

Authorize.net Transaction Statuses

When an invoice is paid through the Authorize.net 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 Authorize.net 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 Authorize.net portal.

When a payment is successfully authorized and captured by Authorize.net, 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.

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 Authorize.net.

When a payment is sent to Authorize.net 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 Authorize.net portal, Pending Settlement, Settled Successfully when the amount is in the bank account, etc.

To get a transaction status update, you can either:

Go to the Authorize.net portal and seach the transaction status by the Transaction ID stored in Openbravo.
Press the Update Authorize.net Status, which will automatically retrieve the transactions's current status associated to the payment from the Authorize.net servers.

To make things easier for the client administrator, there is a background process called Update Authorize.net 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 Authorize.net, 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 Authorize.net 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 Authorize.net 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 Authorize.net 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 Authorize.net Void Payment Configuration window:

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 Authorize.net Status process to automatically void the payments, just deactivate the record in the window's header.

Disclaimer

As you can see, the Authorize.net 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 Authorize.net'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 Authorize.net side must be directly reported to Authorize.net.

Retrieved from "http://wiki.openbravo.com/wiki/Authorize.net_Integration/User_Documentation"

This page has been accessed 9,244 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.