Developers: Earn $100.00 for referring a client for the Authorize Net Payment Gateway.
We offer No Cost Set Up, Great Rates, and Better Service. Call James at 301-829-3331 to Get Paid!

Simple Integration Method (SIM)
Implementation Guide

Card-Not-Present Transactions Version 1.0

Table of Contents

Introduction

Payment gateways facilitate electronic commerce by enabling merchants to accept credit cards and electronic checks as methods of payment for goods and services sold online. The gateway acts as a bridge between the merchant’s Website and the financial institutions that process payment transactions. Payment data is collected online from the shopper and submitted to the gateway for real-time authorization.

Authorization is the process of checking the validity and available balance of a customer’s credit card before the transaction can be accepted. To authorize a given credit card transaction, the gateway transmits the transaction information to the appropriate financial institutions for validation, then returns the response (approved or declined) from the institution to the merchant or customer. The payment gateway supports real-time and offline requests for credit card authorization.

Note: The payment gateway is targeted towards merchants that process Card-Not-Present transactions. In a Card-Not-Present transaction, the merchant and the shopper are not in the same physical location and the customer usually calls in the payment data or keys in the details of the credit card on a Website. All e-commerce and mail/telephone orders are Card-Not-Present transactions.

The gateway also supports electronic check transactions. Merchants can collect consumer bank account numbers and routing numbers to pay for purchases.

This document describes how transactions can be submitted to the gateway for real-time processing using the Simple Integration Method.

Simple Integration Method (SIM)

What is SIM?

The Simple Integration Method is a relatively simple and secure method to submit transactions to the Payment Gateway. Merchants using this method have the option to let the gateway handle all the steps in transaction processing—payment data collection, data submission, and response to customer. Any request to the gateway is required to contain information that indicates to the gateway that the transaction is authentic and has been submitted for processing with the merchant’s knowledge. This information is contained in a fingerprint that has to be generated by the merchant and included with every request submitted to the gateway. The fingerprint is a hash generated using the HMAC-MD5 hashing algorithm on a set of pre-defined transaction-specific fields. If the fingerprint cannot be validated by the gateway, the request will be rejected.

How does SIM work?

The merchant collects payment information on their Website using either their own payment form or by requesting the gateway’s Payment Form. The merchant can also request the gateway’s Receipt Page to return to the customer. For each request or transaction submitted to the Payment Gateway, the merchant generates and submits a unique fingerprint.

Collecting Payment Data

The merchant can choose to host the Web page where the customer enters payment data, or request that the gateway host the page. The page hosted by the gateway to collect payment data is referred to as the Payment Form, and can be configured by the merchant to look like their Website. Using the gateway-hosted Payment Form, merchants can collect payment data securely without having a secure Website.

Submitting a Request to the Gateway

A request to generate the gateway’s Payment Form must include a unique merchant-generated fingerprint. This fingerprint is used to authenticate that the request originated from an authorized merchant.

If the merchant hosts their own secure payment form, the fingerprint must be submitted along with transaction information to the gateway.

Rendering a Response to the Customer

The response returned by the gateway to the customer’s browser is referred to as a Recipt Page. The merchant can configure the Receipt Page to look like their Website. However, the merchant also has the option to receive the transaction response from the gateway, customize it, and send back a receipt page to the gateway. The gateway then relays the merchant-generated receipt page to the customer’s browser. This response option is referred to as Relay Response. Merchants who use Relay Response can exercise a greater degree of control over the messaging of a response to the customer.

SIM Implementation

In order to integrate to the Payment Gateway using the Simple Integration Method, the merchant needs to be able to construct an HTML form that can generate a fingerprint and post information including the fingerprint to https://secure.authorize.net/gateway/transact.dll.

What is required to implement SIM?

• The merchant’s hosting provider must have server scripting or CGI capability like ASP, PHP, Perl, JSP
• Merchants should be able to securely store files containing sensitive account information and apply access controls. They also have to be able to store sensitive information in a secure, restricted-access database.
• Merchant’s hosting their own payment form need to have secure servers.

Steps to Integrate to the gateway using SIM

1. The merchant obtains a transaction key from the Merchant Interface. (The gateway-generated transaction key is similar to a password and is used to generate a fingerprint. The Merchant Interface is a tool through which merchants can manage their accounts and transaction activity. A Login ID and password are required to access this tool. The URL to the Merchant Interface is available to the merchant from their merchant service provider)

2. The merchant needs to modify their Web pages to contain the fingerprint-generating function, or script. The script, whether on a server or embedded in the HTML page itself, generates the unique fingerprint.

3. The merchant can create the fingerprint by modifying sample scripts provided in the Merchant Interface, or by writing and implementing their own script.

4. The fingerprint and the information required to process the transaction are posted to the gateway. The Standard Transaction Submission API for SIM describes the information that is required to submit a transaction to the gateway.

Obtaining and Storing the Transaction Key

The transaction key is a gateway-generated, random alphanumeric string that is one of the inputs to the fingerprint-generating function. The transaction key is a unique value that is exchanged between the gateway and the merchant. It is used by the gateway to authenticate the fingerprint and the transaction as originating from an authorized merchant. It is therefore extremely important that the transaction key is stored securely on the merchant’s server once it has been obtained from the Merchant Interface.

To obtain the Transaction Key from the Merchant Interface:

1. Log into the Merchant Interface

2. Select Settings from the Main Menu

3. Click on the Obtain Transaction Key in the Security section

4. Type in the answer to your secret question (The secret question and answer is setup during account activation. It is required to authenticate the merchant before the transaction key is generated.)

5. Click Submit

6. The transaction key is returned by the Merchant Interface

Creating and generating a fingerprint

The fingerprint is a hash generated using an HMAC-MD5 algorithm on the following fields:

• Merchant Login. This is the merchant Login ID sent in the x_Login field in the Standard Transaction Submission API for SIM
• Transaction Key
• Timestamp of generation of the fingerprint. This must match the time sent in in x_FP_Timestamp field in the Standard Transaction Submission API for SIM.
• Sequence number of the transaction. This can be a merchant-specific invoice number or a randomly-generated number. This number needs to be sent in the x_FP_Sequence field in the Standard Transaction Submission API for SIM.
• Amount of the transaction. The final transaction amount used to generate the fingerprint has to correspond with the amount sent in the x_Amount field in the Standard Transaction Submission API for SIM.
• For transactions that include the currency code, the x_Currency_Code value must also be used as an input for fingerprint generation. For transactions sent with x_Currency_Code, the Payment Gateway will use this value as an additional input for regenerating the transaction fingerprint.

Sample of fingerprint generation

The following sample shows the above fingerprint input values and the order in which they are placed to generate the transaction fingerprint. Input values must be ordered as shown in this sample, otherwise the gateway-generated fingerprint will not match the merchant-generated fingerprint, and the transaction will be rejected.

Example values for the fingerprint parameters are:

• x_Login = authnettest

• x_FP_Sequence = 789

• x_FP_Timestamp = 67897654

• x_Amount = 10.50

• x_Currency_Code = GBP

• x_Tran_Key = ab34986jg5678655

Sample of fingerprint generation without the currency code (x_Currency_Code):

Fingerprint = HMAC-MD5 (“authnettest^789^67897654^10.50^”, “ab34986jg5678655”)

Note: The fields are concatenated and separated by the “^” character. Please note the trailing “^” in the concatenated string in the case of fingerprint generation without currency code. Here, the transaction key is the cryptographic key used in the HMAC calculation.

Sample of fingerprint generation with the currency code (x_Currency_Code):

Fingerprint = HMAC-MD5 (“authnettest^789^67897654^10.50^GBP”, “ab34986jg5678655”)

Note: The fields are concatenated and separated by the “^” character. Here, the transaction key is the cryptographic key used in the HMAC calculation.

Sample fingerprint-generating functions, or scripts, are provided in the Merchant Interface. Please refer to Appendix E for details on the sample scripts and integrations.

Construct an HTML form to generate the fingerprint and POST transactions to the gateway

The post string will consist of a set of NAME/ VALUE pairs. The NAME is the field name and indicates to the gateway what information is being submitted. The VALUE contains the content of the field. The response rendered by the gateway depends on the information in the post string. (Please refer to the Sample SIM Integration – Form Construction section of this document)

Merchant collects payment data

If the merchant hosts their own payment form then the information posted to the gateway needs to contain the minimum set of fields required to process the transaction. The set of required fields is described in the section Standard Transaction Submission API for SIM.

Merchant Requests the Gateway’s Payment Form

If the merchant does not have the ability to host secure Web pages then the post string needs to contain only the information required to identify the merchant and request the gateway’s Payment Form. If the merchant has collected information from a customer on their site before requesting the gateway’s Payment Form, the merchant can include that information in the post string as hidden fields. This results in the gateway rendering a Payment Form populated with the information passed in by the merchant.

Configuring the Gateway Response (Receipt Page or Relay Response)

The post string can contain information that indicates to the gateway how the Receipt Page rendered by the gateway should be formatted. Merchants requesting Relay Response can also provide a URL in the post string to which the gateway will post a response. The merchant’s site can receive, parse, and customize the response and post it back to the gateway. The gateway will then relay the response to the customer.

Using the Merchant Interface to Configure SIM

The merchant has the option to submit information in the post string regarding the format of the Receipt Page, the Payment Form, and the destination URL of the Relay Respone for each transaction. Alternatively, the merchant can configure these in the Merchant Interface. (The Merchant Interface is a tool through which merchants can manage their accounts and their transaction activity. A Login ID and password are required to access this tool. The URL to the Merchant Interface is available to the merchant from their merchant service provider.) It is recommended implementation is to not send in configuration data on a per-transaction basis.

Payment Form Settings

The merchant can configure the following on the Payment Form:

• The background color of the form

• The color of the text on the form

• The header text

• The footer text

• The merchant can also configure the set of fields on the Payment Form that should be displayed to the customer, as well as the set of fields the customer will be required to fill out

To configure Payment Form fields, header and footer text and color: 1. 2. 3. • • • •

Log into the Merchant Interface

Select Settings from the Main Menu

Click on the Payment Forms link in the Transaction Submission section

Note: When creating headers and footers for receipt pages avoid using double quotes.

Receipt Page Settings

• The merchant can configure the following on the Receipt Page:

The background color of the form

The color of the text on the form

The header text

The footer text

• The merchant can also define the method by which the customer should be returned to the merchant Website and the destination URL to which the customer will be returned.

To configure the Receipt Page:

1. Log into the Merchant Interface

2. Select Settings from the Main Menu

3. Click on the Receipt Page link in the Transaction Response section

Note: When creating headers and footers for receipt pages avoid using double quotes.

Relay Response URL Settings

The merchant can configure the default URL to which the gateway should send the response in the Merchant Interface by doing the following:

1. Log into the Merchant Interface

2. Select Settings from the Main Menu

3. Click on Relay Response in the Transaction Response section

4. Enter the URL to which the gateway should send the response by default

The merchant can configure one or more valid Relay Response URLs. To configure valid relay response URLs in addition to the default specified

1. Log into the Merchant Interface

2. Select Settings from the Main Menu

3. Click on the Response /Receipt URL link in the Transaction Response section

4. Click on the Add URL link

5. Add a valid URL

6. Click Submit

The gateway will reject the transaction if the URL sent in the transaction is not configured through the Merchant Interface.

Sample SIM Integrations – Form Construction

This section describes how to create an HTML form to post transactions to the gateway with a fingerprint. The basic HTML tags used to construct a form to post a transaction to the gateway would be written as follows:

<FORM METHOD=POST

ACTION="https://secure.authorize.net/gateway/transact.dll">

</FORM>’

Any form fields that need to be sent to the system would be enclosed as <INPUT> fields within the opening <FORM> tag and the closing </FORM> tag. For example, a form that contained a merchant’s Login ID would look like this:

<INPUT TYPE=HIDDEN NAME="x_Login" VALUE="your login ID goes here">

Some things to note about the sample line above:

  <INPUT> is an HTML tag that does not need a closing tag (unlike <FORM> which needs a closing tag </FORM>).

  TYPE in the sample above is an attribute of the INPUT tag and has a value HIDDEN. In this case it means the information being passed to the gateway server would be hidden from the customer’s HTML page (since the information that is being passed is the merchant’s Login ID).

  The NAME="x_Login" is the category, or field, of information that is being passed, in this case the Login ID of the merchant.

  The VALUE="your Login ID goes here" is where the merchant would put their merchant Login ID (inside the double quotes).

  The NAME/VALUE pair is one of the things that the gateway server looks for when a transaction is submitted. If part of the NAME/VALUE pair is not present or improperly formed, the transaction will be rejected.

The gateway will accept fields that are not specified in the API so long as the name used to describe the field is not identical to a field name in the API. These fields are called “user” fields and can contain any information that might be useful in the transaction. User fields will be echoed back with the results of the transaction and will be displayed on the merchant's receipts; they will not be displayed on the customer’s receipts

The following are some examples of HTML code, along with the server-side script, that can be customized and inserted into a merchant’s Website to provide easy ways to integrate the Website with the system. Server-side scripting capability on the merchant Website is required for this integration, as the script needs access to a secret transaction key that is stored securely in the merchant’s Web server. Sample code and library in ASP, PHP, and Perl are provided in the Merchant Interface. As part of the integration, the merchant Website must provide the appropriate parameters to the InsertFP or CalculateFP library functions that are provided with the sample code.

Example 1 – Minimum requirements for requesting a Payment Form

The following HTML code along with the server-side script represents the minimum data that would need to be inserted into a page to provide a connection to the system. It shows that the fingerprint, time stamp, and the sequence number are inserted into the HTML form POST along with Login ID and other required fields. The result of this HTML code snippet is a button. Clicking on the button will take the user to the gateway’s Payment Form.

A call to generate the fingerprint should be made when the button is clicked and before the Payment Form request is made to the gateway. A sequence number should be generated and the total amount of the tranaction calculated before the call to generate the fingerprint is made. The function used to generate the fingerprint takes these fields (amount, transaction key, Login ID, and sequence number) The transaction amount should not change after the fingerprint is generated. All trailing spaces need to be removed from the fields used to generate the fingerprint

<!--#INCLUDE FILE="simlib.asp"-->

<FORM METHOD=POST ACTION="https://secure.authorize.net/gateway/transact.dll">

<% ret = InsertFP (loginid, txnkey, amount, sequence) %>

<INPUT TYPE=HIDDEN NAME="x_Login" VALUE="your login ID goes here">

<INPUT TYPE=HIDDEN NAME="x_Show_Form" VALUE="PAYMENT_FORM">

<INPUT TYPE=HIDDEN NAME="x_Amount" VALUE="amount goes here">

<INPUT TYPE=SUBMIT VALUE="Click here for secure payment form">

</FORM>

The function InsertFP is provided by the gateway and can be downloaded from the Merchant Interface. This function must be called within a server-side script on the merchant Web server. The above example shows the call being made in an ASP scripting environment.

Example 2 – Using a form to gather information

The following HTML code along with the server-side script demonstrates the ability to send additional information to the system, including information that is specified by the customer. The result of this HTML code snippet is a page that displays a form allowing the customer to specify their name and any specific shipping instructions. The x_First_Name and x_Last_Name fields are normal fields recognized by the system. The Shipping_Instructions field is not a field recognized by the system, and so it is treated as a user field. System-recognized fields can also be used for normal shipping information. The code also shows that the fingerprint, time stamp, and the sequence number are inserted into the HTML form POST along with Login ID and other required fields.

<!--#INCLUDE FILE="simlib.asp"-->

<FORM METHOD=POST ACTION="https://secure.authorize.net/gateway/transact.dll">

<% ret = InsertFP (loginid, txnkey, amount, sequence) %>

<INPUT TYPE=HIDDEN NAME="x_Login" VALUE="your login ID goes here">

<INPUT TYPE=HIDDEN NAME="x_Show_Form" VALUE="PAYMENT_FORM">

<INPUT TYPE=HIDDEN NAME="x_Amount" VALUE="amount goes here">

<INPUT TYPE=HIDDEN NAME="x_Cust_ID" VALUE="a unique customer ID goes here">

<INPUT TYPE=HIDDEN NAME="x_Description" VALUE="description of transaction">

<INPUT TYPE=HIDDEN NAME="x_Invoice_Num" VALUE="invoice number goes here">

Enter your first name:

<INPUT TYPE=TEXT NAME="x_First_Name"><BR>

Enter your last name:

<INPUT TYPE=TEXT NAME="x_Last_Name"><BR>

Enter Any special shipping instructions:

<INPUT TYPE=TEXT NAME="Shipping_Instructions"><BR>

<INPUT TYPE=SUBMIT VALUE="Click here for secure payment form">

</FORM>

The function InsertFP is provided by the gateway and can be downloaded from the Merchant Interface.

Example 3 – Requesting a Receipt Page

The following HTML code shows the request for the Receipt Page, including generating the fingerprint and sending it along with rest of the fields.

<!--#INCLUDE FILE="simlib.asp"--><FORM METHOD=POST ACTION="https://secure.authorize.net/gateway/transact.dll”>

<% ret = InsertFP (loginid, txnkey, amount, sequence) %>

<INPUT TYPE=HIDDEN NAME="x_Version" VALUE="3.1">

<INPUT TYPE=HIDDEN NAME="x_Login" VALUE="your login ID goes here">

<INPUT TYPE=HIDDEN NAME="x_Card_Num" VALUE="customer’s credit card number">

<INPUT TYPE=HIDDEN NAME="x_Exp_Date" VALUE="customer’s credit card expiration date goes here">

<INPUT TYPE=HIDDEN NAME="x_Amount" VALUE="amount goes here">

<INPUT TYPE=SUBMIT VALUE="Submit">

</FORM>

The function InsertFP is provided by the gateway and can be downloaded from the Merchant Interface.

Example 4 – Requesting a Payment Form and a Relay Response

The following are the minimum requirements for requesting a Relay Response from the gateway. This code includes the function for generating the fingerprint and sending it along with rest of the fields.

<!--#INCLUDE FILE="simlib.asp"--><FORM METHOD=POST ACTION="https://secure.authorize.net/gatewaytransact.dll/">

<% ret = InsertFP (loginid, txnkey, amount, sequence) %>

<INPUT TYPE=HIDDEN NAME="x_Login" VALUE="your login ID goes here">

<INPUT TYPE=HIDDEN NAME="x_Amount" VALUE="amount goes here">

<INPUT TYPE=HIDDEN NAME="x_Relay_Response" VALUE="True">

<INPUT TYPE=HIDDEN NAME="x_Relay_URL" VALUE="Any valid URL">

<INPUT TYPE=SUBMIT VALUE="Click here for secure payment form">

</FORM>

The function InsertFP is provided by the gateway and can be downloaded from the Merchant Interface.

Since the HTML code that is returned to the browser appears to come from the gateway server, any links to images need to be absolute URLs with the full path to the server on which the images reside. If relative URLs are used, the customer’s browser will try to load the images from the gateway server and would fail.

The URL specified in x_Relay_URL should be a script that can interactively parse the information that is posted to it. The URL can be a plain HTML page if a static response is desired for every transaction. In this scenario, the merchant's Web server will need to be configured to allow the POST method to plain HTML pages.

Use of frames is not recommended. Even though the Payment Form used will be secure the lock icon on the user’s taskbar will key off the surrounding frame and not off the Payment Form. The page will not look secure to the customer.

Redirects in the relay scripts are not recommended, as the information may not be transferred properly.

When the merchant’s response is relayed back to the customer, anything that is in the HTTP headers will be replaced. This means if a developer is relying on custom information to be in these headers, such as cookies, their implementation will most likely fail.

Standard Transaction Submission API for SIM

The Standard Transaction Submission API defines the information that can be submitted to the gateway for real-time transaction processing. The API consists of a set of fields that are required for each transaction, and a set of fields that are optional. Under the API, the gateway accepts a NAME/ VALUE pair. The NAME is the field name and indicates to the gateway what information is being submitted. The VALUE contains the content of the field. In transmitting information to the gateway the merchant site should post transactions to https://secure.authorize.net/gateway/transact.dll.

The following tables contain the data fields that may be submitted to the system with any transaction. The fields are grouped logically in the tables, based on the information submitted. Each table contains the following information:

• Field – Name of the parameter that may be submitted on a transaction
• Required – Indicates whether the field is required on a transaction. If Conditional, indicates that the field is required based on the existence or value of another field. In cases where a dependency exists, an explanation is provided.
• Value – Lists the possible values that may be submitted for the field. In cases where a format is validated, an explanation is provided.
• Max Length – Indicates the maximum number of characters that may be supplied for each field.
• Description – Provides additional details on how the field is used

Merchant Account Information

The following fields in the API allow the system to identify the merchant submitting the transaction and the state of the merchant’s account on the gateway.

Fingerprint Fields

Payment Form Fields

These fields are optional and need to be used only if the merchant is using the gateway’s Payment Form to collect payment data. All these fields except x_Show_Form can also be configured in the Merchant Interface and do not have to be submitted with each transaction.

Receipt Page Fields

All fields in this section are optional. The merchant can configure the information captured in these fields in the Merchant Interface instead of sending it in with every transaction.

Fields Common to Both the Payment Form and Receipt Page

All fields in this section are optional. The merchant can configure the information captured in these fields in the Merchant Interface instead of sending it in on every transaction.

Relay Response Fields

The following fields indicate to the gateway that the merchant is requesting a Relay Response. They should not be passed in if the merchant is requesting a Receipt Page or a Payment Form

Customer Name and Billing Address

The customer billing address fields listed below contain customer billing address information associated with each transaction.

Additional Customer Data

Merchants may provide additional customer information with a transaction, based on their respective requirements.

Email Settings

The following fields describe how and when emails will be sent when transactions are processed by the system.

Invoice Information

Based on their respective requirements, merchants may submit invoice information with a transaction. Two invoice fields are provided in the gateway API.

Customer Shipping Address

The following fields describe the customer shipping information that may be submitted with each transaction.

Transaction Data

The following fields contain transaction-specific information such as amount, payment method, and transaction type.

Level 2 Data

The system supports Level 2 transaction data by providing the following fields as part of the transaction submission API.

Transaction Submission API for Wells Fargo SecureSource Merchants

For merchants who process transactions through the Wells Fargo SecureSource product, some additional rules apply to transaction processing. Fields that are optional in the Standard Transaction Submission API are required for Wells Fargo SecureSource merchants. The following tables describe these required fields. Only those fields that are different from the standard API are called out in this section.

Customer Name and Billing Address

Email Settings

Additional Customer Data

Gateway Response API

This section describes the response returned by the gateway when a transaction is submitted for processing. The gateway response to a transaction submitted via SIM is either a Receipt Page that is displayed to the consumer or a POST string to a site designated by the merchant. The merchant can then parse the POST string, customize a response, and submit it back to the gateway. The gateway will then relay the response to the customer’s browser.

Fields in the Gateway Response

The following table indicates the order of fields returned in the SIM response from the gateway to the merchant server for a Relay Response. Any fields that were sent to the gateway in addition to the fields described in the Standard Transaction Submission API are returned in the response after the set of fields described in the table below.

SIM Relay Response

The response from the gateway to a request via SIM for a Relay Response consists of a set of fields returned as a POST string to the merchant server at the location indicated in the x_Relay_URL field.

SIM Transaction Response Versions

There are two versions of the response string. The set of fields in the response differ based on the response version.

Version 3.0

The version 3.0 response contains system fields from position 1 to 38 and echoes merchant defined fields from 39 on, in the order received by the system.

Version 3.1

The version 3.1 response string contains 68 system fields with field number 39 representing the Card Code (CVV2/CVC2/CID) response code. Merchant-defined fields are echoed from field 69 on. Merchants wishing to use the Card Code feature must switch to transaction version 3.1.

Setting the Transaction Version

To set the transaction version, do the following:

1. Log into the Merchant Interface

2. Select Settings from the Main Menu

3. Click on Transaction Version in the Transaction Response section

4. Change the transaction version using the drop-down box

5. Click Submit

Note: You can only upgrade to a higher transaction version. You cannot set your transaction version to a previous version.

Response Code Details

When a payment transaction is submitted to the gateway, the gateway returns a response that indicates the general status of the transaction, including details of what caused the transaction to be in that state. The fields in the response that describe the status of the transaction are Response Code, Response Reason Code, and Response Reason Text. The following tables define the values that the gateway may return in these fields.

Description of Response Fields

The three status fields in the transaction response are defined as follows:

• The Response Code indicates the overall status of the transaction with possible values of approval, decline, or error.

• The Response Reason Code gives merchants more information about the transaction status.

• The Response Reason Text is a text string that will give more detail on why the transaction resulted in a specific response code. This field is a text string that can be echoed back to the customer to provide them with more information about their transaction. It is strongly suggested that merchants not parse this string expecting certain text. Instead, a merchant should test for the Response Reason Code if they need to programmatically know these results; the Response Reason Code will always represent these meanings, even if the text descriptions change.

Response Codes

Response Reason Codes & Response Reason Text

SIM Best Practices

This section discusses some of the best practices recommended for the implementation of the Simple Integration Method. These should serve as guidelines to a robust and secure integration of the merchant’s shopping site with the Payment Gateway

Best Practices Summary

• The transaction key should be stored securely on the merchant’s Web server or hosting provider.
• The transaction key should not be exposed in any Web page that is displayed the end customer.
• The transaction key should be changed periodically.
• The merchant server’s system clock needs to be set to proper time and timezone.
• Merchant should collect payment data on secure pages only.
• The secret question and answer configured during merchant setup should be secured to prevent unauthorized personnel from obtaining the transaction key.
• The fingerprint should be generated as late as possible in the checkout process. It is recommended that the fingerprint be regenerated if the amount of the transaction is altered after the initial generation of the fingerprint.
• The order number or invoice number should be used as the sequence value to generate the fingerprint. It is recommended that the merchant perform a validation of the order before generating the fingerprint and submitting it to the gateway.

Some of the best practices summarized above are discussed in detail in the following paragraphs.

Securely store the transaction key

The most important aspect of implementing SIM in a secure fashion lies in storing the transaction key in a secure location where only authorized persons can see or modify it.

If the merchant is using a third-party shopping cart or hosting provider, it is recommended that tha merchant determine the exact procedure by which the third party should securely store the transaction key. Only authorized third-party personnel should have access to the transaction key.

If the merchant uses a database like Oracle, MySQL, or SQL Server, another option is to store the transaction key in the database. In this case the merchant must ensure that the database login procedure is secure.

If the merchant is storing the transaction key in a file, strict access control and data encryption is strongly recommended. Access to the file should be restricted to only the script that generates the fingerprint.

The transaction key is highly confidential data, and should be protected accordingly.

Do not expose the transaction key to the customer

Under no circumstances should the transaction key be exposed in a Web page output that is displayed to the customer. Even if the transaction key appears in a hidden HTML form field or a hidden frame, the integration to the gateway is NOT then considered secure. A view HTML source on all the Web pages generated by the merchant to the customer should neverdisplay the transaction key.

The merchant should do everything possible to leverage the security features of their web server to secure the key from the end customer.

Change transaction keys often

It is recommended that the merchant establish a policy to change transaction keys frequently. The gateway provides a simple interface to quickly generate and obtain a new transaction key, as well as disabling the old transaction key. It is recommended that merchants disable the old transaction key each time a new trasaction key is obtained.

It is recommended that the transaction key be changed if there is any suspicious activity on the merchant’s account. Transaction acitivty can be monitored through the Merchant Interface.

A change in personnel with access to the transaction key, especially system administrators, should prompt a change in the transaction key.

Secure the secret answer

Configuring a secret question and answer is part of the merchant’s account setup on the Payment Gateway. The secret answer is required to authenticate the merchant each time they change the transaction key. It is recommended that the merchant designate a specific individual or role that can change transaction keys. Only that individual or role should have knowledge of the secret question and answer and the ability to change the transaction key. A formal policy to change the transaction key and secret question and answer should be implemented in the event of personnel turnover. It is recommended that the merchant choose an answer that is not easily guessed.

Generate fingerprint as late as possible in the checkout process

It is a good practice to generate the fingerprint only at the last step of the checkout process, as opposed to generating it on every page or as each item is added to the shopping basket. The fingerprint should be generated by the merchant’s server-side script when the final transaction amount is known and the customer has committed to the purchase.

If the transaction amount changes between the generation of the fingerprint and the submission of the transaction and the fingerprint is not updated, the transaction will be rejected. This is because the transaction amount submitted in the post string will not match the amount encrypted in the fingerprint.

If the merchant ‘s checkout process is such that the fingerprint is generated each time an item is added to a shopping cart, or multiple times before an order is complete and ready to be submitted to the gateway, merchants may become subject to abuse by the end user. It is possible that an unauthorized person could view source on each page the fingerprint is generated, accumulate the

unused fingerprints, and use them to submit unauthorized transactions to the gateway until the fingerprints expire.

Validate orders when generating fingerprint

It is also recommended that the merchant use their unique order number or invoice number as the sequence value, submitted in the x_FP_Sequence field. The merchant can then validate the transactionagainst the merchant-generated invoice or order number before using the sequence value to generate the fingerprint.

Ensure your system clock is set to proper time and timezone

The gateway will validate the timestamp of a fingerprint submitted to the system before accepting a transaction. This check is based on the value sent in x_FP_Timestamp field. The gateway will only accept a fingerprint generated within an hour before the transaction was received. If the fingerprint has expired, the transaction will be rejected.

The acceptance of the transaction by the gateway is therefore dependant on the merchant’s system clock being set to the correct time based on the timezone setting of the system. Though it is not required that the system clock be accurate to the last second, it is recommended that the clock is as close as possible to the actual time for the merchant’s timezone.

Appendix A – Types of Credit Card Transactions

There are two steps to credit card transaction processing:

1. Authorization is the process of checking the validity and available balance of a customer's credit card before the transaction is accepted. The transaction submission methods describe the request for authorization.

2. Settlement, also referred to as “Capture,” is the process by which the funds are actually transferred from the customer to the merchant for goods and services sold. Based on the transaction type specified in the authorization request, the gateway will initiate the settlement step. As part of the settlement process, the gateway will send a settlement request to the financial institution to request transfer of funds. Please note that the timeframe within which funds are actually transferred is not controlled by the gateway.

Note: The merchant can specify when the last transaction is picked up for settlement by the gateway. To modify the Transaction Cut-Off Time, do the following:

1. Log into the Merchant Interface

2. Select Settings

3. Select Transaction Cut-Off Time in the General section

4. Using the drop-down boxes, select the desired cut-off time

5. Click Submit to save changes

Credit Card Transaction Types

The following table describes the type of transactions that can be submitted to the gateway and how the gateway will process them.

Appendix B – Features of the Gateway

The following features are supported by the gateway in an effort to reduce merchant’s chargeback liability.

Address Verification System

The Address Verification System (AVS) helps merchants to detect suspicious transaction activity. To use this system, the merchant must submit the customer’s credit card billing address to the gateway for validation. This information is submitted by the gateway to the financial institutions. The financial institutions compare the submitted address with the billing address on file for that particular credit card and return an AVS response code to the gateway. The gateway includes this code in the response back to the merchant.

The merchant can configure the gateway to reject or accept transactions based on the AVS code returned. To configure rejection or acceptance of a transaction based on the AVS code, do the following:

1. Log into the Merchant Interface

2. Select Settings from the Main Menu

3. Click on the Address Verification System (AVS) link from the Security section

4. Check the box(es) next to the AVS codes that the system should reject

5. Click Submit to save changes

Note: It is recommended that merchants enable some level of Address Verification to avoid non-qualified transaction surcharges that can be levied by merchant banks and merchant service providers. Please note, however, that the merchant will incur applicable transaction fees for transactions that are declined due to an AVS mismatch (as with any other declined transaction). System defaults are marked in italics in the table above.

Credit Card Identification Code (CVV2/CVC2/CID)

The Credit Card Identification Code, or “Card Code,” is a three- or four-digit security code that is printed on the back of credit cards in reverse italics in the card’s signature panel (or on the front for American Express cards). The merchant can collect this information from the customer and submit the data to the gateway. The gateway will pass this information to the financial institution along with the credit card number. The financial institution will determine if the value matches the value on file for that credit card and return a code indicating whether the comparison failed or succeeded, in addition to whether the card was authorized. The gateway passes back this response code to the merchant. The merchant can configure the gateway to reject or accept the transaction based on the code returned.

To configure the filter to reject certain Card Code responses, do the following:

1. Log in-to the Merchant Interface

2. Select Settings from the Main Menu

3. Click on the Card Code Verification link from the Security section

4. Check the box(es) next to the Card Codes that the system should reject

5. Click Submit to save changes

Appendix C – Customizing Notification to Customers

Merchants will be sent a confirmation email after the gateway completes processing on a transaction submitted to the system. The confirmation email enables merchants to know the results of a given transaction. Multiple contacts can be configured to receive these email notifications. Additionally, merchants can choose to send a confirmation email to their customers.

Configuration of these contacts can be done through the Merchant Interface:

1. Log into the Merchant Interface

2. Click on the Settings link from the left navigation bar

3. Click on the Email Receipts link from the Transaction Response section

4. Check the box if email receipts should be sent to the customer

5. Configure the header and footer of the email message

6. Click Submit

It is possible to configure the confirmation email on a per-transaction basis by submitting the information with each transaction. The following table describes the fields used in the API to configure email notification to the customer; all fields are optional.

Appendix D – Submitting Test Transactions to the System

Test Mode

Test Mode is a special mode of interacting with the system that is useful during the initial setup phase, where a merchant may want to test their setup without processing live card data.

To set an account to Test Mode, do the following:

1. Log into the Merchant Interface

2. Select Settings from the Main Menu

3. Click on the Test Mode Link in the General section

4. Click on the Turn Test On button

In Test Mode, all transactions appear to be processed as real transactions. The gateway accepts the transactions, but does not pass them on to the financial institutions. Accordingly, all transactions will be approved by the gateway when Test Mode is turned on. Transactions submitted in Test Mode are not stored on the system, and will not appear in any reports or lists.

Note: Test Mode is only supported if the merchant is submitting transactions from a Website or through the Virtual Terminal. If the merchant uploads a file of transactions for offline processing, the gateway will reject the file.

Running a Test Transaction

It is possible to run a test transaction if Test Mode has been turned off. This can be done by indicating to the gateway in the transaction submission request that the transaction should be processed as a test transaction. The corresponding field in the transaction submission API is x_Test_Request. If a test transaction is desired, the value of this field should be set to TRUE.

The following table describes the gateway behavior based on the incoming field value and the mode configured through the Merchant Interface.

If there is no value submitted in the x_Test_Request field, the system will use the configuration specified in the Merchant Interface.

Test credit card numbers

Any of the following card numbers can be used to run test transactions. Please note that these numbers do not represent real card accounts; they will return a decline in live mode, and an approval in test mode. Any expiration dates after the current day's date can be used with these numbers.

There is also a test credit card number that can be used to generate errors. THIS CARD IS INTENDED TO PRODUCE ERRORS, and should only be used if that is the intent.

To cause the system to generate a specific error, set the account to Test Mode and submit a transaction with the card number 4222222222222. The system will return the response reason code equal to the amount of the submitted transaction. For example, to test response reason code number 27, a test transaction would be submitted with the credit card number, “4222222222222,” and the amount, “27.00.”

Appendix E – Sample Scripts

The sample scripts provided through the Merchant Interface will generate a Payment Form request containing a fingerprint. The gateway will return a Payment Form. These sample scripts are provided to facilitate the merchant’s understanding of the SIM integration and should not be implemented without proper modification. They can be modified to fit the context of the merchant’s checkout process.

Note: If you are sending the currency code (x_Currency Code) with the transaction, be sure to include the value as an input when generating the fingerprint. Also be sure to place all fingerprint values in the correct order for fingerprint generation (see the Creating and Generating a Fingerprint section on page 7).

To download a sample script:

Log into the Merchant Interface 1. 2. 3.

Select Help from the Main Menu

Click on Sample Simple Integrations (SIM) Scripts.

ASP Script

There are 4 files provided in this sample.

To run this integration, install the scripts on the Web server. Replace the value in SIMDdata.asp with the merchant Login ID and transaction key. Execute the SIM.asp script.

Http://<machine>/<virtualdir>/ASP/sim.asp?x_Amount=100.25&x_Description=Coolstuff should show the gateway’s Payment Form with an amount of $100.25 prefilled. The request to get the Payment Form would have contained the fingerprint.

This will generate the gateway’s Payment Form and uses a set of functions to generate a random sequence number and calculate the time in seconds from 1970. The amount here is hardcoded to $1.

Some of the functions that are used in this integration are:

Merchants that wish to control where the fingerprint is generated should use the Function CalculateFP provided by the gateway and pass in the required parameters including the sequence number and amount. The timestamp can be calculated using the Function GetSecondssince1970().

The script uses the Function InsertFP() to calulate the fingerprint and includes it in the post string to generate the gateway’s Payment Form.

PHP Script

There are 3 files provided in this sample.

These files should be installed on the Web server. The text in the data.php file should be replaced with the merchant Login ID and transaction key.

Http://<machine>/<virtualdir>/PHP/sim.php?x_Amount=100.25x_Description=Coolstuff should show the gateway Payment Form with an amount of $100.25 prefilled. The request to get the Payment Form would have contained the fingerprint. The functions used to generate the fingerprint are the same as described in the ASP Script sections.

Perl Script

There are 3 files provided in this sample.

Executing SIM.pl will send a request to the gateway (with a fingerprint) for a Payment Form. The functions used to generate the fingerprint are the same as described in the ASP Script section.

Appendix F – Certification

It is possible for a merchant to test their integration using a test gateway system.

In order to test the integration, the merchant should post transactions to https://certification.authorize.net/gateway/transact.dll. The test gateway behavior will be identical to the primary gateway. Transactions sent to the test gateway are not submitted to financial institutions for authorization, will not be stored on the system and cannot be retrieved from the system (as is the case when using Test Mode set to TRUE with the primary gateway system).

Appendix G – Currency Codes

Back to Top