Card-Present Transactions

Transcription

1 Card-Present Transactions Implementation Guide September 2012 Authorize.Net Developer Support Authorize.Net LLC Ver.2.0

2 Authorize.Net LLC ( Authorize.Net ) has made efforts to ensure the accuracy and completeness of the information in this document. However, Authorize.Net disclaims all representations, warranties and conditions, whether express or implied, arising by statute, operation of law, usage of trade, course of dealing or otherwise, with respect to the information contained herein. Authorize.Net assumes no liability to any party for any loss or damage, whether direct, indirect, incidental, consequential, special or exemplary, with respect to (a) the information; and/or (b) the evaluation, application or use of any product or service described herein. Authorize.Net disclaims any and all representation that its products or services do not infringe upon any existing or future intellectual property rights. Authorize.Net owns and retains all right, title and interest in and to the Authorize.Net intellectual property, including without limitation, its patents, marks, copyrights and technology associated with the Authorize.Net services. No title or ownership of any of the foregoing is granted or otherwise transferred hereunder. Authorize.Net reserves the right to make changes to any information herein without further notice. Authorize.Net Trademarks Advanced Fraud Detection Suite Authorize.Net Authorize.Net Your Gateway to IP Transactions Authorize.Net Verified Merchant Seal Automated Recurring Billing echeck.net FraudScreen.Net 2

3 Contents CONTENTS Revision History 6 Chapter 1 Introduction 7 Connection Methods 7 Advanced Integration Method (AIM) 7 Customer and Developer Support 8 Chapter 2 Integration Settings 10 Features of the Gateway 10 Address Verification System 10 Credit Card Identification Code (CVV2/CVC2/CID) 11 What is the Advanced Integration Method (AIM)? 13 How Does AIM Work? 13 What is Required to Implement AIM? 13 The AIM Application Program Interface (API) 13 Software Development Kits (SDK) 14 Chapter 3 Submitting Transactions 15 Minimum Requirements 15 Credit Card Transaction Processing 16 Credit Card Transaction Types 17 Partial Authorization Transactions 19 Chapter 4 Standard CP Transaction Submission API for AIM 21 Merchant Account Information 21 Gateway Response Configuration 23 Customer Name and Billing Address 24 Additional Customer Data 25 Invoice Information 25 Card-Present Transactions Implementation Guide September

4 Contents Itemized Order Information 25 Customer Shipping Address 27 Transaction Data 27 Track1 and Track2 Data 27 Level 2 Data 32 Chapter 5 Gateway Response API 33 Delimited Response 33 Fields in the Gateway Response 34 Response for Duplicate Transactions 35 XML Response 36 Response Code Details 38 Description of Response Fields 38 Response Codes 38 Response Reason Codes & Response Reason Text 39 HTTP Error Codes & Reason Text 49 Appendix A Submitting Test Transactions to the System 50 Test Mode 50 Running a Test Transaction 50 Testing to Generate Specific Transaction Results 51 Appendix B Response Examples 52 Sample Delimited Responses 52 Approval Response 52 Decline Response 52 Error Response 52 Sample XML Responses 53 Approval Response 53 Decline Response 53 Error Response 54 Appendix C The Transaction Key 55 What is the Transaction Key? 55 How do I Obtain the Transaction Key? 55 Card-Present Transactions Implementation Guide September

5 Contents Appendix D The Secret Question and Answer 56 What is the Secret Question and Answer? 56 How do I Set my Secret Question and Answer? 56 Appendix E Track Data 57 Track 1 Data 58 Track 2 Data 59 Appendix F Currency Codes 60 Card-Present Transactions Implementation Guide September

6 Revision History REVISIONS Release September 2012 May 2011 November 2010 October 2010 June 2010 June 2009 Changes This revision contains only editorial changes and no technical updates. Format update Added reference to enabling Transaction Details API Corrected table of response fields to allow for up to 26 fields Partial Authorization implementation Format of guide updated Additions to the Response Code list Card-Present Transactions Implementation Guide September

7 Introduction CHAPTER 1 Welcome to the Authorize.Net Card Present (CP) Implementation Guide. This guide describes how card present transactions can be submitted to the gateway for real-time processing. Connection Methods You can submit transactions to Authorize.Net in the following ways: Automatically through a website or custom application connected to Authorize.Net using Advanced Integration Method (AIM). Ready-to-go point-of-sale (POS) solutions include our own Virtual Point of Sale as well as numerous third party card swipe terminals, software, self-service kiosks, and mobile devices. A list of our partners Certified POS Solutions can be found in our Certified Solution Directory. It s a good idea to identify how your business plans to submit transactions so that you and/ or your Web developer can properly integrate your payment gateway account to support your business processes. By communicating your transaction processing practices or requirements, you can help your Web developer integrate your website or custom application more quickly. Advanced Integration Method (AIM) AIM is a customizable payment processing solution that gives the merchant control over all the steps in processing a transaction, including: Collecting customer payment information through a custom application Generating a receipt to the customer Secure transmission to the payment gateway for transaction processing Secure storage of cardholder information And more, depending on the merchant s business requirements Card-Present Transactions Implementation Guide September

8 Chapter 1 Introduction The security of an AIM transaction is assured through a 128-bit Secure Sockets Layer (SSL) connection between the merchant s Web server and the Authorize.Net Payment Gateway. Payment gateways act as a bridge between a merchant's point-of-purchase software and the financial institutions that process payment transactions. Payment data is submitted by the point-of-purchase software using the Internet 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 a transaction can be accepted. To authorize a given credit card transaction, the gateway transmits the payment information to the appropriate financial institution for validation, then returns the response (approved or declined) from the institution to the merchant s software. The Payment Gateway supports real-time and offline requests for credit card authorization. Note For CP transactions, the merchant and the shopper are in the same physical location. The merchant has a card reader (or swipe terminal ) and receipt printer at the point of purchase. The card reader device reads the magnetic stripe on the back of the card and transmits the encoded information to the gateway. Once a transaction is approved, the merchant can print a receipt for obtaining the cardholder s signature. Customer and Developer Support There are several resources available to help you and your Web developer successfully integrate a merchant website or other business application to the Authorize.Net Payment Gateway. Refer to the Merchant Interface Online Help Files. Log on to the Merchant Interface, click on the feature for which you need help from the main menu or Settings menu, and then click the Help link in the top right corner of the page. The Authorize.net Knowledge Base provides comprehensive answers to virtually any customer support question, as well as useful links to demos, help files and information on contacting us. We strongly recommend using the Knowledge Base anytime you need help. Software Development Kits (SDKs) are available in several popular languages from our developer website. Customer Support is available to help you with questions regarding integration settings in the Merchant Interface. You can contact Customer Support by ing support@authorize.net, or using chat by clicking Live Help in the top right corner of Card-Present Transactions Implementation Guide September

9 Chapter 1 Introduction the Merchant Interface. Customer Support hours are 5:00 AM 5:00 PM Pacific time, Monday through Friday. The Developer Center provides Web developers with test accounts, sample code, FAQs, and troubleshooting tools. If you or your developer can t find what you need in the Developer Center, our Developer support team is available to answer your questions by at developer@authorize.net. (Please note that our Developer support team can only assist with support requests specific to the Authorize.Net application programming interface (API) and/or services.) If you have any suggestions about how we can improve or correct this guide, please documentation@authorize.net. Card-Present Transactions Implementation Guide September

10 Integration Settings CHAPTER 2 Most integration settings in the Merchant Interface apply to both Server Integration Method (SIM) and Advanced Integration Method (AIM). However, some are specific to the connection method you are using. This section details all the settings you should be aware of in the Merchant Interface that will help you achieve and maintain a strong connection to the payment gateway. Features of the Gateway The gateway supports the following features in an effort to reduce the merchant s chargeback liability. Address Verification System Bankcard processors implemented the Address Verification Service (AVS) to aid merchants in the detection of suspicious transaction activity. The payment processing network compares the billing address provided in the transaction with the cardholder s address on file at the credit card issuing bank. The processing network returns an AVS response code that indicates the results of this comparison to the payment gateway. You can configure your account to reject certain transactions based on the AVS code returned. For example, the AVS code A indicates that the street address matched, but the first five digits of the ZIP Code did not. Note In most cases, AVS is not required for a card-present transaction since the cardholder is present at the point of purchase. However, in cases where the magnetic stripe reader cannot read the track data, some processors specify that AVS data be sent with the manually keyed-in card information. The following result codes are possible. AVS Code Description A Address (Street) matches, ZIP does not B Address information not provided for AVS check Card-Present Transactions Implementation Guide September

11 Chapter 2 Integration Settings AVS Code Description 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 Step 1 Step 2 Step 3 Step 4 Step 5 To configure transaction rejection settings based on the AVS response code: Log on to the Merchant Interface at Select Settings under Account in the main menu on the left Click Address Verification Service in the Security Settings section Click to select the check box(es) next to the AVS codes for which the payment gateway should reject transactions Click Submit Transactions are processed against your rejection criteria immediately. Note In order to use the AVS filter, you need to require the billing address and ZIP code fields when collecting payment information from your customers. Please communicate these requirements to your Web developer. 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. Card-Present Transactions Implementation Guide September

12 Chapter 2 Integration Settings Figure 1 Finding the card code on a credit card You can choose to collect this information from the customer and submit the data to the payment gateway, as another method for authenticating credit card transactions submitted through your account. The payment gateway will pass this information to the credit card issuer along with the credit card number. The credit card issuer will determine if the value matches the value on file for the customer s credit card and return a code to the payment gateway indicating whether the code matched, in addition to indicating whether the card was authorized. You can configure the payment gateway to reject transactions based on the code returned. Card Code Response M N P S U Description Card Code matched Card Code does not match Card Code was not processed Card Code should be on card but was not indicated Issuer was not certified for Card Code Note In most cases, Card Codes are not required for a card-present transaction since the cardholder is present at the point of purchase. However, in cases where the magnetic stripe reader cannot read the track data, some processors specify that Card Code data be sent with the manually keyed-in card information. Card-Present Transactions Implementation Guide September

13 Chapter 2 Integration Settings What is the Advanced Integration Method (AIM)? Software that resides on a merchant s POS or other IP terminal can submit transactions to the gateway using Advanced Integration Method (AIM). AIM allows a merchant s server to automatically and securely connect to the Payment Gateway to submit transaction data. This method requires merchants to be able to initiate and manage secure Internet connections. How Does AIM Work? When using AIM, transactions flow in the following way: 1 The Merchant s server initiates a secure connection to the Payment Gateway and then initiates an HTTPS POST of the transaction data to the gateway server 2 The Payment Gateway receives and processes the transaction data 3 The Payment Gateway then generates and submits the transaction response to the Merchant s server 4 The Merchant s server receives and processes the response 5 Finally, the Merchant prints a receipt and obtains the cardholder s signature to complete the transaction What is Required to Implement AIM? Merchants must be able to perform the following functions in order to submit transactions to the gateway using AIM: Have a secure socket layer (SSL) digital certificate Provide both server and client side encryption Develop scripts on a Web server for the integration to the gateway (for example, for submitting transaction data and receiving system responses) The AIM Application Program Interface (API) A defined API is provided for submitting transactions to the Payment Gateway. An API is also provided for responses to transactions that are submitted to the gateway. These APIs are discussed in detail in this document. The merchant uses the Merchant Interface to configure the transaction response from the gateway. (The Merchant Interface is a tool through which merchants can manage their accounts and their transaction activity. A user 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.) Card-Present Transactions Implementation Guide September

14 Chapter 2 Integration Settings Software Development Kits (SDK) An SDK is available to help you set up an application in PHP, Ruby, Java, and C#. You can download this SDK from Card-Present Transactions Implementation Guide September

15 Submitting Transactions CHAPTER 3 The payment gateway supports several credit card transaction types for transactions submitted by AIM. To implement AIM for a merchant s business, a developer would design a script that can do the following: Securely obtain all of the information needed to process a transaction Initiate a secure HTTPS form POST from the merchant s server to Receive the response from the gateway and process the response to display the appropriate result to the end user The 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. Minimum Requirements The following table contains the minimum set of NAME/VALUE pairs that must be submitted to the gateway when using AIM. The data fields are name/value pairs with the syntax of: x_name_of_field=value of field&. Field Name Field Value Notes x_cpversion 1.0 x_login x_market_type x_device_type x_amount API Login ID for the payment gateway account Your market type Your device type Amount of purchase inclusive of tax Card-Present Transactions Implementation Guide September

16 Chapter 3 Submitting Transactions Field Name Field Value Notes x_split_ tender_id The payment gatewayassigned ID that links the current authorization request to the original authorization request. This value applies to partial authorization transactions only, and is returned in the reply message from the original authorization request. x_tran_key Your transaction key See Appendix C, The Transaction Key for more information on the transaction key. x_track1 OR Track 1 data from credit card Must be supplied if neither x_ track2 nor x_card_num and x_ exp_date data is submitted. x_track2 OR Track 2 data from credit card Must be supplied if neither x_ track1 nor x_card_num and x_ exp_date data is submitted. x_card_num AND Customer's card number Must be supplied if neither x_ track1 nor x_track2 data is submitted. x_exp_date Customer's card expiration date Must be supplied if neither x_ track1 nor x_track2 data is submitted. For security reasons, use only port 443 for AIM information transfers. Note Credit Card Transaction Processing There are two steps to credit card transaction processing: 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. Settlement, also referred to as Capture, is the process by which 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 initiates the settlement step. As part of the settlement process, the gateway will send a settlement Card-Present Transactions Implementation Guide September

17 Chapter 3 Submitting Transactions request to the financial institution to request transfer of funds. The gateway does not control the time frame within which funds are actually transferred. 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 (only users with the appropriate permissions can access this setting): Step 1 Step 2 Step 3 Step 4 Step 5 Log on to the Merchant Interface Select Settings Select Transaction Cut-Off Time from the General section Using the drop-down boxes, select the desired cut-off time 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. Transaction Type AUTH_CAPTURE AUTH_ONLY Description Transactions of this type are sent for authorization. The transaction is automatically picked up for settlement if approved. This is the default transaction type in the gateway. If no type is indicated when submitting transactions to the gateway, the gateway will assume that the transaction is of the type AUTH_CAPTURE. If the approved amount is less than the requested amount and the transaction qualifies as a partial authorization transaction, see the special conditions described in "Credit Card Transaction Processing," page 16. Transactions of this type are submitted if the merchant wishes to validate the credit card for the amount of the goods sold. If the merchant does not have goods in stock or wishes to review orders before shipping the goods, this transaction type should be submitted. The gateway will send this type of transaction to the financial institution for approval. However this transaction will not be sent for settlement. If the merchant does not act on the transaction within 30 days, the transaction will no longer be available for capture. Card-Present Transactions Implementation Guide September

18 Chapter 3 Submitting Transactions Transaction Type PRIOR_AUTH_CAPTURE CREDIT Description This transaction is used to request settlement for a transaction that was previously submitted as an AUTH_ONLY. The gateway will accept this transaction and initiate settlement if the following conditions are met: The transaction is submitted with the ID of the original authorization-only transaction which needs to be settled. The transaction ID is valid and the system has a record of the original authorization-only transaction being submitted. The original transaction referred to is not already settled or expired or errored. The amount being requested for settlement in this transaction is less than or equal to the original authorized amount. If no amount is submitted in this transaction, the gateway will initiate settlement for the amount of the originally authorized transaction. Note If extended line item, tax, freight, and/or duty information was submitted with the original transaction, adjusted information can be submitted in the event that the transaction amount changed. If no adjusted line item, tax, freight, and/or duty information is submitted, the information submitted with the original transaction will apply. This transaction is also referred to as a Refund and indicates to the gateway that money should flow from the merchant to the customer. The gateway will accept a credit or a refund request if the transaction submitted meets the following conditions: The transaction is submitted with the ID of the original transaction against which the credit is being issued (x_ref_trans_id). The gateway has a record of the original transaction. The original transaction has been settled. The sum of the amount submitted in the Credit transaction and all credits submitted against the original transaction is less than the original transaction amount. The full or last four digits of the credit card number submitted with the credit transaction match the full or last four digits of the credit card number used in the original transaction. The transaction is submitted within 120 days of the settlement date of the original transaction. A transaction key is required to submit a credit to the system (i.e., x_tran_key should have a valid value when a CREDIT transaction is submitted). For details about how to submit CREDIT transactions to the Payment Gateway, please see the Issuing Credits Guide. Card-Present Transactions Implementation Guide September

19 Chapter 3 Submitting Transactions Transaction Type CAPTURE_ONLY VOID Description This is a request to settle a transaction that was not submitted for authorization through the payment gateway. The gateway will accept this transaction if an authorization code is submitted. x_auth_code is a required field for CAPTURE_ ONLY type transactions. This transaction is an action on a previous transaction and is used to cancel the previous transaction and ensure it does not get sent for settlement. It can be done on any type of transaction (i.e., CREDIT, AUTH_CAPTURE, CAPTURE_ONLY, and AUTH_ONLY). The transaction is accepted by the gateway if the following conditions are met: The transaction is submitted with the ID of the transaction that has to be voided. The gateway has a record of the transaction referenced by the ID. The transaction has not been sent for settlement. Partial Authorization Transactions A split tender order is one in which two or more transactions are used to cover the total amount of the order. The merchant must indicate that they are able to handle the extra processing either by selecting the Partial Authorization option in the Account settings of the Merchant Interface, or by sending x_allow_partial_auth=true with an individual transaction. Without this flag, the transaction would be handled as any other, and would be either fully authorized or declined due to lack of funds on the card. When the first transaction is successfully approved for a partial amount of the total order, a split tender ID is generated and returned to the merchant in the response. This ID must be passed back with each of the remaining transactions of the group, using x_split_ tender_id=<value>. If you include both a split tender ID and a transaction ID on the same request, an error results. If successfully authorized, all transactions in the group are held until the final transaction of the group is successfully authorized, unless the merchant has indicated either by input parameter or default configuration that they do not want these transactions to be held. If the merchant needs to release the group of transactions before the final one is approved (if the balance is paid by cash, for example), send a prior auth capture request and include the split tender ID instead of a transaction ID. If the merchant needs to void the group before completion, a void request should be sent, using the split tender ID instead of a transaction ID. The following rules apply to partial authorization transactions: The merchant can choose to accept partial authorization transactions by selecting an option in the Merchant Interface. Alternatively, partial authorization transactions can Card-Present Transactions Implementation Guide September

20 Chapter 3 Submitting Transactions be submitted by including a new API field (x_allow_partial_auth) in the initial request that enables partial authorization for that specific request... When an authorization is granted for an amount less than the purchase amount, a Split Tender ID is provided (x_split_tender_id), in addition to the Transaction ID. The Split Tender ID is used on subsequent payments for that purchase, instead of the Transaction ID. The transaction is not submitted for settlement until either the merchant submits payments adding up to the full requested amount, or the merchant indicates the transaction has been completed (in the case when all or part of the remaining balance is paid in cash). Any of the transactions can be voided using the Split Tender ID. The Split Tender ID cannot be submitted together with a Transaction ID; only one or the other can be submitted. Unique field requirements for Partial Authorization Transactions are: x_allow_partial_auth=true (input, optional) The default value is set in the Merchant Interface; you can use this parameter to authorize individual transactions if the option is set to False in the Merchant Interface. Including this field in the transaction request overrides the merchant s account configuration. x_prepaid_balance_on_card (output) this is the authorized amount remaining on the card. x_prepaid_requested_amount (output) this is the amount requested. x_split_tender_id (output) this is the split tender ID provided when the first partial authorization transaction was issued. Use this ID when submitting subsequent transactions related to the same group order. x_split_tender_status (output) indicates whether or not the transaction is complete. x_card_type (output) the card type. Card-Present Transactions Implementation Guide September

21 Standard CP Transaction Submission API for AIM CHAPTER 4 The Card Present 1.0 API supports several Required, Conditional, and Optional information fields for submitting transaction data to the credit card processors and card associations. Some information fields are supported by the API, but are not required by the payment gateway for submitting basic transactions. However, some of these fields might be required by your acquiring bank to meet their transaction processing requirements. You or your Web developer should contact your acquiring bank to learn about their specific transaction information requirements. The following tables list the transaction data fields that can be submitted using the transaction request string. Several of these fields can also be configured in the Merchant Interface. For more information about configuring these settings in the Merchant Interface, please see the Merchant Integration Guide. Fields are name/value pairs with the syntax: x_name_of_field = value of the field&. 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 Description x_login Required Varies by Merchant N/A Pass the API Login ID for the payment gateway account. x_tran_key Required Varies by Merchant x_market_type Required 2 System-generated value obtained from the Merchant Interface. 2 = Retail N/A N/A The transaction key is similar to a password and is used by the system to authenticate requests that are submitted to the gateway. See Appendix C, The Transaction Key for instructions on how to obtain the transaction key from your Merchant Interface. The market type that is configured for your account. Card-Present Transactions Implementation Guide September