|
 |  |
 |
     |  |
We accept credit cards so you can! |
Serving Merchants Since 1996  |
              The Credit Card Store     Apply for a Credit Card Online
|
Simple Integration Method (SIM) 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)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. 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 DataThe 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 GatewayA 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 CustomerThe 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. 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?
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) Obtaining and Storing the Transaction KeyThe 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 fingerprintThe fingerprint is a hash generated using an HMAC-MD5 algorithm on the following fields:
Sample of fingerprint generationThe 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 gatewayThe 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 dataIf 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 FormIf 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 SIMThe 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. 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. • 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. 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 ConstructionThis 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 SIMThe 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:
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.
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.
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.
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.
Merchants may provide additional customer information with a transaction, based on their respective requirements.
The following fields describe how and when emails will be sent when transactions are processed by the system.
Based on their respective requirements, merchants may submit invoice information with a transaction. Two invoice fields are provided in the gateway API.
The following fields describe the customer shipping information that may be submitted with each transaction.
The following fields contain transaction-specific information such as amount, payment method, and transaction type.
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 MerchantsFor 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
Gateway Response APIThis 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.
|