///Integrating With Authorize.net Using SIM

Integrating With Authorize.net Using SIM

Integrating With Authorize.net Using SIM

We’ve received numerous requests for help with modifying Master Form and other programs for integrating with authorize.net’s SIM integration method.

Authorize.net is asking clients using the ADC Relay Response method to switch to the SIM method. And they have a deadline.

This article does not replace the authorize.net documentation or technical manuals. Rather, it addresses one aspect of the SIM integration — the generation and inclusion of the fingerprint information authorize.net uses to verify transactions.

The article is rather technical. If you don’t plan to use authorize.net as your credit card payment gateway, you may wish to skip the article.

First, let me mention that Master Shopper Lite has been upgraded to work with SIM. If you already purchased Master Shopper Lite, you can generate the upgraded version at no charge. The generator is at http://willmaster.com/master/shopperlite/generator/makemsl.shtml

This article addresses:


i. How SIM works.

ii. The order verification form.

iii. Customizing the SIM.cgi script

iv. Using SSI to insert the fingerprint.

v. Using JavaScript to insert the fingerprint.

vi. Using a Perl program to display the form with

fingerprint automatically inserted.

vii. Modifying scripts to create the fingerprint.

viii. Detailed instructions for Master Form.

ix. Testing.

x. Changing Transaction Keys.

Authorize.net provides documentation for using ASP, PHP, and Perl to generate fingerprints. Only the Perl method is addressed here.

The article mentions scripts and examples that can be obtained via a download. The download URL is http://willmaster.com/a/18/pl.pl?art186

The downloaded ZIP file name is SIM.zip

Whenever SIM.zip is mentioned in the this article, I’m referring to the above downloaded file.

How SIM Works

Simply stated, a unique fingerprint is generated immediately prior to submitting transaction information to the authorize.net payment gateway. When the fingerprint and transaction information is received by the gateway, the fingerprint is used during authentication. An invalid fingerprint invalidates the transaction.

To create a fingerprint, an MD5 encryption (referred to as an “MD5 hash”) is generated using


~~ Your merchant Login ID,

~~ Your Transaction Key (obtained via your merchant’s

control panel at authorize.net),

~~ A Time Stamp (automatically obtained from your

server),

~~ A Sequence Number (the scripts in SIM.zip provide

a pseudo-random number, 0 to 999),

~~ The amount of the transaction, and

~~ The currency code of the transaction (optional).

The fingerprint is composed of the generated MD5 hash along with the Sequence Number and the Time Stamp.

The Order Verification Form

The web page form used to transmit transaction information to the authorize.net payment gateway is referred to here as an order verification form. This is the web page your customer sees on your web site immediately prior to credit card or alternate payment authorization.

It is the form that transmits transaction information to the gateway.

If you’ve been using authorize.net’s ADC Relay Response integration method, you already have an Order Verification Form. If you do not, authorize.net’s integration documentation has instructions for creating this form, probably under headings containing words related to “form construction.”

For SIM integration, the fingerprint must be transmitted to authorize.net along with the rest of the transaction information. The fingerprint is inserted into the Order Verification Form as hidden fields.

The transaction amount used when generating the fingerprint must be the same as the x_Amount form field value that will be transmitted to the gateway.

If a currency code was used when generating the fingerprint, then an x_Currency_Code form field with the same value must also be transmitted to the gateway.

SIM.zip contains scripts and example files for inserting the fingerprint into your order verification form.

Customizing the SIM.cgi Script

The SIM.cgi script is included in the SIM.zip file. The script can be used to insert the fingerprint into your order verification form with SSI or with JavaScript. (Instructions for SSI and JavaScript are in following sections.)

Before SSI or JavaScript can be used to insert the fingerprint into your form, the script must be customized and installed.

SIM.cgi has six places that can be customized, each clearly marked.


1. Your Login ID must be specified.

2. Your Transaction Key must be specified. (Obtain a

Transaction Key from authorize.net according to

their instructions).

3. Whether or not to generate an x_Currency_Code hidden

field whenever the order verification form specifies

a currency code.

~~ If you do provide that hidden field on your order

verification form, specify No, and the subroutine

will refrain from generating the hidden field so

you won’t end up with a duplicate.

~~ If you don’t provide that hidden field, specify

Yes, and the subroutine will generate the hidden

field as needed.

4. Whether or not you’re calling SIM.cgi as an external

JavaScript file. Specify Yes or No.

5. If you know the total transaction amount beforehand,

having only one product with one price for example,

then specify that amount.

6. If you know the currency code beforehand, specify

that code.

To install SIM.cgi, upload the script as a text file into your cgi-bin and give it 755 permissions.

Using SSI To Insert the Fingerprint


Note: Using a “get” URL in the context presented in this

section might be less secure than the methods described

in the “Modifying Scripts To Create the Fingerprint”

and “Detailed Instructions For Master Form” sections,

below. I don’t know this for a fact, but it seems to me

that providing a URL to obtain the fingerprint for a

specific order amount could be a security consideration.

If you know the total amount of the transaction at the time the order verification form is to be displayed to your customer, you might use SSI to insert the fingerprint. SSI can be used in either of two situations:


1. When you have only one product at one price, script

SIM.cgi (included with the SIM.zip file) can be

customized to always use that transaction amount

when generating the fingerprint. An SSI tag calls

SIM.cgi.

2. When you’re able to calculate the total amount of

the transaction and send the customer’s browser to

the order verification form as a “get” URL with a

value representing the total amount, then the SSI

that calls SIM.cgi can extract the value from the

URL and use that transaction amount when generating

the fingerprint. Example “get” URL with a value:

http://domain.com/orderverification.shtml?24.95


In the above URL, 24.95 would be used as the amount

when generating the fingerprint.

JavaScript might be used to calculate the amount

and store it in a variable named “total”, for

example. Then the following line could give the

browser a “get” URL with a value:

window.location=’http://domain.com/orderverification.shtml’ +

‘?’ +

total;


If you want to specify a currency code, append an

ampersand and the currency code to the “get” URL.

Example:

http://domain.com/orderverification.shtml?24.95&USD


Methods other than JavaScript can be used to

calculate the total amount. So long as the browser

can be sent to the order verification form using a

“get” URL with the total amount as the value, an

SSI tag can call SIM.cgi to insert the fingerprint.

An example order verification form using SSI to insert the fingerprint is included in SIM.zip as file SIMexample_SSI.shtml

Using JavaScript To Insert the Fingerprint


Note: Using JavaScript code in the context presented in this

section might be less secure than the methods described

in the “Modifying Scripts To Create the Fingerprint”

and “Detailed Instructions For Master Form” sections,

below. I don’t know this for a fact, but it seems to me

that providing a URL to obtain the fingerprint for a

specific order amount could be a security consideration.

If you know the total amount of the transaction at the time the order verification form is to be displayed to your customer, you might use JavaScript to insert the fingerprint.

For example, if the order total amount is $24.95 you might put the following your order verification form’s source code where hidden fields are appropriate:


<script language=”JavaScript” src=”/cgi-bin/SIM.cgi?24.95″>

</script>

Notice that the url to SIM.cgi is followed by a question mark and then the total amount of the order.

If you want to specify a currency type along with the order amount, append an ampersand and the currency type to the URL. Example:


<script language=”JavaScript” src=”/cgi-bin/SIM.cgi?24.95&USD”>

</script>

When using SIM.cgi to insert the fingerprint hidden fields with JavaScript, answer Yes to the question in the customization section of the script where it asks whether or not you’re calling the script as an external JavaScript file.

An example order verification form using JavaScript to insert the fingerprint is included in SIM.zip as file SIMexample_JS.shtml

Using a Perl Program To Display the Form With Fingerprint Automatically Inserted

SIM.zip has a file named subroutine.cgi, which contains a subroutine named GenerateSIMhiddenFields. (The subroutine takes up the bottom half of the file.)

subroutine.cgi is intended to be used for modifying other scripts (see “Modifying Scripts To Create the Fingerprint” and “Detailed Instructions For Master Form” below), but can also be used as a program by itself.

To use it as a program by itself, first create an order verification form template page. The template page would have a [[SIMFIELDS]] placeholder where the SIM hidden fields are to be inserted and it might have one or more [[amount]] placeholders to be replaced with the total order amount. See file SIMexampleOrderVerification.html (part of SIM.zip) for an example.

Next, modify subroutine.cgi.


1. Decide whether your going to use the http://… URL

method to retrieve the template page or read the

page directly from your server. Remove the code that

you will not be using (the sections are marked).

2. Subroutine GenerateSIMhiddenFields has three places

requiring custom information:

i. Your Login ID.

ii. Your Transaction Key (obtained from

authorize.net according to their instructions).

iii. Whether or not to generate a certain hidden

field whenever a currency code is specified.

~~ If you do provide that hidden field on your

order verification form, specify No, and

the subroutine will not generate the hidden

field so you won’t end up with a duplicate.

~~ If you don’t provide that hidden field,

specify Yes, and the subroutine will

generate the hidden field as needed.

If you use the downloaded file

SIMexampleOrderVerification.html as your

order verification form, specify Yes so

subroutine.cgi will generate the hidden

field as needed.

Upload your order verification form template page and script subroutine.cgi into your cgi-bin as plain text files. Give subroutine.cgi 755 permissions.

Last, call subroutine.cgi with a form on the page prior to presenting the order verification form. This might be a shopping cart page or a product page.

The form that calls subroutine.cgi may have one or two fields. If one, the field must be named “amount”. If two, the second field must be named “currency”. Here is an example form:


<form method=”POST” action=”/cgi-bin/subroutine.cgi”>

<input type=”hidden” name=”amount” value=”24.95″>

<input type=”hidden” name=”currency” value=”USD”>

<input type=”submit” value=”Click to verify your order”>

</form>

When the above button is clicked, subroutine.cgi will


1. Retrieve the order verification form template page.

2. Insert the SIM hidden fields into the template page

in place of the [[SIMFIELDS]] placeholder.

3. Replace any [[amount]] placeholders with the value

of the name=”amount” field submitted to the script.

4. Display the completed order verification form in

the customer’s browser.

Modifying Scripts To Create the Fingerprint

Scripts can be modified to create a SIM fingerprint. How the fingerprint would then be used depends on the script. An example of a script modified to create and use the SIM fingerprint is in the “Detailed Instructions For Master Form” section, below.

To create a SIM fingerprint, two things need to be done with the script:


1. The subroutine GenerateSIMhiddenFields (found in

subroutine.cgi, in SIM.zip) needs to be inserted

into your script.

(See the “Using a Perl Program To Display the Form

With Fingerprint Automatically Inserted” section,

above, for information on how to customize

subroutine GenerateSIMhiddenFields)

The subroutine should not be inserted within any

other program blocks, such as subroutines,

conditionals, or loops. One place it might be done

is immediately below the first line of the script.

Another place might be at the bottom of the script,

so long as the script doesn’t have this line

__END__

anywhere within it. If it does have that line, the

subroutine may be inserted immediately above it.

Not knowing the script you’re modifying, I can’t

provide exact instructions of where to insert

subroutine GenerateSIMhiddenFields, but one of

the suggested locations should work.

2. The subroutine GenerateSIMhiddenFields needs to be

called and it’s returned value stored in a variable.

Your script can then use that variable to do what

it needs to do in order to get the fingerprint

information into your order verification page.

If the variable is named $hiddenSIMfields, then

this line might be used to call store the

fingerprint information into $hiddenSIMfields

my $hiddenSIMfields=GenerateSIMhiddenFields($amount,$currency);

$amount would be the total amount of the order and

the optional $currency would be the currency type.

Again, not knowing the script you’re modifying, I can’t provided instructions regarding the appropriate variable name to hold the fingerprint information, nor how your script will use the variable.

Using subroutine.cgi as a program by itself, as outlined in the “Using a Perl Program To Display the Form With Fingerprint Automatically Inserted” section, above, and reading the “Detailed Instructions For Master Form” section, below, might provide enough experience and understanding to make modifying your script somewhat easier.

Detailed Instructions For Master Form

Integrating SIM using Master Form requires two MasterForm.cgi script modification steps, one order verification form modification, and three files will need to be uploaded to your server:

Script Modification Step 1 —

At about line 38 or line 63 of MasterForm.cgi (depending on which version of Master Form you’re working with), you’ll find this line:


&GetDateTime;

Immediately above that line, insert these two lines (can be all one line, if you prefer):


$In{SIMFIELDS} =

GenerateSIMhiddenFields($In{ordertotal},$In{currency});

You’ll end up with:


$In{SIMFIELDS} =

GenerateSIMhiddenFields($In{ordertotal},$In{currency});

&GetDateTime;

The “ordertotal” part of the line is the form field name that sent the order total amount to Master Form. If that field in your form has a different name, change ordertotal to the field name your form uses.

The “currency” part of the line is the form field name that sent the currency code to Master Form. Note that this is optional —


~~ If your form does send that information to Master

Form and that field in your form has a different

name, change currency to the field name on your

form.

~~ If your form does not send that information to

Master Form, remove the “,$In{currency}” part of

that line, which will make it look like this:

$In{SIMFIELDS} =

GenerateSIMhiddenFields($In{ordertotal});

&GetDateTime;

Script Modification Step 2 —

SIM.zip has a file named subroutine.cgi, which contains a subroutine named GenerateSIMhiddenFields.

Copy subroutine GenerateSIMhiddenFields and paste it all the way at the bottom of the Master Form script. It could actually go anywhere below the first line of the script, so long as it isn’t inserted into conditionals, loops, or other subroutines. But putting it at the bottom of the file is probably the best place because you don’t have to worry about interferring with other sections of the script.

The subroutine GenerateSIMhiddenFields has three places requiring custom information. See the “Using a Perl Program To Display the Form With Fingerprint Automatically Inserted” section, above, for customization information.

The Order Verification Form Modification Step

In the source code of your order verification form (which is the last page of a multi-page form), where hidden form fields are appropriate, insert the following placeholder in either of the two example formats:


[[SIMFIELDS]]

<!–SIMFIELDS–>

(Master Form version 2.# recognizes placeholders between double square brackets and within HTML comment tags.)

SIM.zip contains an example order verification form for use with Master Form, SIMexampleOrderVerificationMF.html

Uploading the Three Files To Your Server

File 1: MasterForm.cgi

Upload the modified MasterForm.cgi as a text file to your server. (Make a backup copy of the un-modified script before overwriting the copy on your server.) After uploading, verify that the script contains 755 permissions.

File 2: SimHMAC.pm

Upload SimHMAC.pm as a text file into the same directory where your modified MasterForm.cgi is installed. Give the file SimHMAC.pm 755 permissions.

File 3: The order verification form.

Upload the order verification form where Master Form can find it (the location in the name=”goto” hidden field value in the previous form page).

Testing

To test your form, you might first use Display.cgi until you’ve verified that the form hidden fields are submitting like they are supposed to. Display.cgi simply displays the submitted fields and their values in your browser, where you can see for yourself what the form submits.

To use Display.cgi:


1. Upload Display.cgi into your cgi-bin and give it

755 permissions.

2. Change your form’s action=”…” to Display.cgi’s

URL.

Now you’re ready to test.

Once you’ve verified that the form submits information as it should, change the form’s action=”…” back to https://secure.authorize.net/gateway/transact.dll

You aren’t required to use Display.cgi for testing, of course. But it’s available if you think it might make things easier.

Display.cgi also provides the current date and time according to your server’s clock. This date and time must be correct, within a few minutes, in order to use the SIM method.

To obtain the server’s current date and time directly, type the URL of Display.cgi into your browser’s address bar.

Changing Transaction Keys

If in the future you suspect your Transaction Key has been compromised, you’ll need to generate another Transaction Key and update your script with the new Transaction Key.

There is a method you can use to avoid having to modify your script when you change your Transaction Key. That method is to keep the Transaction Key in a separate plain text file. When your script runs, it retrieves the Transaction Key from the plain text file.

You change the plain text file when your Transaction Key changes, not the script itself.

This is how you set it up.


1. Decide on a file name for the file to contain

your Transaction Key. A file name extension of

“.cgi” (or “.pl” if your server runs scripts only

with the .pl extension) could prevent the file

contents from displaying in snooper’s browsers.

2. In your script, find the line where you assign the

Transaction Key to a variable. It may be something

like this:

my $transactionKey = ‘ab32NOP’;

Replace that line with these four lines:

open RgSIMhf,’____________’;

my $transactionKey = join ”,<RgSIMhf>;

close RgSIMhf;

$transactionKey =~ s/^s*(.*?)s*$/$1/s;

Replace the underline in the first of the above

four lines with the file name you decided upon in

step 1.

Upload your script and verify that it has 755

permissions.

3. Use a plain text word processor, like NotePad or

BBEdit, and paste or type the Transaction Key into

the workspace window. Save the file with the file

name you decided upon in step 1.

3. Upload the file with the Transaction Key into the

same directory where your script is installed.

Now, whenever you change your Transaction Key, you only need to change the one small plain text file.

2010-05-26T17:18:54+00:00 February 11th, 2003|CGI and Perl|0 Comments

About the Author:

Leave A Comment