View source | Discuss this page | Page history | Printable version   

Authorize.net Integration/User Documentation

Contents

Introduction

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:

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.

Obautn installation.png


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:

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:

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

Obautn authorize hash.png

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.

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

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 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:

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

Obautn authorize relayreponse.png


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:

Obautn dataset.png


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

Obautn financialaccount.png

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:

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, 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:

Auth net org.png

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:

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 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:

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

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 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:

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 Authorize.net. This information is safely stored into the Authorize.net 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 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.

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 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:

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:

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