X-Cart:Authorize.Net

Authorize.Net is a large U.S.-based payment gateway that allows you to accept online credit card and electronic check payments. The claimed user base of more than 230,000 merchants makes it one of the largest internet payment service providers. X-Cart is currently integrated with two payment methods offered by Authorize.Net: Server Integration Method (SIM) and Advanced Integration Method (AIM). The major difference between the two methods is where you host the payment pages for you store.

A third Authorize.Net's payment option supported by X-Cart is Authorize.Net: AIM. eCheck, which is an implementation of Authorize.Net: AIM for electronic check payments.

Authorize.Net: SIM (Server Integration Method)

With Authorize.Net: SIM the payment pages are hosted on the side of Authorize.Net, which means that Authorize.Net provides all the necessary resources to process a transaction, including collection of payment information. Customers get redirected to the Authorize.Net secure website and enter their card details there. Authorize.Net: SIM is a right solution if you do not have adequate resources to collect and transfer sensitive card details. For example, SIM does not require you to obtain and install an SSL certificate on your server/hosting account.

Authorize.Net: AIM (Advanced Integration Method)

With Authorize.Net: AIM the payment pages are hosted together with the rest of the store. The data is transmitted to Authorize.Net in the background mode and customers never leave your website during the purchase. Since Authorize.Net: AIM involves collection and transmission of sensitive cardholder data, you must ensure the security of this data by setting up secure connection with Authorize.Net. Otherwise, Authorize.Net will reject the transaction.

Secure connection is implemented through an SSL certificate installed on your server/hosting account. For recommended SSL certificate providers please check the X-Cart marketplace at http://marketplace.x-cart.com/ . Another requirement of Authorize.Net: AIM is that your server must provide support for at least one of the following HTTPS modules: Net::SSLeay, CURL, libCURL, OpenSSL or HTTPS-cli.

Authorize.Net: AIM. eCheck

Authorize.Net: AIM. eCheck uses the same logic as Authorize.Net: AIM, but it is meant to process electronic check payments - not credit card payments. Like Authorize.Net: AIM, the eCheck implementation also requires an SSL certificate and one of the supported HTTPS modules.

Obtaining an Authorize.Net account

If you have not yet registered an account with Authorize.Net, you should do it before you start setting up Authorize.Net in X-Cart. To open an account, go to the Authorize.Net website at http://www.authorize.net/signupnow/ and follow the instructions on the screen. After you have registered an account, you can set up Authorize.Net: SIM, Authorize.Net: AIM and Authorize.Net: AIM. eCheck in the X-Cart Admin area.

Setting up Authorize.Net to work with X-Cart 4.x

X-Cart 4.0or higher

Authorize.Net: AIM

1. Log in to the X-Cart Admin area.

2. Go to the Payment methods section (Administration menu -> Payment methods) and scroll down to the Payment gatewaysform.

3. Select Authorize.Net: AIM from the drop-down list and click the Add button.

Clicking the Add button adds Authorize: AIM to the list of the available payment methods.

Note: If you set up a payment method providing online credit card payment processing and do not intend to process credit card payments manually, you should disable the default "Credit Card" payment method, that requires manual payment processing, by unselecting the check-box next to the payment method's name. Additionally, you can change the default "Credit Card" payment method's name to "Credit Card (offline)", and change the online payment method's name to "Credit Card". This will help you to avoid any confusion between these two payment methods.

The $store_cc variable in the config.php file must be set to false in case you disable the default 'Credit Card' payment method and do not intend to process credit card payments manually.

4. Click on the 'Configure' link. This opens the configuration page for Authorize.Net:AIM.

5. In the 'Settings' window that appears, complete the following fields:

• Account type: Select from Card not present or Card present.
• API Login ID: Enter the name of your merchant account with Authorize.Net.
• Transaction key: Enter your Authorize.Net transaction key.

To obtain a key:

• Log in to your Authorize.Net account at https://account.authorize.net/
• In the main menu, click Settings and Profile.
• In the Security section, click Obtain Transaction Key.
• Enter the answer to the Secret Question configured during the account setup.

• MD5 hash value: Enter the MD5 hash value, which is set up in your merchant account.
• Test/Live mode: Choose the mode in which the gateways must operate.
  The "test" mode means that you can submit test orders and perform test transaction. Money will not be withdrawn from credit cards. The "live" mode is the full functioning mode with real transactions and charges. It must be used when only you are ready to go live.
  
  When you choose to use the "live" mode, be sure to enable the "live" mode in your Authorize.Net account as well.
  Test mode notes (specific to the payment method):
  * Test Credit Card Number: 4222222222222
  * Test Results: Depending on the dollars value passed through the gateway the result will either return as transaction successful or failed.
  Example: to test the AVS response reason code number 27, submit the test transaction with the credit card number 4222222222222 and the amount $27.00.
• Order prefix: Enter a prefix that will be automatically added to IDs of orders placed in your store and paid through Authorize.Net: AIM.
• Action to be performed on order placement. Choose whether Authorize.Net must capture the money automatically (Auth and Capture) or only freeze the funds until you capture the authorized amount manually through the X-Cart Admin area (Auth only).

6. Click the Update button to apply the changes.

7. Adjust the configuration settings in the Authorize.Net back-office.

• Log in to your Authorize.Net account at https://account.authorize.net/ .
• Go to the Settings -> Response/Receipt URLs section.
• Click the Add URL button and then enter the URL from the Valid Referrer URL field of the Authorize.Net configuration page.
• Make sure the following parameters are set up in the section Settings -> Direct Response:

• Direct Response Delimited Response = Yes;
• Default Field Separator = , (comma).

After you have configured and activated the gateway, your customers will be able to choose Authorize.Net: AIM as a payment option.

Authorize.Net: SIM

To use Authorize.Net: SIM as one of the payment options in the store:

1. Log in to the X-Cart Admin area.

2. Go to the Payment methods section (Administration menu -> Payment methods) and scroll down to the Payment gatewaysform.

3. Select Authorize.Net: SIM from the drop-down list and click the Add button.

After you have clicked on Add, Authorize: SIM will be added to the list of the available payment methods.

Note: If you set up a payment method providing online credit card payment processing and do not intend to process credit card payments manually, you should disable the default "Credit Card" payment method, that requires manual payment processing, by unselecting the check-box next to the payment method's name. Additionally, you can change the default "Credit Card" payment method's name to "Credit Card (offline)", and change the online payment method's name to "Credit Card". This will help you to avoid any confusion between these two payment methods.

The $store_cc variable in the config.php file must be set to false in case you disable the default 'Credit Card' payment method and do not intend to process credit card payments manually.

4. Click on the Configure link. This opens the configuration page for Authorize.Net: SIM.

5. Adjust the configuration settings for Authorize.Net: SIM and click the Update button to apply the changes.

• Valid Referrer URL: The URL from which Authorize.Net: SIM will receive data from X-Cart.

Important: Authorize.Net uses the URL to check whether the payment request is sent by your store, not a fake website. Make sure the URL in the X-Cart Admin area coincides with the respective URL in the Authorize.Net back-office.

• Relay URL: The URL to which Authorize.Net must land customers back to X-Cart after a payment has been processed.
• API Login ID: Enter the name of your merchant account with Authorize.Net.
• Transaction key: Enter your Authorize.Net transaction key.

To obtain a key:

• Log in to your Authorize.Net account at https://account.authorize.net/
• In the main menu, click Settings and Profile.
• In the Security section, click Obtain Transaction Key.
• Enter the answer to the Secret Question configured at account setup.

• The difference between your server time and the Authorize.Net server time (in seconds): Enter the number of seconds between your server time and Authorize.Net server time.

Each time X-Cart performs a SIM transaction, Authorize.Net generates a new fingerprint to authenticate the transaction. Among other parameters, the fingerprint also includes a timestamp of when the fingerprint was generated. The timestamp must coincide with the time of the Authorize.Net server, which uses Greenwich Mean Time (GMT).

Sure, your server is likely use a local time zone that is different to GMT. To ensure successful authentication, you must iron out the difference in server time by adjusting the value of this field. The value must be setup in seconds. Although it is not required that the difference is covered to the last second, it must be no more than 15 minutes ahead, or 15 minutes behind the Authorize.Net server time (GMT). Otherwise, authentication will fail.

For example, if your server uses a local time zone GMT +2, the value must be 7200, which is equal to the number of seconds in 2 hours; if your server uses a local time zone GMT -6, the value must be -21600, which is equal to the number of seconds in 6 hours, and the minus sign indicates that the time must be subtracted from GMT. Also, be sure to account for daylight savings time.

• Currency: Choose the currency in which you wish to accept payments through Authorize.Net: SIM.
• Test/Live mode: Choose the mode in which the gateways must operate.

The "test" mode means that you can submit test orders and perform test transaction. Money will not be withdrawn from credit cards. The "live" mode is the full functioning mode with real transactions and charges. It must be used when only you are ready to go live.

Note: When you choose to use the "live" mode, be sure to enable the "live" mode in your Authorize.Net account as well.

• Order prefix: Enter a prefix that will be automatically added to IDs of orders placed in your store and paid through Authorize.Net: SIM.

Having a prefix ensures that orders will have unique IDs and will never coincide with orders placed in another online store of yours that also uses Authorize.Net as a payment option.

• Action to be performed on order placement: Choose whether Authorize.Net must capture money automatically (Auth and Capture) or only freeze the funds until you capture the authorized amount manually through the X-Cart Admin area (Auth only).

6. Return to the list of payment methods and activate Authorize.Net: SIM by selecting the check box next to the gateway's name.

7. Click the Update button.

8. Adjust the configuration setting in the Authorize.Net back-office.

• Log in to your Authorize.Net account at https://account.authorize.net/ .
• Go to the section Settings -> Response/Receipt URLs.
• Click the Add URL button and enter the URL from the Valid Referrer URL field of the Authorize.Net configuration page.
• Make sure the following parameters are set up in the section Settings -> Direct Response:

• Direct Response Delimited Response = Yes;
• Default Field Separator = , (comma).

After you have configured and activated the gateway, your customers will be able to choose Authorize.Net: SIM as a payment option.

Setting up Authorize.Net in X-Cart 3.4.x and 3.5.x

X-Cart 3.5

X-Cart 3.4

Go to 'CC/ACH processing' menu, select 'Authorize.net' as an active CC processor, click 'Continue' and complete the settings form. Enter merchant login and transaction key. Choose the currency and enter order prefix.

Then log in to your Authorize.net merchant account. Go to Settings -> 'Response/Receipt URLs', click the 'Add URL' button and enter the following URL: http://www.yoursite.com/xcart_directory/customer/home.php (POST method). Also check that the following parameters are set under Settings-> Direct Response:

• Direct Response Delimited Response: Yes
• Default Field Separator: ,(comma)

Troubleshooting

Authorize.Net error: "(14) The referrer, relay response or receipt link URL is invalid."

Make sure you have entered the correct URLs in your Authorize.Net merchant account back-end ('Settings -> Response/Receipt URLs' page), for example:

• Valid Referrer URL: https://www.yoursite.com/xcart/payment/cc_authorizenet_sim.php
• Relay URL: https://www.yoursite.com/xcart/payment/cc_authorizenet_sim.php

Please note, if you have PROTOCOL column set to HTTPS for 'Authorize.Net: SIM' payment method, the URLs must have "https" and vise versa.

Authorize.Net error: "MD5 transaction signature is incorrect! (Reason Code 0 / Sub 0)"

Usually this error is caused by incorrect values submitted for Authorize.Net in the X-Cart admin zone and/or in your merchant account back-office.

Check the settings in your X-Cart: "Payment method" page -> scroll down to Authorize.Net and click 'Configure'. Make sure that there are correct values for Login, Transaction key and MD5 hash. For example, it might be that MD5 hash value is wrong or empty.

Login (API Login ID) and Transaction key are recorded in your merchant account back-office on the "Account -> API Login ID and Transaction Key" page.

MD5 hash value is generated in your Authorize.Net account as well:

1. Log in on to the account,
2. Select Settings from the Main Menu
3. Click on MD5 Hash in the Security section,
4. Enter a new value (it is not recommended to use such characters like {, }, *, !),
5. Confirm the value entered,
6. Click Submit.

If Autorize.Net is successfully contacted but you get an error message.

It can be found on the error message page (in earlier versions, in the browser address string), so you will know what is wrong.

If Authorize.Net replies that certain field cannot be left empty

In this case you should do the following: login to your merchant account, go to 'Settings' -> 'Payment Form' -> Form fields and uncheck 'Required checkbox' next to this field. Another possible cause of orders declining is that AVS checking is too strict. Go to 'Settings' -> 'Address Verification System Settings' and uncheck all Reject flags.

If you do not get any response from Authorize.Net

This means that Authorize.Net hasn't been contacted.

First, check if payment/authorize_net.pl has executable permissions. If it doesn't, run the shell/ftp command - chmod 0755 authorize_net.pl. The second possible cause: Net::SSLeay Perl module is not installed. Refer to the corresponding FAQ item that explains Net::SSLeay Perl module installation.

Rarely happens: your Perl script may have been corrupted during its uploading to your server from Windows machine. If you edit Perl script in Windows editor (like NotePad), you should upload it in ASCII mode to convert Windows new line symbols to UNIX new line symbols.

Authorize.Net SIM error: Unable to send notification to Customer

When a customer completes their payment, Authorize.Net calls back to the Relay Response URL (for example, "https://www.yoursite.com/xcart/payment/cc_authorizenet_sim.php") in order to send the payment transaction details to your X-Cart store. When calling back to the URL, Authorize.Net may not receive any response from your server within 10 seconds. Therefore Authorize.net sends the error message:

An error occurred while trying to report this transaction to the merchant. An e-mail has been sent to the merchant
informing them of the error. The following is the result of the attempt to charge your credit card.

Such errors may be caused by accidental communication problems between your web-server and Authorize.Net server, probably when your web-server and/or Authorize.Net server are experiencing the maximum work-load or there is a DNS lookup issue. Here is what Authorize.net knowledge base says:

On occasion, timeouts will occur that are outside of the control of your script or our servers. Typical reasons for
these timeouts include Internet traffic, your server is overloaded or malfunctioning, or Internet routing issues.
Depending upon your server location and what route is used to send data, it is possible that you may occasionally
receive the message you are seeing.

As a possible solution, try to increase the time-to-live (TTL) setting for the response URL domain (i.e. up to 1 week). Please contact your hosting provider to implement the necessary changes.

See also:

• http://www.authorize.net/support/knowledgebase/?page_id=169764&url=/authorize.net/consumer/kbdetail.asp%3Fkbid%3D559
• http://community.developer.authorize.net/t5/Integration-and-Testing/SIM-Relay-Response-Timeout/td-p/7867/page/3