Authorize.Net. Reference Guide

Transcription

1 Authorize.Net Reference Guide

2 2005, Jenzabar, Inc. 5 Cambridge Center Cambridge, MA This document is confidential and contains proprietary information. The use of this document is subject to the license agreement that governs usage of the associated software. No part of this document may be photocopied, reproduced, stored in a retrieval system, transmitted in any form or by any means, or translated into another language without the prior written consent of Jenzabar, Inc. This document may contain errors, omissions, or typographical errors and does not represent any commitment or guarantee by Jenzabar. The information herein is subject to change with or without notice. Jenzabar disclaims any liability from the use of information herein. Please refer to the most current product release notes for updated information. All rights reserved. Trademarks and Attributions Jenzabar, Jenzabar.com, and all related graphic logos are trademarks of Jenzabar, Inc. All other trademarks not owned by Jenzabar are used for identification purposes and may be trademarks of their respective owners. Filename: inauth Revision History Revision Date Comments March 31, 2005 Standards updates

3 JENZABAR, INC. AUTHORIZE.NET REFERENCE GUIDE TABLE OF CONTENTS GETTING STARTED... 1 Introduction... 1 What is Authorize.Net?... 1 Credit Cards and the Internet... 1 Purpose of This Guide... 1 Intended Audience... 1 Real-Time Web Transactions Process... 2 Overall Process... 2 AUTHORIZE.NET COMPONENTS AND PROCESSES... 3 Components... 3 Two Services... 3 Authorize.Net Virtual Terminal... 3 Authorize.Net E-Commerce Web Site Integration Method... 3 Jenzabar CX s Support of AIM... 4 Jenzabar CX and the Advanced Integration Method...5 Advanced Integration Method... 5 Process Flow... 5 Maintaining Security... 6 Introduction... 6 Background... 6 Authentication... 6 Message Privacy... 6 Message Integrity... 6 Secure Sockets Layer (SSL)... 6 Digital Certificates (Secure Server IDs)... 7 Certificate Authority (CA)... 7 Firewall Configuration... 7 Providers... 7 Cost of VeriSign Services and Products... 7 Encryption... 8 Session Keys... 8 Private and Public Keys... 8 EXCERPTS OF AUTHORIZE.NET DOCUMENTATION... 9 Introduction... 9 Information Included in This Section... 9 Purpose of Included Documentation... 9 Implementing Real Time Processing Introduction Obtaining a Merchant Account Gaining a Secure Server Connection Defining Macros Testing the Connection Verifying Access to Virtual Terminal Basic Integration Concepts Introduction Minimum Requirements for AIM Testing the Authorize.Net Connection i

4 Introduction Setting Up Test Mode Running a Test Transaction Outside of Test Mode Test Credit Card Numbers Testing Error Conditions APPENDIX A JENZABAR CX FILES USED FOR AUTHORIZE.NET Scripts and Descriptions Included Scripts Directory Script Descriptions APPENDIX B FUNCTIONAL REFERENCE AND RESULT FIELDS Standard Transaction Submission API for AIM Merchant Account Information Gateway Response Configuration Customer Name and Billing Address Additional Customer Data Settings Invoice Information Customer Shipping Address Transaction Data Level 2 Data Gateway Response API Introduction Fields in the Gateway Response APPENDIX C RESPONSE CODES Description of Response Fields Introduction Response s Response Reason s and Response Reason Text APPENDIX D FREQUENTLY ASKED QUESTIONS (FAQs) APPENDIX E UNDERSTANDING CREDIT CARD RATES AND FEES Introduction Overview Discount Rates Transaction Fees Monthly Fees Example Transaction INDEX ii

5 Introduction GETTING STARTED What is Authorize.Net? Authorize.Net is a real-time transaction processing system that functions as a payment gateway service using a secure transaction server on the Internet. A real-time system will perform all processing automatically from the Web site 24 hours a day, 7 days a week. Merchants with a valid merchant account can use Authorize.Net to submit, authorize, capture, and settle credit card transactions without the need for a separate transaction terminal or processing software. Automated Clearing House (ACH) collections, also known as Electronic Checks, are also supported on the Authorize.Net system. Authorize.Net works in conjunction with a merchant account supplied by a Merchant Service Provider. This allows you, in your role as the merchant, to accept credit card payments securely and in real-time over the Internet. Credit Cards and the Internet It is important to understand that there is really no such thing as processing credit cards over the Internet. None of the major processing networks (such as Nova, Paymentech, FDC/FDR, Vital, etc.) are connected to the Internet. All credit card processing is done by dedicated dial-up modem and is accessed by a terminal, software, or larger systems found on mainframes. There are, however, real-time systems available to process an approval while the user is at your Web site. If a school does not want any manual tasks associated with credit card processing, they should opt for a real-time system. A real-time system consists of everything needed to conduct online transactions. These systems will capture the credit card information from the Web site where the user enters the information, downloads it to the Host server, transmits it on to the processing center, obtains the approval (or decline), and then sends a confirmation message back to the user at the Web site, all in a matter of seconds. Purpose of This Guide This guide serves as a learning tool and reference guide for setting up and supporting Authorize.Net functionality to work with Jenzabar CX. Intended Audience This guide is intended for the system users in your institution s computer center. System users include the Jenzabar coordinator, Jenzabar system administrator, and programmer/analyst. 1 Authorize.Net

6 Real-Time Web Transactions Process Overall Process The following steps outline how real-time Web transactions are processed by Authorize.Net: Users enter their credit card information onto a payment submission form. The form needs to be set up to run through a Secured Server (SSL) so that the information is encrypted. The encrypted card information is sent to the processing center/payment gateway via HTTPS POST. The processor/bank verifies the card information and either approves or declines the cardholder within seconds. If the cardholder is approved, the amount is moved from the cardholder's bank to the merchant's processing bank. The merchant's processing bank then moves the money to the merchant's checking account. The transaction is now complete. Usually, the money will appear in the in any credit card transaction, and is the step that ensures the merchant is paid for the goods or services. It is fairly simple in concept. All transactions ready for settlement (sometimes referred to as posting) are sent as records to the processing host, where they are stored in a capture database. Payment Gateway stores the result and transmit them back as an HTTPS response. Authorize.Net 2

7 AUTHORIZE.NET COMPONENTS AND PROCESSES Components Two Services Authorize.Net includes the following two separate and distinct services; both services are included with your Authorize.Net account. AuthorizeNet Virtual Terminal, used directly by merchants for manual processing AuthorizeNet E-Commerce Web site Integration methods, used by a Web site for online transactions through one of the following methods: Advanced Integration Method (AIM) Simple Integration Method (SIM) Authorize.Net Virtual Terminal Virtual Terminal is hosted completely on the Authorize.Net transaction servers, where merchants simply log in using their favorite Web browser and perform live transactions using their merchant account. Virtual Terminal replaces standard authorization terminals or software and provides the best solution for merchants who manually enter credit card transactions for mail or phone order sales. Authorize.Net E-Commerce Web Site Integration Method Authorize.Net offers two secure online payment-processing connection methods that allow Internet-based businesses to authorize, process, and manage credit card transactions directly and automatically from an e-commerce Web site. Advanced Integration Method (AIM) is the preferred Authorize.Net integration solution, and uses secure sockets layer (SSL) digital certificate technology to connect securely and directly to the Payment Gateway achieving the highest security for the Internet connection between a merchant and the gateway. Simple Integration Method (SIM) optimizes the security, encryption, and authentication of transactions for merchants that do not have an SSL digital certificate. AIM and SIM provide the highest levels of secure transaction infrastructure available to merchants building an e-commerce business and directly connecting that their Web site to the Authorize.Net Payment Gateway. When using AIM and SIM to connect to the Payment Gateway, a customer enters purchase information (e.g., name, credit card number, etc.) into a payment form on the merchant's Web site. This payment form is hosted either by the merchant, or the merchant may choose to use Authorize.Net's securely hosted, customizable payment form. When the customer clicks to submit his or her purchase information, payment information is encrypted using 128-bit SSL technology and sent to an Authorize.Net transaction server. The server sends the data through the authorization network to the appropriate card issuer's bank, using a secure, proprietary connection. When the authorization process is complete this takes around five seconds the customer receives an approval or decline response, and the Authorize.Net server stores the transaction. Approved transactions are automatically settled each day and are typically funded within two to three business days. Merchants can check the status of current transactions submitted directly from their Web site or run reports on past transaction activity by going to the Authorize.Net Corporate site and logging into their own password-protected Merchant Interface. Online businesses also can use the Authorize.Net Virtual Terminal feature of their Merchant Interface account to enter payment information manually if customers prefer to call in their credit card information. 3 Authorize.Net

8 Jenzabar CX s Support of AIM Of the two types of E-Commerce Web site Integration methods (AIM and SIM), Jenzabar CX s current version of Authorize.Net usage works exclusively with AIM. Authorize.Net 4

9 Jenzabar CX and the Advanced Integration Method Advanced Integration Method Process Flow Advanced Integration Method (AIM) is the recommended method of submitting transactions to the payment gateway. This method allows a merchant s server to connect and securely and directly to the payment gateway to submit transaction data. You as the merchant retain full control of the payment data collection and the user experience. This method requires you to be able to initiate and manage secure Internet connections. The following details the flow of control when using AIM: The user connects securely to CX Eeb and fills in the payment information on CX s payment form and submits the data. A confirmation page displays, allowing the user to review the contents prior to sending it. Once a user submits the data, a cgi script will initiate a secure connection to the Authorize.Net payment gateway and then initiate an HTTPS post of the transaction data to the Authorize.net payment gateway server. The payment gateway receives and processes the transaction data. The payment gateway then generates and submits the transaction response to the CX CGI script. The CX CGI script receives and processes the response. If the response is a success, then an entry is posted to Jenzabar CX via the filepost process (see Appendix A). An online receipt is displayed for the user s reference. If the response is a failure, a message displays to explain the failed request to the end user. 5 Authorize.Net

10 Maintaining Security Introduction Background Security is essential in the use of Authorize.Net. The following components provide the required level of security: Authentication Message privacy Message integrity Secure sockets layers Digital certificates Certificate authority Firewall configuration In physical transactions, the challenges of identification, authentication, and privacy are solved with physical marks, such as seals or signatures. In electronic transactions, the equivalent of a seal must be coded into the information itself. By checking that the electronic seal is present and has not been broken, the recipient can confirm the identity of the message sender and ensure that the message content was not altered in transit. The system relies on advanced cryptography to create an electronic equivalent of physical security. Once activated by digital certificates, SSL immediately begins providing the required components of secure online transactions. Authentication By checking the digital certificate, users can verify to whom the Web site belongs. This supports their confidence in submitting confidential information. Message Privacy SSL encrypts all traffic between their Web server and customers, using a unique session key. To securely transmit the session key to the consumer, the server encrypts it with their public key. Each session key is used only once during a single session with a single customer. These layers of privacy protection ensure that information cannot be viewed if unauthorized parties intercept it. Message Integrity When a message is sent, the sending and receiving computers each generate a code based on the message content. If even a single character in the message content is altered, the receiving computer will generate a different code and then alert the recipient that the message is not legitimate. With message integrity, both parties involved in the transaction know that what they are seeing is exactly what the other party sent. Secure Sockets Layer (SSL) This technology establishes a secure channel for online transactions and should already be enabled on your server. The only requirement for activation is a digital certificate. SSL becomes functional only after you install a digital certificate. SSL employs the essential functions of Authorize.Net 6

11 authentication, data encryption, and data integrity for secure transactions and establishes a secure communications channel between your server and your customer's browser. SSL comes in two strengths, 40-bit and 128-bit, which refers to the length of the session key generated by every encrypted transaction. The longer the key, the more difficult it is to break the encryption code. Most browsers support 40-bit SSL sessions, and the latest browsers enable users to encrypt transactions in 128-bit sessions. Digital Certificates (Secure Server IDs) By using a digital certificate, the information that is being sent cannot be intercepted or decrypted by anyone other than the intended recipient. Digital certificates work in conjunction with the SSL technology that is a standard part of most Web server and Web browser packages. When you obtain and install a digital certificate, you enable the use of SSL at your Web site. When a browser connects to a site with a digital certificate, the browser automatically uses the certificate to verify that it is doing business with a legitimate site. The browser and the server then use the public key contained within the certificate to encrypt all information that passes between them. Certificate Authority (CA) This component is responsible for issuing, revoking, renewing, and providing directories of digital certificates. CAs must take steps to establish the identity of the people or organizations to which they issue IDs. Once the CA establishes an organization's identity, it issues a certificate that contains the organization's public key and signs it with the CA's private key. For more information, see Private and Public Keys in this document. Firewall Configuration Providers The digital certificate enrollment requires that you can make both HTTP and HTTPS connections. NOTE: SSL imposes some performance overhead. Therefore, most server software applications allow you to apply SSL selectively to Web pages that require encryption, such as payment information pages. For example, there is no benefit from applying SSL to general information pages. Verisign, Inc., of Mountain View, California, is the leading provider of digital certificate solutions used by enterprises, Web sites, and consumers to conduct secure communications and transactions over the Internet and private networks. VeriSign is the world's leading CA, having issued over 3,000,000 Digital IDs to individuals for use in identifying themselves on the Internet. VeriSign has also issued more than 75,000 IDs for use on servers, which enable people to conduct secure and authenticated e-commerce and other forms of communication with those servers. The Public Key Infrastructure that VeriSign has helped establish for the Internet will secure billions of dollars in transactions this year. Thawte is another leading CA and is a subsidiary of Verisign. Cost of VeriSign Services and Products For complete VeriSign pricing details, visit: For complete Thawte pricing details, visit: 7 Authorize.Net

12 Encryption Session Keys Standard practice enables 128-bit SSL encryption with domestic-version Microsoft and Netscape browsers and industry 40-bit SSL with export-version browsers. U.S. encryption laws stipulate that browser software will usually only enable SSL connections at 56-bit encryption. However, if the Web server presents a strong encryption certificate, the browser will connect at 128-bit encryption. In the complex world of encryption technology, security levels increase with the bit count. A large company with computer equipment worth $1 million can crack a weakly encrypted message within hours. By contrast, a message encrypted with a 128-bit key is considered completely impenetrable by any organization or government using today's technology. The 128-bit or 40-bit connection refers to the session key. This is a symmetric key created by the browser when it connects to the server that is used to encrypt and decrypt data (transmitted to and from the server) after the initial browser/server handshake. If your server supports full strength sessions and the browser connecting to your site supports 128-bit, then a 128-bit session key (128-bit connection) will be created and used. Browsers that have been exported from the U.S. are limited to creating 40-bit session keys. Browsers that have been distributed within the U.S. or manufactured by companies outside of the U.S. can create 128-bit session keys and thus connect to similarly manufactured and distributed servers in full strength cryptography. Private and Public Keys Digital certificate technology employs advanced public-key cryptography, Public Key Infrastructure (PKI). In public key cryptography, an individual or organization has two complimentary keys, a public key, and a private key. Any information encrypted using the private key can only be decrypted using the public key. Conversely, any information encrypted using the public key can only be decrypted using the private key. Rather than using the same key to both encrypt and decrypt data, a digital certificate uses a matched pair of keys that uniquely complement each another. When a key pair is generated for the school, the private key is installed on their server and nobody else has access to it. Their matching public key, in contrast, is freely distributed as part of their digital certificate. They can share it with anyone and even publish it in directories. Customers or correspondents who want to communicate with the school privately can use the public key in the school's digital certificate to encrypt information before sending it to them. Only the school can decrypt the information, because only they have the private key. The digital certificate contains the school's name and identifying information and their public key. It tells students and correspondents that the public key belongs to the school. Refer to Appendix D for answers to some commonly asked questions regarding security. Authorize.Net 8

13 EXCERPTS OF AUTHORIZE.NET DOCUMENTATION Introduction Information Included in This Section The following excerpts were extracted from Authorize.Net documents Advanced Integration Method (AIM) Implementation Guide, which is found on their Web site, They have been included here to help you better understand the approach to implementing the online transaction process using Authorize.Net s AIM Application Program Interface (API). All of the necessary coding is in place within the Jenzabar CX Web products. Note: Where applicable and for your convenience, comments regarding the specifics of your usage of Authorize.Net with Jenzabar CX are included throughout this section. Purpose of Included Documentation User institutions can use the information contained in this section to complete the following tasks so they can use Authorize.Net: Obtain a merchant account Secure the Web server with SSL Define macros that are specific to the institution s Web server Define macros for posting to a General Ledger account 9 Authorize.Net

14 Implementing Real Time Processing Introduction To implement real-time processing, you must: Obtain a merchant account Gain a secure server connection Define macros Test the connection Verify access to Virtual Terminal Obtaining a Merchant Account A merchant account allows you to accept major credit cards, electronic checks, and ATM/Debit cards. The bank deposits the daily credit sales (minus applicable fees) into your institution s account. All funds are directly transferred to the checking account of your choice. A merchant account is a contract relationship between a merchant (the school) and a merchant account provider (a processing bank or independent sales organization such as Jenzabar) for the clearing and settlement of credit card transactions. A merchant account is not a bank account. It does not carry a balance, and you do not deposit or withdraw from it. A merchant account enables your school to process credit card transactions through a payment gateway (i.e., a processing center such as Authorize.Net), the route used to quickly transfer card information for processing and verifying online in real-time (usually within a matter of seconds). Authorize.Net's services also have the ability to process non real-time manual transactions. Detailed information is included with your merchant account. Obtain a merchant account from Jenzabar by contacting your Customer Care Account Executive for an application and merchant account setup information. Gaining a Secure Server Connection You must obtain an SSL-enabled link to the campus Web server. It will encrypt confidential ordering data through the use of digital certificates. Defining Macros Linking your school's campus Web online payment forms with the AIM requires you to set the value of the macro WEB_ENABLE_ONLINE_PAYMENT to Y. This macro is located in the file macros/custom/web. If a student has an outstanding balance from the Course and Fee Statement, a button appears. When students click the Make an Online Payment button, they can complete the forms that send information to the Authorize.Net site. An additional macro exists for online check payments. Testing the Connection Institutions can check the status of transactions or run reports on past activity by going to the Merchant Menu Login and logging on to their own password-protected area. To view this area in Test Mode, please contact the Authorize.Net sales department for a demo login and password. Verifying Access to Virtual Terminal From the Merchant menu, a school can also access the Virtual Terminal to enter payment information manually (for users who either call in a payment or pay in person with their credit card). Virtual Terminal is a manual processing system that works from a browser connected to Authorize.Net 10

15 the Internet. Virtual Terminal is included with Authorize.Net's services. These tools are available only through Authorize.Net. 11 Authorize.Net

16 Basic Integration Concepts Introduction To implement AIM, a script must exist that: Securely obtains all the information needed to process a transaction. Initiates a secure HTTPS form POST from the server to Note: Authorize.Net will only accept transactions on port 443. Receives the response from the gateway and processes the response to display the appropriate result to the end user. Minimum Requirements for AIM The following is the minimum set of NAME/VALUE pairs that should be submitted to the gateway when using AIM for a credit card transaction. Values shown within caret marks (< >) must be replaced with values specific to your institution or to the transaction. Field name x_version 3.1 x_delim_data x_relay_response x_login x_tran_key x_amount x_card_num x_exp_date x_type True False <Your Login ID> Field value <Transaction key obtained from the Merchant Interface> <Amount of purchase, including tax> <Customer s card number> <Customer s card expiration date> <Type of transaction (i.e., AUTH_CAPTURE, AUTH_ONLY, CAPTURE_ONLY, CREDIT, VOID, PRIOR_AUTH_CAPTURE)> Authorize.Net 12

17 Testing the Authorize.Net Connection Introduction Test mode is a special mode of interacting with the system that is useful during the initial setup phase, when you may want to test your setup without processing live card data. Setting Up Test Mode To set an account to Test mode: 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 you are submitting transactions from a Web site or through the Virtual Terminal. If you upload a file of transactions for offline processing, the gateway will reject the file. Running a Test Transaction Outside of Test Mode You can run a test transaction even if Test mode has been turned off 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. Value passed in x_test_request Configuration in Merchant Interface Gateway behavior TRUE ON Transaction processed as test FALSE ON Transaction processed as test TRUE OFF Transaction processed as test FALSE OFF Transaction processed as a live transaction 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. Test card number Card type Test card number Card type 13 Authorize.Net

18 American Express Discover MasterCard Visa Testing Error Conditions There is also a test credit card number that can be used to generate errors. Its sole purpose is to test error conditions, 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 (a four and twelve twos). The system will return a 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 and an amount of Authorize.Net 14

19 APPENDIX A JENZABAR CX FILES USED FOR AUTHORIZE.NET Scripts and Descriptions Included Scripts The following scripts are included for Authorize.Net in Jenzabar CX Web products: Directory Modules/common/lib web/cgi/student/secure web/html/includes Script names Payform.pm, Paycfm.pm, Payspost.pm stucform.cgi, stuccfm.cgi, stucpost.cgi Ccnumval.js, isready.js Script Descriptions File: stucform.cgi The stucform.cgi module is called by the stubill.cgi module. This module uses Payform.pm to generate the initial entry form. Default values for the current ID are placed in the form for submission. The ccnumval.js and isready.js JavaScript modules are used by the generated html to validate the form entries. File: stuccfm.cgi The stuccfm.cgi module is called by the stucform.cgi module. This module uses Paycfm.pm to generate the confirmation page that allows the user to review all the entries for correctness. The majority of the hidden form fields are declared here. The hidden form fields are used by Authorize.Net to process the transaction. The complete listing of Authorize.Net fields is in Appendix B. File: stucpost.cgi The stucpost.cgi module is called by the stuccfm.cgi module. This module uses Paypost.pm to send HTTPS post to Authorize.net and get a response from Authorize.net. If the transaction is a success, then the transaction is posted to the GL via the filepost process. Macros can be changed in macros/custom/web to indicate which accounts are to be used for the filepost process. 15 Authorize.Net

20

21 APPENDIX B FUNCTIONAL REFERENCE AND RESULT FIELDS Standard Transaction Submission API for AIM 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. VALUE contains the content of the field. 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. Field Required Value Max Length x_login Required Varies by merchant x_tran_key Required Varies by merchant x_version Optional If no value is specified, the value located in the Transaction Version settings within the Merchant Interface will be used. Description 20 Pass the Login ID used to access the Merchant Interface. 16 Pass the transaction key obtained from the Merchant Interface. 2.5, 3.0, Indicates to the system the set of fields that will be included in the response: 3.0 is the standard version 3.1 allows the merchant to utilize the Card feature 17 Authorize.Net

22 Field Required Value Max Length x_test_reques t Gateway Response Configuration Description Optional TRUE,FALSE 5 Indicates whether the transaction should be processed as a test transaction. The following fields determine how a transaction response will be returned once a transaction is submitted to the system. The merchant has the option of sending in the configuration of the response on a per-transaction basis or configuring the response through the Merchant Interface. Submitting values in these fields on a per-transaction basis overrides the configuration in the Merchant Interface for that transaction. It is recommended that the values be set in the Merchant Interface for these fields and not submitted on a per-transaction basis. Field Required Value Max Length Description x_delim_data Required TRUE 5 In order to receive a delimited response from the gateway, this field has to be submitted with a value of TRUE or the merchant has to configure a delimited response through the Merchant Interface x_delim_char Optional Any valid character x_encap_char Optional Any valid character 1 Character that will be used to separate fields in the transaction response. The system will use the character passed in this field or the value stored in the Merchant Interface if no value is passed. If this field is passed, and the value is null, it will override the value stored in the Merchant Interface and there will be no delimiting character in the transaction response. 1 Character that will be used to encapsulate the fields in the transaction response. The system will use the character passed in this field or the Authorize.Net 18

23 Field Required Value Max Length x_relay_respons e Customer Name and Billing Address Description value stored in the Merchant Interface if no value is passed. If this field is passed, and the value is null, it will override the value stored in the Merchant Interface and there will be no encapsulation character in the transaction response. Required FALSE N/A Indicates whether a relay response is desired. As all AIM transactions are direct response, a value of FALSE is required. The customer billing address fields listed below contain information on the customer billing address associated with each transaction. Field Required Value Max Length Description x_first_name Optional Any string 50 Contains the first name of the customer associated with the billing address for the transaction. x_last_name Optional Any string 50 Contains the last name of the customer associated with the billing address for the transaction. x_company Optional Any string 50 Contains the company name associated with the billing address for the transaction. x_address Optional Any string 60 Contains the address of the customer associated with the billing address for the transaction. x_city Optional Any string 40 Contains the city of the customer associated with the billing address for the transaction. x_state Optional Any valid two- 40 Contains the state of 19 Authorize.Net

24 Field Required Value Max Length digit state code If passed, the value of full state will be verified name Description the customer associated with the billing address for the transaction. x_zip Optional Any string 20 Contains the zip of the customer associated with the billing address for the transaction. x_country Optional If passed, the value will be verified Any valid twodigit country code or full country name (spelled in English) x_phone Optional Any string Recommended format is (123) x_fax Optional Any string Additional Customer Data Recommended format is (123) Contains the country of the customer associated with the billing address for the transaction. 25 Contains the phone number of the customer associated with the billing address for the transaction. 25 Contains the fax number of the customer associated with the billing address for the transaction. Merchants may provide additional customer information with a transaction, based on their respective requirements. Field Required Value Max Length Description x_cust_id Optional Any string 20 Unique identifier to represent the customer associated with the transaction. x_customer_ip Optional Required format is x_customer_ tax_id Optional If this value is not passed, it will default to digits/numbers only 15 IP address of the customer initiating the transaction. 9 Tax ID or SSN of the customer initiation the transaction. Authorize.Net 20

25 Settings The following fields describe how and when s will be sent when transactions are processed by the system. Field Required Value Max Length x_ Optional Any valid address x_ _ customer x_merchant_ Invoice Information Optional Optional TRUE, FALSE If no value is submitted, system will default to the value configured in the Merchant Interface Any valid address Description 255 address to which the customer s copy of the confirmation is sent No will be sent to the customer if the e- mail address does not meet standard format checks. 5 Indicates whether a confirmation should be sent to the customer address to which the merchant s copy of the customer confirmation should be sent. If a value is submitted, an will be sent to this address as well as the address(es) configured in the Merchant Interface. Based on their respective requirements, merchants may submit invoice information with a transaction. Two invoice fields are provided in the gateway API. Field Required Value Max Length x_invoice_ num Description Optional Any string 20 Merchant-assigned invoice number. x_description Optional Any string 255 Description of the transaction. 21 Authorize.Net

26 Customer Shipping Address The following fields describe the customer shipping information that may be submitted with each transaction. Field Required Value Max Length x_ship_to_ first_name x_ship_to last_name x_ship_to_ company x_ship_to_ address x_ship_to_ city x_ship_to_ state x_ship_to_ zip x_ship_to_ country Transaction Data Description Optional Any string 50 Contains the customer shipping first name. Optional Any string 50 Contains the customer shipping last name. Optional Any string 50 Contains the customer shipping company. Optional Any string 60 Contains the customer shipping address. Optional Any string 40 Contains the customer shipping city. Optional If passed, the value will be verified Any valid twodigit state code or full state name 40 Contains the customer shipping state. Optional Any string 20 Contains the customer shipping zip. Optional If passed, the value will be verified. Any valid twodigit country code or full country name (spelled in English) 60 Contains the customer shipping country. The following fields contain transaction-specific information such as amount, payment method, and transaction type. Field Required Value Max Lengt h Description x_amount Required Any amount 15 Total value to be charged or credited including tax. x_currency_ code Optional Valid currency code 3 Currency of the transaction amount. If left blank, this value will default to the Authorize.Net 22

27 Field Required Value Max Lengt h Description value specified in the Merchant Interface. x_method Required CC, ECHECK N/A Indicates the method of payment for the transaction being sent to the system. If left blank, this value will default to CC. x_type Required AUTH_CAPTURE, AUTH_ONLY, CAPTURE_ONLY, CREDIT, VOID, PRIOR_AUTH_ CAPTURE x_recurring_ billing x_bank_aba_ code x_bank_acct_nu m x_bank_name x_bank_acct_ name N/A Indicates the type of transaction. If the value in the field does not match any of the values stated, the transaction will be rejected. If no value is submitted in this field, the gateway will process the transaction as AUTH_CAPTURE. Optional YES, NO 3 Indicates whether the transaction is a recurring billing transaction. Conditional Required if x_method = ECHECK Conditional Required if x_method = ECHECK Conditional Required if x_method = ECHECK Conditional Required if x_method = ECHECK Valid routing number CHECKING, SAVINGS 9 Routing number of a bank for echeck.net transactions. 8 Describes the type of bank account; if no value is provided, default is set to CHECKING. Valid bank name 50 Contains the name of the customer s financial institution. Name on the customer s bank account Is the customer s name as it appears on their 23 Authorize.Net

28 Field Required Value Max Lengt h x_echeck_ type x_card_num x_exp_date Conditional Required if x_method = ECHECK Conditional Required if x_method = CC Conditional Required if x_method = CC WEB Numeric credit card number MMYY, MM/YY, MM-YY, MMYYYY, MM/YYYY, MM- YYYY, YYYY-MM- DD, YYYY/MM/DD x_card_code Optional Valid CVV2, CVC2, or CID value x_trans_id x_auth_code x_authentication_ indicator Conditional Required if x_type = CREDIT, VOID, or PRIOR_AUTH_CAPTUR E Conditional Required if x_type = CAPTURE_ONLY Optional Required only for AUTH_ONLY and AUTH_CAPTURE transactions processed through cardholder authentication programs. When submitted with other transaction types, this value is ignored. Valid transaction ID Valid authorization code Valid ECI or UCAF indicator v alue (obtained by the merchant after the authentication process). Description bank statement. This indicates that the echeck payment request originated from a Web site. The system will default this value to WEB if no value is sent. 22 Contains the credit card number. N/A Contains the date on which the credit card expires. 4 Three- or four-digit number on the back of a credit card (on front for American Express). 10 ID of a transaction previously authorized by the gateway. 6 Authorization code for a previous transaction not authorized on the gateway that is being submitted for capture. N/A The electronic commerce indicator (ECI) value for a Visa transaction; or the universal cardholder authentication field indicator (UCAF) for a MasterCard Authorize.Net 24

29 Field Required Value Max Lengt h x_cardholder_ authentication_ value Optional Required only for AUTH_ONLY and AUTH_CAPTURE transactions processed through cardholder authentication programs. When submitted with other transaction types, this value is ignored. Valid CAVV, AVV, or UCAF value (obtained by the merchant after the authentication process). N/A Description transaction. The cardholder authentication verification value (CAVV) for a Visa transaction; or accountholder authentication field (UCAF) for a MasterCard transaction. This field is currently supported only through FDC Nashville and Vital. Level 2 Data The system supports Level 2 transaction data by providing the following fields as part of the transaction submission API. Field Required Value Max Length Description x_po_num Optional Any string 25 Contains the purchase order number. x_tax Optional Any valid amount 15 Contains the tax amount. x_tax_exempt Optional TRUE, FALSE 5 Indicates whether the transaction is taxexempt. x_freight Optional Any valid amount x_duty Optional Any valid amount 10 Contains the amount of freight charged. 10 Contains the amount charged for duty. 25 Authorize.Net

30 Gateway Response API Introduction This section describes the response returned by the gateway when a merchant server submits a transaction for processing. The response is a set of fields that gives merchants information about the status of a transaction. The fields will be comma-delimited by default or delimited by the character specified by the merchant. The merchant server can parse this data and determine the message to display to the customer. Fields in the Gateway Response The following table indicates the order of the fields returned in the AIM response from the gateway to the merchant server. Position in respons e Field name of value in response Description 1 Response Indicates the result of the transaction: 1 = Approved 2 = Declined 3 = Error 2 Response Subcode A code used by the system for internal transaction tracking. 3 Response Reason 4 Response Reason Text A code representing more details about the result of the transaction. Brief description of the result, which corresponds with the Response Reason. 5 Approval The six-digit alphanumeric authorization or approval code. 6 AVS Result Indicates the result of Address Verification System (AVS) checks: A = Address (Street) matches; ZIP does not B = Address information not provided for AVS check E = AVS error G = Non-U.S. Card Issuing Bank N = No match on Address (Street) or ZIP P = AVS not applicable for this transaction R = Retry - System unavailable or timed out S = Service not supported by issuer U = Address information is unavailable W = 9 digit ZIP matches, Address (Street) does not X = Address (Street) and 9 digit ZIP match Y = Address (Street) and 5 digit ZIP match Z = 5 digit ZIP matches, Address (Street) does not Authorize.Net 26

31 Position in respons e Field name of value in response Description 7 Transaction ID This number identifies the transaction in the system and can be used to submit a modification of this transaction at a later time, such as voiding, crediting, or capturing the transaction. 8 Invoice Number Echoed from form input value for x_invoice_num. 9 Description Echoed from form input value for x_description. 10 Amount Echoed from form input value for x_amount. 11 Method Echoed from form input value for x_method. 12 Transaction Type Echoed from form input value for x_type. 13 Customer ID Echoed from form input value for x_cust_id. 14 Cardholder First Name 15 Cardholder Last Name Echoed from form input value for x_first_name. Echoed from form input value for x_last_name. 16 Company Echoed from form input value for x_company. 17 Billing Address Echoed from form input value for x_address. 18 City Echoed from form input value for x_city. 19 State Echoed from form input value for x_state. 20 Zip Echoed from form input value for x_zip. 21 Country Echoed from form input value for x_country. 22 Phone Echoed from form input value for x_phone. 23 Fax Echoed from form input value for x_fax. 24 Echoed from form input value for x_ . 25 Ship to First Name Echoed from form input value for x_ship_to_first_name. 26 Ship to Last Name Echoed from form input value for x_ship_to_last_name. 27 Ship to Company Echoed from form input value for x_ship_to_company. 28 Ship to Address Echoed from form input value for x_ship_to_address. 29 Ship to City Echoed from form input value for x_ship_to_city. 30 Ship to State Echoed from form input value for x_ship_to_state. 31 Ship to Zip Echoed from form input value for x_ship_to_zip. 32 Ship to Country Echoed from form input value for x_ship_to_country. 33 Tax Amount Echoed from form input value for x_tax. 34 Duty Amount Echoed from form input value for x_duty. 35 Freight Amount Echoed from form input value for x_freight. 36 Tax Exempt Flag Echoed from form input value for x_tax_exempt. 27 Authorize.Net

32 Position in respons e Field name of value in response Description 37 PO Number Echoed from form input value for x_po_num. 38 MD5 Hash System-generated hash that may be validated by the merchant to authenticate a transaction response received from the gateway. 39 Card (CVV2/CVC2/CID) Response 40 Cardholder Authentication Verification Value (CAVV) Response Indicates the results of Card verification: M = Match N = No Match P = Not Processed S = Should have been present U = Issuer unable to process request Indicates the results of cardholder authentication verification: Blank or not present - CAVV not validated 0 = CAVV not validated because erroneous data was submitted 1 = CAVV failed validation 2 = CAVV passed validation 3 = CAVV validation could not be performed; issuer attempt incomplete 4 = CAVV validation could not be performed; issuer system error 5 = Reserved for future use 6 = Reserved for future use Reserved for future use. 7 = CAVV attempt - failed validation - issuer available (U.S.- issued card/non-u.s. acquirer) 8 = CAVV attempt - passed validation - issuer available (U.S.-issued card/non-u.s. acquirer) 9 = CAVV attempt - failed validation - issuer unavailable (U.S.-issued card/non-u.s. acquirer) A = CAVV attempt - passed validation - issuer unavailable (U.S.-issued card/non-u.s. acquirer) B = CAVV attempt - passed validation, information only, no liability shift 69 - Echo of merchant-defined fields. Authorize.Net 28

33 APPENDIX C RESPONSE CODES Description of Response Fields Introduction The three status fields in the transaction response are defined as follows: Response Indicates the overall status of the transaction with possible values of approval, decline, or error. Response Reason Gives merchants more information about the transaction status. Response Reason Text A text string that will give more detail on why the transaction resulted in a specific response code. This field is a test 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 if they need to programmatically know these results; the Response Reason will always represent these meanings, even if the text descriptions change. Response s Valid Response s are: Response Description 1 This transaction has been approved. 2 This transaction has been 3 There has been an error processing this transaction. Response Reason s and Response Reason Text Possible Response Reason s and Response Reason Text are: Response Response Reason Response Reason Text 1 1 This transaction has been approved. 2 2 This transaction has been 2 3 This transaction has been 2 4 This transaction has been Notes The code returned from the processor indicating that the card used needs to be picked up. 3 5 A valid amount is required. The value submitted in the amount field did not pass validation for a number. 3 6 The credit card number is invalid. 29 Authorize.Net