Advanced Integration Method (AIM) Developer Guide

Transcription

1 Advanced Integration Method (AIM) Developer Guide Card Not Present Transactions January 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 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 Authorize.Net Where the World Transacts Automated Recurring Billing echeck.net FraudScreen.Net 2

3 Contents CONTENTS Revision History 5 Chapter 1 Introduction 6 AIM Minimum Requirements 6 Payment Card Industry (PCI) Data Security Standard 7 Managing Integration Settings 7 Features of AIM 8 echeck.net 9 Developer Support 9 Software Development Kits 10 Chapter 2 Submitting Transactions 11 Minimum Requirements 11 Credit Card Transaction Types 13 Authorization and Capture 14 Authorization Only 14 Prior Authorization and Capture 15 Capture Only 15 Credit (Refund) 16 Unlinked Credit 16 Void 17 Visa Verification Transactions 18 Partial Authorization Transactions 18 Using the Merchant Interface 19 Chapter 3 Transaction Data Requirements 20 Transaction Post Location 20 AIM Transaction Submission API 20 Merchant Information 21 Transaction Information 22 AIM Developer Guide January

4 Contents Order Information 24 Itemized Order Information 25 Customer Information 26 Shipping Information 28 Additional Shipping Information (Level 2 Data) 29 Cardholder Authentication 30 Merchant-defined fields 32 Chapter 4 Transaction Response 34 Fields in the Payment Gateway Response 36 Response for Duplicate Transactions 41 AIM Transaction Response Types 41 Version Version Setting the Transaction Version 42 Response Code Details 43 Response Codes 43 Response Reason Codes and Response Reason Text 44 Receipt 56 Chapter 5 Test Transactions 58 Testing to Generate Specific Transaction Results 59 Appendix A Fields by Transaction Type 61 Minimum Required Fields 61 Required Fields for Additional AIM Features 62 Best Practice Fields 63 Appendix B Alphabetized List of API Fields 64 AIM Developer Guide January

5 Revision History CHANGES PUBLISH DATE January 2012 August 2011 May 2011 June 2010 December 2009 November 2009 September 2009 July 2009 UPDATES Formatting change only, no content changes Corrected required fields table Corrected example for x_tax format Correct references to AVS/CCV Partial authorization changes Updated table of reason-response codes Updated table of reason-response codes Modified test transactions in live mode to allow for zero authorizations for Visa. Clarified use of x_recurring_billing, x_version Added warning for Merchant Defined Fields Additions to the Response Code list March 2009 Addition of error codes May 2008 Removed SecureSource requirements and various updates AIM Developer Guide January

6 Introduction CHAPTER 1 This guide describes the Web development required to connect an e-commerce website or other application to the Authorize.Net Payment Gateway in order to submit credit card transactions for authorization and settlement using the 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 of data to the payment gateway for transaction processing Securely storing cardholder information And more, depending on the merchant s business requirements The security of an AIM transaction is ensured through a 128-bit Secure Sockets Layer (SSL) connection between the merchant s Web server and the Authorize.Net Payment Gateway. AIM allows merchants the highest degree of customization and control over their customers checkout experience. Note For merchants who prefer a payment solution that collects, transmits, and stores cardholder data, Authorize.Net recommends the Server Integration Method (SIM). See the SIM Developer Guide at: With SIM, merchants never have to collect, transmit, or store sensitive cardholder information. SIM does not require merchants to purchase and install an SSL digital certificate, which reduces the complexity of securely handling and storing cardholder information, simplifying compliance with the Payment Card Industry (PCI) Data Security Standard. AIM Minimum Requirements Before you begin, check with the merchant to make sure that the following AIM requirements have been met. It is strongly recommended that you work closely with AIM Developer Guide January

7 Chapter 1 Introduction the merchant to ensure that any other business and Web site requirements (for example, bank or processor requirements, Web site design preferences) are included in their AIM integration. The merchant must have a U.S.-based merchant bank account that allows Internet transactions. The merchant must have an e-commerce (Card Not Present) Authorize.Net Payment Gateway account. The merchant must have a valid Secure Sockets Layer (SSL) certificate and their Web site must be capable of initiating both client- and server-side SSL connections. The merchant s website must have server-side scripting or CGI capabilities such as ASP Classic, C#, Cold Fusion, Java, Perl, PHP or VB.Net. The merchant must be able to store payment gateway account data securely (for example, API Login ID, or Transaction Key). Payment Card Industry (PCI) Data Security Standard Important AIM involves transmitting sensitive cardholder data using the merchant s Web server. Therefore, if the merchant stores cardholder information, it must be stored securely and in accordance with the Payment Card Industry (PCI) Data Security Standard. For more information about PCI and other industry standard processing practices, see the Developer Security Best Practices White Paper. If merchants need a solution that collects, transmits, and stores cardholder data, they should use the Server Implementation Method (SIM). For more information about SIM, see the SIM Developer Guide. Managing Integration Settings When integrating to the payment gateway, you should be aware that most settings for a merchant s integration can be configured and managed in one of two ways: Included in the transaction request on a per-transaction basis using the application programming interface (API), (as described in this guide) AIM Developer Guide January

8 Chapter 1 Introduction Configured in the Merchant Interface and applied to all transactions. Important The Merchant Interface at is a secure website on which merchants can manage their payment gateway account settings, including their Web site integration settings. Review the Merchant Integration Guide at for information on managing the merchant s payment gateway integration using the Merchant Interface. Transaction settings submitted in the transaction request will override transaction settings configured in the Merchant Interface. However, be aware that some integration settings must be configured in the Merchant Interface. To help the merchant maintain a robust integration, review with the merchant the integration settings that can be configured in the Merchant Interface and determine which settings can be posted on a per-transaction basis and which should be configured in the Merchant Interface. See Appendix A, "Fields by Transaction Type," on page 61 for a list of fields that can be submitted on a pertransaction basis. Features of AIM In addition to basic transaction processing, AIM provides merchants with several features for configuring transaction security options and further customizing their customers checkout experience. These features are listed in the AIM feature selection table below. Take a few moments to discuss these features with your merchant and select the appropriate features for their integration. Feature Description Requirements Address Verification Service (AVS) Filter Card Code Verification (CCV) Filter This feature enables merchants to compare the billing address submitted by the customer for the transaction with the address on file at the card issuing bank. Filter settings in the Merchant Interface allow the merchant to reject transactions based on the AVS response received. This feature enables merchants to compare the card code submitted by the customer for the transaction with the card code on file at the card issuing bank. Filter settings in the Merchant Interface allow the merchant to reject transactions based on the CCV response received. To implement AVS, the merchant must require the Address and ZIP Code fields on their custom payment form. For more information about AVS, see the Merchant Integration Guide at support/merchant/. To implement CCV, the merchant must require the Card Code on their custom payment form. For more information about CCV, see the Merchant Integration Guide at support/merchant/. AIM Developer Guide January

9 Chapter 1 Introduction Feature Description Requirements Itemized Order Information Receipt This feature enables merchants to submit details for items purchased. This information is included in the customer s confirmation , in the Transaction Details for the transaction, and in QuickBooks download reports in the Merchant Interface. This feature enables merchants to have the payment gateway send an automatic receipt to their customers. To implement Itemized Order Information, the line item field must be submitted for each transaction. See "Itemized Order Information," page 25 for details. To configure the payment gateway receipt, merchants must require the customer addresses on their custom payment form, and settings must be configured in the Receipts section of the Settings menu in the Merchant Interface or submitted for each transaction. See " Receipt," page 56 for details. echeck.net In addition to processing credit card transactions, the payment gateway also supports electronic check transactions with our exclusive echeck.net product.contact the merchant to determine whether echeck.net is enabled for their payment gateway account or whether they would like to have it enabled. If echeck.net is enabled, you must ensure that the merchant s Web site integration supports all echeck.net field requirements. See the echeck.net Developer Guide for more information. Developer Support Several resources are available to help you successfully integrate a merchant Web site or other application to the Authorize.Net Payment Gateway. The Developer Center at provides test accounts, sample code, SDKs, FAQs, and troubleshooting tools. If you can t find what you need in the Developer Center, our Integration Team is available to answer your questions by at developer@authorize.net. (Our Integration Team can only assist with support requests specifically about the Authorize.Net application programming interface (API) and/or services.) AIM Developer Guide January

10 Chapter 1 Introduction Be sure to read our Developer Security Best Practices White Paper for information on how to maximize the security and reliability of your merchant integration solutions. If you have any suggestions about how we can improve or correct this guide, send to documentation@authorize.net. Software Development Kits Authorize.Net offers software development kits (SDKs) that present an alternate objectoriented model, in several popular languages. To use these SDKs, the merchant s transaction version must be set to 3.1. The SDK performs the core payment activities (such as error handling and parsing, network communication, and data encoding) behind the scenes. The SDK provides utilities to help developers build payment flows for each of the integration methods. You can download the SDKs at downloads/. AIM Developer Guide January

11 Submitting Transactions CHAPTER 2 The payment gateway supports several credit card transaction types for transactions submitted by AIM. To implement AIM for a merchant s Web site or proprietary business application, you will need to develop an application that: Securely obtains all of the information required to process a transaction (including data requirements specified by the merchant). Initiates an SSL connection from the merchant s Web server to the payment gateway transaction post location to pass transaction data in name/value pairs. Receives and parses the transaction response from the payment gateway and displays the results to the customer. You can develop the application in one of two ways: by yourself using the information provided in this document use Authorize.Net sample code available for free from our Developer Center. If you choose to use sample code, be aware that to achieve a successful implementation, the code must be modified with the merchant s specific payment gateway account information. Be sure to carefully review the readme.txt files and comments included in each file of sample code in order to achieve a faster, successful integration. Developer test accounts with API Login IDs and Transaction Keys are also available to test your integration methods to the Authorize.Net Payment Gateway at Minimum Requirements The following table represents the minimum fields required for submitting a credit card transaction request to the payment gateway using AIM. The data fields are name/value pairs with the following syntax: x_name_of_field=value of field&. AIM Developer Guide January

12 Chapter 2 Submitting Transactions Field Name x_login x_tran_key x_type x_amount x_card_num x_exp_date Description Value: The merchant s unique API Login ID Format; Up to 20 characters Notes: The merchant API Login ID is provided in the Merchant Interface and must be stored securely. The API Login ID and Transaction Key together provide the merchant the authentication required for access to the payment gateway. See the Merchant Integration Guide at for more information. Value: The merchant s unique Transaction Key Format; 16 characters Notes: The merchant Transaction Key is provided in the Merchant Interface and must be stored securely. The API Login ID and Transaction Key together provide the merchant the authentication required for access to the payment gateway. See the Merchant Integration Guide at for more information. Value: The type of credit card transaction Format; AUTH_CAPTURE (default), AUTH_ONLY, CAPTURE_ONLY, CREDIT, PRIOR_AUTH_CAPTURE, VOID Notes: If the value submitted does not match a supported value, the transaction is rejected. If this field is not submitted or the value is blank, the payment gateway will process the transaction as an AUTH_CAPTURE. Value: The amount of the transaction Format; Up to 15 digits with a decimal point (no dollar symbol). For example, Notes: This is the total amount and must include tax, shipping, and any other charges. Value: The customer s credit card number Format; Between 13 and 16 digits without spaces. When x_type=credit, only the last four digits are required. Notes: This is sensitive cardholder information and must be stored securely and in accordance with the Payment Card Industry (PCI) Data Security Standard. For more information about PCI, see the Developer Security Best Practices White Paper. Value: The customer s credit card expiration date. Format; MMYY, MM/YY,MM-YY, MMYYYY, MM/YYYY, MM-YYYY Notes: This is sensitive cardholder information and must be stored securely and in accordance with the Payment Card Industry (PCI) Data Security Standard. For more information about PCI, see the Developer Security Best Practices White Paper. AIM Developer Guide January

13 Chapter 2 Submitting Transactions Field Name x_trans_id x_split_tender_id x_auth_code x_relay_response x_delim_data Description Value: The payment gateway-assigned transaction ID of an original transaction Notes: Required only for CREDIT, PRIOR_AUTH_CAPTURE, and VOID transactions. Do not include this field if you are providing the x_split_tender_id field. For more information about transaction types, see "Credit Card Transaction Types," page 13. Value: The payment gateway-assigned ID that links the current authorization request to the original authorization request. Format; Numeric Notes: This value applies only to partial authorization transactions, and is returned in the reply message from the original authorization request. For more information, see "Partial Authorization Transactions," page 18. Value: The authorization code of an original transaction not authorized on the payment gateway Format; 6 characters Notes: Required only for CAPTURE_ONLY transactions. See "Credit Card Transaction Types," page 13. Value: FALSE Format; FALSE, F, NO, N Notes: SIM applications use relay response. Set this to false if you are using AIM. Value: Indicates whether a delimited transaction response is required Format; TRUE, T, YES, Y Notes: A value of TRUE indicates a request for delimited response from the payment gateway. Since all AIM transactions are direct response, a value of TRUE is required. Submit this field for each transaction to be sure that transaction responses are returned in the correct format. See Chapter 4, "Transaction Response," on page 34 for more about delimited response Credit Card Transaction Types This section describes the credit card transaction types supported by the payment gateway and their specific field requirements. It s a good idea to talk to your merchant about how their business plans to submit transaction so that you can properly integrate their payment gateway account to support their business processes. For example, are they submitting transactions mainly through an e-commerce Web site? Do they need to integrate a custom application to allow call center representatives to enter mail order/telephone order (MOTO) transactions? Would they like the ability to verify the availability of funds on a customer s credit card account at the time of purchase and then charge the credit card at the time they ship the order? AIM Developer Guide January

14 Chapter 2 Submitting Transactions The payment gateway supports the following credit card transaction types. Note Some of the field requirements listed in this section for each credit card transaction type are in addition to the minimum field requirements already set forth above for ALL transactions submitted to the payment gateway. For a list of all fields that are required for each credit card transaction type, see Appendix A, "Fields by Transaction Type," on page 61. Authorization and Capture This is the most common type of credit card transaction and is the default payment gateway transaction type. The amount is sent for authorization, and if approved, is automatically submitted for settlement. The unique field requirement for an Authorization and Capture transaction is: x_type=auth_capture Authorization Only This transaction type is sent for authorization only. The transaction will not be sent for settlement until the credit card transaction type Prior Authorization and Capture (see definition below) is submitted, or the transaction is submitted for capture manually in the Merchant Interface. For more information about capturing Authorization Only transactions in the Merchant Interface, see the Merchant Integration Guide at support/merchant/. If action for the Authorization Only transaction is not taken on the payment gateway within 30 days, the authorization expires and is no longer available for capture. A new Authorization Only transaction would then have to be submitted to obtain a new authorization code. The unique field requirement for an Authorization Only transaction is: x_type=auth_only Merchants can submit Authorization Only transactions if they want to verify the availability of funds on the customer s credit card before finalizing the transaction. This transaction type can also be submitted if the merchant does not currently have an item in stock or wants to review orders before shipping goods. AIM Developer Guide January

15 Chapter 2 Submitting Transactions Prior Authorization and Capture This transaction type is used to complete an Authorization Only transaction that was successfully authorized through the payment gateway. Note An Authorization Only and a Prior Authorization and Capture together are considered one complete transaction. After the Prior Authorization and Capture is submitted, the transaction will be sent for settlement. The payment gateway accepts this transaction type and initiates settlement if the following conditions are met: The original Authorization Only transaction was submitted within the previous 30 days (Authorization Only transactions expire on the payment gateway after 30 days). The transaction is submitted with the valid transaction ID (x_trans_id) of an original, successfully authorized, Authorization Only transaction. The original transaction is not yet captured, expired or errored. The amount being requested for capture is less than or equal to the original authorized amount. Only a single Prior Authorization and Capture transaction can be submitted against an Authorization Only. The unique field requirements for a Prior Authorization and Capture are: x_type=prior_auth_capture x_trans_id=transaction ID here For this transaction type, the amount field (x_amount) is required only if a Prior Authorization and Capture is submitted for an amount that is less than the amount of the original Authorization Only transaction. If no amount is submitted, the payment gateway will initiate settlement for the amount of the original authorized transaction. Capture Only This transaction type is used to complete a previously authorized transaction that was not originally submitted through the payment gateway or that requires voice authorization. The payment gateway accepts this transaction type and initiates settlement if the following conditions are met: The transaction is submitted with the valid authorization code issued to the merchant to complete the transaction. The unique field requirements for a Capture Only transaction are: x_type=capture_only AIM Developer Guide January

16 Chapter 2 Submitting Transactions x_auth_code=authorization Code here For instructions on how to perform a Capture Only transaction in the Merchant Interface, see the Merchant Integration Guide at Credit (Refund) This transaction type is used to refund a customer for a transaction that was originally processed and successfully settled through the payment gateway. The payment gateway accepts Credits if the following conditions are met: The transaction is submitted with the valid transaction ID (x_trans_id) of an original, successfully settled transaction. The amount being requested for refund is less than or equal to the original settled amount. The sum of multiple Credit transactions submitted against the original transaction is less than or equal to the original settled amount. At least the last four digits of the credit card number (x_card_num) used for the original, successfully settled transaction are submitted. An expiration date is not required. The transaction is submitted within 120 days of the settlement date of the original transaction. The unique field requirements for a Credit transactiton are: x_type=credit x_trans_id=transaction ID here x_card_num=full credit card number or last four digits only here Unlinked Credit This transaction type is used to issue a refund for a transaction that was not originally submitted through the payment gateway. It also enables the merchant to override restrictions for submitting refunds for payment gateway transactions, for example, if the merchant is beyond the 120-day period for submitting a refund or would like to refund an amount that is greater than the original transaction amount. The ability to submit unlinked credits is not a standard feature of a merchant s payment gateway account. To be enabled for expanded credits capability (ECC), the AIM Developer Guide January

17 Chapter 2 Submitting Transactions merchant must submit an application, which can be found at ecc.pdf. Important A transaction ID must not be submitted with an Unlinked Credit. If ECC is enabled for the merchant s account, and a transaction ID is submitted with the Unlinked Credit transaction, then the payment gateway will attempt to apply the credit to an original transaction with the transaction ID submitted. The unique field requirement for an Unlinked Credit is: x_type=credit Void This transaction type can be used to cancel either an original transaction that is not yet settled, or an entire order composed of more than one transactions. A Void prevents the transaction or the order from being sent for settlement. A Void can be submitted against any other transaction type. Note If you are not sure whether a transaction is settled, you can attempt to submit a Void first. If the Void transaction results in an error, the original transaction is likely settled and you can submit a Credit for the transaction. The payment gateway accepts Voids if the following conditions are met: The transaction is submitted with the valid transaction ID (x_trans_id) of an original, successfully authorized transaction. To void an entire order, submit the split tender ID (x_split_tender_id). The original transaction is not already settled, expired or errored. The unique field requirements for a Void transaction are: x_type=void x_trans_id=transaction ID, or x_split_tender_id=split Tender ID. Note Typically, Authorization Only or Authorization and Capture are the primary transaction types submitted by an e-commerce Web site or other application. Although they most likely will not be used for the merchant s website integration, all other transaction types listed above can be integrated for automatic submission into an internal or enterprise application, like those used in a call center, or they can also be submitted by the merchant manually using the Virtual Terminal in the Merchant Interface. AIM Developer Guide January

18 Chapter 2 Submitting Transactions Visa Verification Transactions The following are required for $0 Visa verification calls: The transaction type must be AUTH_ONLY. All other transaction types will be rejected. Bill To address (x_address) and zip code (x_zip) are required in order to perform the AVS check. Not all processors accept zero dollar amount. Partial Authorization Transactions A split tender order is an order in which two or more transactions are used to cover the total amount of the order. Merchants 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. 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, send a void request, using the split tender ID instead of a transaction ID. This action will void all the transactions in the group. 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 be submitted by including a new API field (x_allow_partial_auth) in the initial request that enables partial authorization for that specific request. AIM Developer Guide January

19 Chapter 2 Submitting Transactions When an authorization is granted for an amount less than the purchase amount, a split tender ID is provided, in addition to the Transaction ID. The split tender ID is used on subsequent payments for that purchase. The transaction is not submitted for settlement until either the merchant submits payments adding up to the full requested amount, or until the merchant indicates that the transaction has been completed (when all or part of the remaining balance is paid in cash). You can void all transactions in an order using a split tender ID, or you can void individual transactions using a transaction 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. This parameter is sent to the merchant during relay response processing. It is not included in the delimited response. x_card_type (output) the card type. Using the Merchant Interface The Merchant Interface enables merchants to manage transactions, capture Authorization Only transactions, void transactions, and issue refunds. These transaction types can also be managed automatically using the API if you are integrating a custom application to the payment gateway. However, for most integrations, these transaction types can be more conveniently and easily managed in the Merchant Interface. For more information on submitting transactions in the Merchant Interface, see the Merchant Integration Guide at or click Help in the top right corner of the Merchant Interface. AIM Developer Guide January

20 Transaction Data Requirements CHAPTER 3 The standard payment gateway application programming interface (API) consists of required information fields (introduced in the previous section) and additional optional fields that can be submitted to the payment gateway for real-time transaction processing. Transaction Post Location The merchant s Web site should submit transaction requests to the following payment gateway URL: Note If you are using an Authorize.Net developer test account, test transactions are posted to a staging environment at transact.dll. If you do not have a developer test account, you can sign up for one at AIM Transaction Submission API 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, see the Merchant Integration Guide at Fields are name/value pairs with the syntax: x_name_of_field = value of the field&. AIM Developer Guide January

21 Chapter 3 Transaction Data Requirements Merchant Information Field Name x_login Description Required Value: The merchant s unique API Login ID Format: Up to 20 characters Notes: The merchant API Login ID is provided in the Merchant Interface and must be stored securely. The API Login ID and Transaction Key together provide the merchant authentication required for access to the payment gateway. See the Merchant Integration Guide at for more information. x_tran_key x_allow_partial_auth Required Value: The merchant s unique Transaction Key Format: 16 characters Notes: The merchant Transaction Key is provided in the Merchant Interface and must be stored securely. The API Login ID and Transaction Key together provide the merchant authentication required for access to the payment gateway. See the Merchant Integration Guide at for more information. Value: True, False Notes: Indicates if the transaction is enabled for partial authorization. Including this field in the transaction request overrides your account configuration. For more information, see "Partial Authorization Transactions," page 18. AIM Developer Guide January

22 Chapter 3 Transaction Data Requirements Transaction Information FIELD NAME REQUIRED VALUE FORMAT NOTES x_version x_type x_method x_recurring_ billing x_amount Required Value: The merchant s transaction version Format: 3,0, 3.1 Notes: Indicates to the system the set of fields that will be included in the response: 3.0 is the default version. 3.1 allows the merchant to utilize the Card Code feature and the Partial Authorization feature, and is the current standard version. It is highly recommended that you submit this field on a per-transaction basis to be sure that the formats of transaction requests and the responses you receive are consistent. For more information, see Appendix A, "Fields by Transaction Type," on page 61 of this document. Value: The type of credit card transaction Format: AUTH_CAPTURE (default), AUTH_ONLY, CAPTURE_ONLY, CREDIT, PRIOR_AUTH_ CAPTURE, VOID Notes: If the value submitted does not match a supported value, the transaction is rejected. If this field is not submitted or the value is blank, the payment gateway will process the transaction as an AUTH_CAPTURE. Value: The payment method Format: CC or ECHECK Notes: The method of payment for the transaction, CC (credit card) or ECHECK (electronic check). If this field is not submitted or is blank, the value will default to CC. For more information about echeck.net transaction requirements, see the echeck.net Developer Guide. Value: The recurring billing status Format: TRUE, FALSE,T, F, YES, NO,Y, N,1, 0 Notes: Indicating marker used by merchant account providers to identify transactions which originate from merchant hosted recurring billing applications. This value is not affiliated with Automated Recurring Billing. Required Value: The amount of the transaction Format: Up to 15 digits with a decimal point (no dollar symbol). For example, 8.95 Notes: This is the total amount and must include tax, shipping, and any other charges. The amount can either be hard coded or posted to a script. AIM Developer Guide January

23 Chapter 3 Transaction Data Requirements FIELD NAME REQUIRED VALUE FORMAT NOTES x_card_num x_exp_date x_card_code x_trans_id x_split_tender_ id Required Value: The customer s credit card number Format: Between 13 and 16 digits without spaces When x_type=credit, only the last four digits are required. Notes: This is sensitive cardholder information and must be stored securely and in accordance with the Payment Card Industry (PCI) Data Security Standard. For more information about PCI, see the Developer Security Best Practices White Paper. Required Value: The customer s credit card expiration date Format: MMYY, MM/YY, MM-YY, MMYYYY, MM/YYYY, MM-YYYY Notes: This is sensitive cardholder information and must be stored securely and in accordance with the Payment Card Industry (PCI) Data Security Standard. For more information about PCI, see the Developer Security Best Practices White Paper. Value: The customer s card code Format: Numeric Notes: The three- or four-digit number on the back of a credit card (on the front for American Express). This field is required if the merchant would like to use the Card Code Verification (CCV) security feature. For more information, see the Merchant Integration Guide at support/merchant. Cardholder information must be stored securely and in accordance with the Payment Card Industry (PCI) Data Security Standard. See the Developer Security Best Practices White Paper for more information. Conditional Required only for CREDIT, PRIOR_ AUTH_ CAPTURE, and VOID transactions Value: The payment gateway assigned transaction ID of an original transaction Notes: For more information about transaction types, see the "Credit Card Transaction Types," page 13 section of this document. Conditional Value: The payment gateway-assitned ID assigned when the original transaction includes two or more partial payments. This is the identifier that is used to group transactions that are part of a split tender order. Notes: If the first transaction results in a partial authorization, the payment gateway returns this ID to the merchant. The merchant must pass this ID back with each subsequent transaction that will be part of the group of transactions sent to obtain the entire amount of the order. The payment gateway does not calculate new amounts, that is up to the merchant s software. For more information about partial authorization transactions, see the "Partial Authorization Transactions," page 18 topic. AIM Developer Guide January

24 Chapter 3 Transaction Data Requirements FIELD NAME REQUIRED VALUE FORMAT NOTES x_auth_code x_test_request x_duplicate_ window Conditional. Required only for CAPTURE_ ONLY transactions Value: The authorization code of an original transaction not authorized on the payment gateway Format: 6 characters Notes: See the "Credit Card Transaction Types," page 13 section of this document. Value: The request to process test transactions Format: TRUE, FALSE, T, F, YES, NO, Y, N, 1, 0 Notes: Indicates if the transaction should be processed as a test transaction. See Chapter 5, "Test Transactions," on page 58 of this guide for more information. Value: The window of time after the submission of a transaction that a duplicate transaction can not be submitted Format: Any value between 0 and (no comma) Notes: Indicates in seconds the window of time after a transaction is submitted during which the payment gateway will check for a duplicate transaction. The maximum time allowed is 8 hours (28800 seconds). If a value less than 0 is sent, the payment gateway will default to 0 seconds. If a value greater than is sent, the payment gateway will default to If no value is sent, the payment gateway will default to 2 minutes (120 seconds). If this field is present in the request with or without a value, an enhanced duplicate transaction response is sent. See the "Response for Duplicate Transactions," page 41 section of this guide for more information. Order Information Field Name x_invoice_num x_description Description Value: The merchant-assigned invoice number for the transaction Format: Up to 20 characters (no symbols) Notes: The invoice number must be created dynamically on the merchant server or provided on a per-transaction basis. The payment gateway does not perform this function. Value: The transaction description Format: Up to 255 characters (no symbols) Notes: The description must be created dynamically on the merchant server or provided on a per-transaction basis. The payment gateway does not perform this function. AIM Developer Guide January

25 Chapter 3 Transaction Data Requirements Itemized Order Information Based on their respective business requirements, merchants can choose to submit itemized order information with a transaction. Itemized order information is not submitted to the processor and is not currently returned with the transaction response. This information is displayed on the Transaction Detail page and in QuickBooks download file reports in the Merchant Interface. Note The value for the x_line_item field is capable of including delimited item information. In this case, line item values must be included in the order listed below. Field Name Description x_line_item Value: Any string Format: Line item values must be delimited by a bracketed pipe < > Itemized order information. Item ID< > < >item name< > < >item description< > < >itemx quantity< > < >item price (unit cost)< > < >itemx taxable eth ID assigned to an item. Format: Up to 31 characters A short description of an item. Format: Up to 31 characters A detailed description of an item. Format: Up to 255 characters The quantity of an item. Format: Up to two decimal places Must be a positive number Cost of an item per unit, excluding tax, freight, and duty. Format: Up to two decimal places Must be a positive number The dollar sign ($) is not allowed when submitting delimited information. Indicates whether the item is subject to tax. Format: TRUE, FALSE, T, F, YES, NO, Y, N, 1, 0 The merchant can submit up to 30 distinct line items containing itemized order information per transaction. For example: AIM Developer Guide January

26 Chapter 3 Transaction Data Requirements Example Submitting itemized order information x_line_item=item1< >golf balls< >< >2< >18.95< >Y&x_line_item= item2< >golf bag< >Wilson golf carry bag, red< >1< >39.99< >Y& x_line_item=item3< >book< >Golf for Dummies< >1< >21.99< >Y& Note For Prior Authorization and Capture transactions, if line item information was submitted with the original transaction, adjusted information can be submitted if the transaction changed. If no adjusted line item information is submitted, the information submitted with the original transaction applies. Customer Information Field Name x_first_name x_last_name x_company x_address x_city x_state Description Value: The first name associated with the customer s billing address Format: Up to 50 characters (no symbols) Value: The last name associated with the customer s billing address Format: Up to 50 characters (no symbols) Value: The company associated with the customer s billing address Format: Up to 50 characters (no symbols) Value: The customer s billing address Format: Up to 60 characters (no symbols) Notes: Required if the merchant would like to use the Address Verification Service security feature. For more information on AVS, see the Merchant Integration Guide at Value: The city of the customer s billing address Format: Up to 40 characters (no symbols) Value: The state of the customer s billing address Format: Up to 40 characters (no symbols) or a valid two-character state code AIM Developer Guide January

27 Chapter 3 Transaction Data Requirements Field Name x_zip x_country x_phone x_fax x_ x_cust_id x_customer_ip Description Value: The ZIP code of the customer s billing address Format: Up to 20 characters (no symbols) Notes: Required if the merchant would like to use the Address Verification Service security feature. For more information on AVS, see the Merchant Integration Guide at Value: The country of the customer s billing address Format: Up to 60 characters (no symbols) Value: The phone number associated with the customer s billing address Format: Up to 25 digits (no letters). For example, (123) Value: The fax number associated with the customer s billing address Format: Up to 25 digits (no letters). For example, (123) Value: The customer s valid address Format: Up to 255 characters. For example, janedoe@customer.com Notes: The address to which the customer s copy of the receipt is sent when Receipts is configured in the Merchant Interface. The is sent to the customer only if the address format is valid. For more information about Receipts, see the Merchant Integration Guide at Value: The merchant assigned customer ID Format: Up to 20 characters (no symbols) Notes: The unique identifier to represent the customer associated with the transaction. The customer ID must be created dynamically on the merchant server or provided on a per-transaction basis. The payment gateway does not perform this function. Value: The customer s IP address Format: Up to 15 characters (no letters). For example, Notes: IP address of the customer initiating the transaction. If this value is not passed, it will default to This field is required when using the Fraud Detection Suite (FDS) IP Address Blocking tool. For more information about FDS, see the Merchant Integration Guide at AIM Developer Guide January

28 Chapter 3 Transaction Data Requirements Shipping Information Field Name 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 Description Value: The first name associated with the customer s shipping address Format: Up to 50 characters (no symbols) Value: The last name associated with the customer s shipping address Format: Up to 50 characters (no symbols) Value: The company associated with the customer s shipping address Format: Up to 50 characters (no symbols) Value: The customer s shipping address Format: Up to 60 characters (no symbols) Value: The city of the customer s shipping address Format: Up to 40 characters (no symbols) Value: The state of the customer s shipping address Format: Up to 40 characters (no symbols) or a valid two-character state code Value: The ZIP code of the customer s shipping address Format: Up to 20 characters (no symbols) Value: The country of the customer s shipping address Format: Up to 60 characters (no symbols) AIM Developer Guide January

29 Chapter 3 Transaction Data Requirements Additional Shipping Information (Level 2 Data) Field Name x_tax x_freight Description Value: The valid tax amount OR delimited tax information Format: When submitting delimited tax information, values must be delimited by a bracketed pipe < > Notes: The tax amount charged OR when submitting this information using the transaction request string, delimited tax information including the sales tax name, description, and amount is also allowed. The total amount of the transaction in x_amount must include this amount. tax item name< > tax description< > tax amount The tax item name. The tax item description. The tax item amount. Format: The dollar sign ($) is not allowed when submitting delimited information. The total amount of the transaction in x_amount must include this amount. Example: x_tax=tax1< >state tax< >0.09& Value: The valid freight amount OR delimited freight information Format: When submitting delimited freight information, values must be delimited by a bracketed pipe < > Notes: The freight amount charged OR when submitting this information using the transaction request string, delimited freight information including the freight name, description, and amount is also allowed. The total amount of the transaction in x_amount must include this amount. freight item name< > freight description< > freight amount The freight item name. The freight item description. The freight amount. Format: The dollar sign ($) is not allowed when submitting delimited information. The total amount of the transaction in x_amount must include this amount. Example: x_freight=freight< >ground overnight< >12.95& AIM Developer Guide January

30 Chapter 3 Transaction Data Requirements Field Name x_duty x_tax_exempt x_po_num Description Value: The valid duty amount OR delimited duty information Format: When submitting delimited duty information, values must be delimited by a pipe < > Notes: The duty amount charged OR when submitting this information using the transaction request string, delimited duty information including the duty name, description, and amount is also allowed. The total amount of the transaction in x_amount must include this amount. duty item name< > duty description< > duty amount The duty item name. The duty item description. Format: The dollar sign ($) is not allowed when submitting delimited information. The duty amount. The total amount of the transaction in x_amount must include this amount. Example: x_duty=duty1< >export< >15.00& Value: The tax exempt status Format: TRUE, FALSE, T, F, YES, NO, Y, N, 1, 0 Notes: Indicates whether the transaction is tax exempt. Value: The merchant-assigned purchase order number Format: Up to 25 characters (no symbols) Notes: The purchase order number must be created dynamically on the merchant server or provided on a per-transaction basis. The payment gateway does not perform this function. Note Delimited duty, freight, and tax information are not returned in the transaction response or in the merchant confirmation . This information is displayed only on the Transaction Detail page in the Merchant Interface. Cardholder Authentication The payment gateway supports the transmission of authentication fields for the following cardholder authentication programs: Verified by Visa AIM Developer Guide January