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 $hiddenSIMfieldsmy $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.
No related posts.
