Integrating First Data e4 SIM with osCommerce

by | Sep 18, 2014 | osCommerce | 9 comments

Integrating First Data’s payment system with osCommerce is very simple once you understand that First Data’s instructions are both incomplete and inaccurate.  In this post,  I’ll take you through the entire process of this integration, step by step.  First, however,  you need to understand that SIM stands for Server Integration Method and it takes the customer from your webserver to First Data’s webserver to enter their payment information.   Some people don’t like the fact that the customer leaves their website.  You can keep the customer on your website using First Data’s AIM system,  but I strongly recommend against it.  If, in the unlikely event that your website gets hacked and customer credit card information is lost,  the merchant is responsible and will end up paying huge fines and penalties.  It’s one of those low chance but high risk events – like nuclear war.  Don’t chance it.

My purpose with this post is to document what ended up working.  I didn’t experiment further after I got everything working.  I didn’t try to unravel the way everything involved works – only as necessary as I was led into various rabbit holes.  Hopefully this post will help you avoid those rabbit holes.

 

Configuring First Data

Since First Data will be presenting pages to your customers, you need to configure them properly.  Go to https://globalgatewaye4.firstdata.com/login and login.  The pages that First Data offers up are called “Payment Pages”, cleverly enough.  So click “Payment Pages” in the upper right menu.  Then create a new payment page by clicking on the link at the left to “Create a New Payment Page.”  This section of the control panel has 10 sections for you to move through.  Here are the entries you need:

Section 1: General

Payment page title:  a title that appears in First Data’s control panel so you can recognize which page is which.  I called mine “Online Store” and I have another for “Make a Payment”.  The latter is configured to deal with customers that use a special page on my website to enter a payment of some amount or other supplied by the customer.  It’s not connected to osCommerce at all.  Beside collecting random payments,  such a page could be used to collect donations, but I digress.

“Return to your site” URL:  at various points First Data provides a link on their pages that leads back to your website.  the URL should be something like http://yourwebsite.com/catalog

Maximum Number of Payment Attempts:  This defaults to 3.  Three seems fine to me.

Notification email:  My client wants several people to receive the emails that First Data sends out.  These include copies of payment confirmation emails that are also sent to the Customer and notifications of and error diagnosis for failed redirect-submissions.   I created a special email address on my webserver that is forwarded to all the people that need to get these emails.  You might call it store@yourwebsite.com and enter it here.  I ran into a problem with a long email address – First Data was not sending the necessary emails to the merchant.  I suspect they have an undisclosed limit on the number of characters in an email address.  A shorter address worked fine.  So, if everything works – First data takes your money, you get a receipt etc – but the merchant doesn’t get a notification from “First Data Customer Support”, try a shorter email address here.

Level 3 Processing: Leave it blank.

Before moving on to the next section click Save Changes or First Data is likely to log you out and you’ll have to start over.

Section 2:  Payment Types

I didn’t give this section much thought.  First Data seemed to have it appropriately populated.  It could be more complex in some cases, but in my case First Data gave me no choice for currency ($)  or processing mode (live).  They provided only one terminal.  The remaining options defaulted to unchecked and I left them that way.

Section 3: Pay Now/Donate Now

You can leave this page as it is.  If you were creating a payment or donation page on your server, you would use this page to set it up.

Section 4:  Receipt Page

This is the critical page and one that First Data explains poorly.

Return Link Method (for receipt page):  This provides a number of options that relate to the way information is transferred from First Data back to your server.  Choose:  “Link to the receipt page including result parameters using HTTP POST method (POST).”  I saw some instructions for osCMax (a varient of osCommerce) that said to use the “Link to the receipt page (LINK)” option – I think that’s just wrong, but I didn’t go back and check it out after I got everything working.

Receipt Link Text:  Something like “Return”

Receipt link URL:  It seemed like this link should be the link back to your store except that is already covered in Section 1 discussed above.  Instead,  I used https://yourwebsite.com/catalog/checkout_process.php and that seemed to work fine.  After First Data is done taking the customer’s money, this bounces the customer back to our website and displays osCommerce’s “Success” page.

Reference Number Title: I left blank.

Customer Reference Title: I left blank.

Authorize.Net Protocol – Relay Response Settings:  There are two of these items that are critical, the rest can remain unchecked. Be sure that Allow Relay Response is checked and that the associated link is  https://yourwebsite.com/catalog/checkout_process.php  Note that this must be https and in your case it may need to be www.yourwebsite.com. It depends on how your system is set up so look at your osCommerce configuration file to see what URL ties to SSL. Also be sure to check Allow HTTP Redirect to Merchant Website. Leave the remainder of this page blank.

Before moving on to the next section click Save Changes or First Data is likely to log you out and you’ll have to start over.

 

Section 5: Receipt Emails

Email Enabled: Check this so that your customers, and you, get an email receipt after First Data takes their money.

Email Addresses: This email address is used as the “Reply-To:” address for payment confirmation emails that are sent to customers.  I just used store@yourwebsite.com as in section 1 above.

Receipt Email Header:  You can put whatever you want here. I put: “This is a receipt for your recent purchase from My Company. Inc.”

Receipt Email Footer:  You can put whatever you want here.  I put: “Thank you for your order.”

Section 6: Recurring Payments

This didn’t apply in my situation so I skipped it.

Section 7: Customize Form

In this section, you drag little boxes from the top section to the bottom section to layout the form that First Data will use to capture your cusotmer’s data.  Here is what mine looks like:

 

Form Height:  I left this blank

Form Width: I used 960 as that matches the width of the rest of my website.

Before moving on to the next section click Save Changes or First Data is likely to log you out and you’ll have to start over.

Section 8: Appearance

You can mess around with this section to try to get the First Data page to look decent.  You are quite limited however.  For example the blue lines are provided in CSS that’s embeded in the web page.  If you create an external style sheet to pretty up the page, it can’t change this because the stylesheet is called in the page header and the embedded style overrides it.  I had some trouble getting the form-based formatting to work so I used a stylesheet.

Anyway, get your logo in there.

I created a stylesheet at https://yourwebsite.com/catalog/styleFirstData.css  This is what I put in it:

/* The following are locked by their inclusion in First Data’s html although more CSS can be added below:

body {

color: #444444;

background-color: #ffffff; }

div#header {

border-bottom: 20px solid #5090ef;

color: #ffffff;

font-family:”Arial Black”, “Arial Bold”, Gadget, sans-serif;font-size:18px

}

html {

width: 960px; min-width: 960px; max-width: 960px } body, #document {

width: 960px; min-width: 960px; max-width: 960px; overflow: auto

}

*/

body, #document {

margin-left: 50px;

}

#content {

}

div.return {

}

#secure {

}

#footer{

}div.powered {

}

The first four styles are commented out because they can’t be changed.  The other div ID’s and classes can be modified if you wish.  All I did was force the page away from the right side of the window because that looked bad.

CSS URL: put the URL of your stylesheet here like https://yourwebsite.com/catalog/styleFirstData.css

Before moving on to the next section click Save Changes or First Data is likely to log you out and you’ll have to start over.

Section 9: Security

In this section we will get some parameters we need to configure our payment module.

Encryption Type: Choose MD5

Transaction Key: If there is no string of letters/numbers here, click “Generate New Transaction Key” to create it.  Copy and paste this into a text document as you will need it later.  Don’t generate it again or you will need to change your osCommerce payment module to match the new string.

Response Key:  If there is no string of letters/numbers here, click “Generate New Response Key” to create it.  Copy and paste this into a text document as you will need it later.  Don’t generate it again or you will need to change your osCommerce payment module to match the new string.

Captcha: Use it if you want, I left it blank in this case, but used it on my independent payment page, where it is required.

Section 10: Hash Calculator

You can skip this section.

Click Save Changes.  Finally,  open your page for editing one last time and copy the page identifier from the top left.  It might look something like this:  USP-ABCDE-JKlMnoPQrs Paste this identifier into a text file as we will need it later.

The Payment Module

I just did this integration on 2.3.3.4 version of osCommerce.  I used the very latest authorize.net module that came with version 2.3.4.  It comes in two parts like everything else in osCommerce.  The module itself and the language file that goes with it.  You can find them in the latest osCommerce distribution here:

/catalog/includes/modules/payment/authorizenet_cc_sim.php  (the payment module)

/catalog/includes/languages/modules/payment/authorizenet_cc_sim.php  (the language file)

You need make only one change that involves two lines in the module:

Find:

if ( MODULE_PAYMENT_AUTHORIZENET_CC_SIM_TRANSACTION_SERVER == ‘Live’ ) {

$this->form_action_url = ‘https://secure.authorize.net/gateway/transact.dll’;

} else {

$this->form_action_url = ‘https://test.authorize.net/gateway/transact.dll’;

}

Replace with:

if ( MODULE_PAYMENT_AUTHORIZENET_CC_SIM_TRANSACTION_SERVER == ‘Live’ ) {

$this->form_action_url = ‘https://checkout.globalgatewaye4.firstdata.com/payment’;

} else {

$this->form_action_url = ‘https://checkout.globalgatewaye4.firstdata.com/payment’;

}

The URL’s above are the only things that change.  When done editing, save the file and move it to its proper place on your server (/catalog/includes/modules/payment/).

You may also edit the language file if you wish.  I just changed two lines so that the title I see on the admin side of osCommerce is meaningful to me and so that the title the customers see is meaningful to them.  Here’s what my two lines look like after editing:

define(‘MODULE_PAYMENT_AUTHORIZENET_CC_SIM_TEXT_TITLE’, ‘Authorize.net Server Integration Method (SIM) for First Data e4’);
define(‘MODULE_PAYMENT_AUTHORIZENET_CC_SIM_TEXT_PUBLIC_TITLE’, ‘Secure Credit Card Payment’);

Don’t edit anything except the descriptive strings.  When done, save your changes and move the file to its appropriate place on the server (/catalog/includes/languages/modules/payment/).

The payment module is now ready to be installed.  To do that log in to the admin side of your osCommerce installation and

  • go to: Modules > Payment.
  • click +Install Module
  • Find your authorize.net module and install it.

 

Configuring the Payment Module

Back on the Modules > Payment Screen, Click on the module’s line and choose Edit.  The graphic is what my configuration looks like.  You will need to use the three parameters discussed above that you should have saved to a text file.

Enable Authorize.net SIM: Click True so the module will be active when you are done

API Login ID: This is the page identifier that you got from First Data and saved in your text file.  Paste it here.

API Transaction Key:This is the Transaction Key from the Security section of the payment page setup at First Data.  Copy it from your text file and paste it here.

MD5 Hash: The MD5 Hash is the Response Key from the Security section of the payment page setup at First Data.  Copy it from your text file and paste it here.

Transaction Method:Normally your Transaction Method will be “Capture” so you can get your customer’s money.

Set Order Status: is a selection from a list of order statuses.  If you don’t like any of them you can create your own at Localization > Orders Status in your osCommerce admin side.

Review Order Status: I used the same as my Set Order Status

Transaction Order Status:  Now this is critical.  I had some trouble getting osCommerce to receive the info that comes back from First Data.  A lot of other people have the same problem with authorize.net modules.  The status you choose here MUST be the SAME as the status  you set for “Set Order Status”.  So, when someone places an order, the order status is automatically set to “Credit Card-Preparing Order”, in my case, AND when an order is in this same status, First Data will send the data back to osCommerce and it will be recorded with your Customers > Orders.

Payment Zone: My client only wants to accept payments from the lower 48 states, so I created this zone.  Why would he want that?  Well, he wants to manually calculate shipping for places outside the lower 48 states and doesn’t want people paying first and finding out later that there are huge shipping costs involved.  This way they never see the First Data payment option, but only a special payment module that tells the customer that the merchant will contact them with the total cost of their order.

Transaction Server: Set to Live

Transaction Mode: Set to Live

Debug Email Address: put your email address here in case any error messages come through.

Set order of display:  This positions the payment options in the list that the customer selects from.  I usually set them 10, 20, 30, 40 etc.  In this case I used 40 to put it at the bottom of the list.  I’ll eventually move it to the top of the list by setting this to 10.  I might have a check/money order payment module that would be set to 20.

It looks like a lengthy process, but it’s not too bad if it works correctly the first time!