Appendix B - Functional Reference & Result Fields |
In version 3.0 and 3.1 of the system, there are many ways to integrate a merchant's server with the system. This section provides a convenient reference to all of the types of information that can be sent to the system, and all of the things that could be expected in return. All integration with the system is done by performing an HTTP(S) form POST to https://secure.authorize.net/gateway/transact.dll.
The following table provides an alphabetical list of all of the possible values that will be recognized by the system when sent in an HTML form. This table specifies which fields and which values are needed for each of the different connection types.
| v3.0 and v3.1 Gateway Interface Form Field Names | Possible Values (Bold = Default if not present or stored) | WebLink | ADC Direct Response | ADC Relay Response |
|---|---|---|---|---|
| x_ADC_Delim_Character | any character ( , ) | N/A | optional | N/A |
| x_ADC_Delim_Data | TRUE | N/A | required | N/A |
| x_ADC_Encapsulate_Character | any character (none) | N/A | optional | N/A |
| x_ADC_Relay_Response | TRUE | N/A | N/A | required |
| x_ADC_URL | any valid URL (or FALSE for ADC Direct Response) | N/A | required(it is required for x_ADC_URL to have a value of “FALSE” for ADC Direct Response) | required |
| x_Address | any string | required for all eCheck transactions and Wells Fargo SecureSource Merchants—otherwise optional | required for all eCheck transactions and Wells Fargo SecureSource Merchants—otherwise optional | required for all eCheck transactions and Wells Fargo SecureSource Merchants—otherwise optional |
| x_Amount | any valid amount | required | required | required |
| x_Auth_Code | any valid Authorization Code | optional | optional | optional |
| x_Background_URL | any valid URL | optional | optional | optional |
| x_Bank_ABA_Code | any valid bank ABA code | required for all eCheck transactions—otherwise optional | required for all eCheck transactions—otherwise optional | required for all eCheck transactions—otherwise optional |
| x_Bank_Acct_Num | any valid bank account number | required for all eCheck transactions—otherwise optional | required for all eCheck transactions—otherwise optional | required for all eCheck transactions—otherwise optional |
| x_Bank_Acct_Type | CHECKING, SAVINGS | optional | optional | optional |
| x_Bank_Name | any valid bank name | required for all eCheck transactions—otherwise optional | required for all eCheck transactions—otherwise optional | required for all eCheck transactions—otherwise optional |
| x_Card_Code | any valid CVV2 or CVC2 value | optional | optional | optional |
| x_Card_Num | any valid credit card number | required if not using x_Show_Form | required | required if not using x_Show_Form |
| x_City | any string | required for all eCheck transactions and Wells Fargo SecureSource Merchants—otherwise optional | required for all eCheck transactions and Wells Fargo SecureSource Merchants—otherwise optional | required for all eCheck transactions and Wells Fargo SecureSource Merchants—otherwise optional |
| x_Color_Background | any valid color or color hex code (White or #FFFFFF) | optional | optional | optional |
| x_Color_Link | any valid color or color hex code (Blue or #0000FF) | optional | optional | optional |
| x_Color_Text | any valid color or color hex code (Black or #000000) | optional | optional | optional |
| x_Company | any string | optional | optional | optional |
| x_Country | any string | required for all eCheck transactions and Wells Fargo SecureSource Merchants—otherwise optional | required for all eCheck transactions and Wells Fargo SecureSource Merchants—otherwise optional | required for all eCheck transactions and Wells Fargo SecureSource Merchants—otherwise optional |
| x_Currency_Code | USD | optional | optional | optional |
| x_Cust_ID | any string | optional | optional | optional |
| x_Customer_IP | Must be in the format 255.255.255.255 | required for all eCheck transactions and Wells Fargo SecureSource Merchants—otherwise optional | required for all eCheck transactions and Wells Fargo SecureSource Merchants—otherwise optional | required for all eCheck transactions and Wells Fargo SecureSource Merchants—otherwise optional |
| x_Customer_Tax_ID | 20 digits (numbers and spaces only)—may be used for customer SSN | required for all eCheck transactions (either drivers license #, state and DOB, or SSN) | required for all eCheck transactions (either drivers license #, state and DOB, or SSN) | required for all eCheck transactions (either drivers license #, state and DOB, or SSN) |
| x_Customer_Organization_Type | "I" or "B" "I" = Individual "B" = Business | required for all eCheck transactions and Wells Fargo SecureSource Merchants—otherwise optional | required for all eCheck transactions and Wells Fargo SecureSource Merchants—otherwise optional | required for all eCheck transactions and Wells Fargo SecureSource Merchants—otherwise optional |
| x_Description | any string | optional | optional | optional |
| x_Drivers_License_Num | eCheck only, any string | required for all eCheck transactions (either drivers license #, state and DOB, or SSN) | required for all eCheck transactions (either drivers license #, state and DOB, or SSN) | required for all eCheck transactions (either drivers license #, state and DOB, or SSN) |
| x_Drivers_License_State | eCheck only, 2-character state abbreviation | required for all eCheck transactions (either drivers license #, state and DOB, or SSN) | required for all eCheck transactions (either drivers license #, state and DOB, or SSN) | required for all eCheck transactions (either drivers license #, state and DOB, or SSN) |
| x_Drivers_License_DOB | eCheck only, YYYYMMDD | required for all eCheck transactions (either drivers license #, state and DOB, or SSN) | required for all eCheck transactions (either drivers license #, state and DOB, or SSN) | required for all eCheck transactions (either drivers license #, state and DOB, or SSN) |
| x_Duty | any valid amount | optional | optional | optional |
| x_Email | any valid email address | required for all eCheck transactions and Wells Fargo SecureSource Merchants—otherwise optional | required for all eCheck transactions and Wells Fargo SecureSource Merchants—otherwise optional | required for all eCheck transactions and Wells Fargo SecureSource Merchants—otherwise optional |
| x_Email_Customer | TRUE, FALSE | optional | optional | optional |
| x_Email_Merchant | TRUE, FALSE | optional | optional | optional |
| x_Exp_Date | mmyy, mm/yy, mm/yyyy | required if not using x_Show_Form | required | required if not using x_Show_Form |
| x_Fax | any string | optional | optional | optional |
| x_First_Name | any string | required for all eCheck transactions and Wells Fargo SecureSource Merchants—otherwise optional | required for all eCheck transactions and Wells Fargo SecureSource Merchants—otherwise optional | required for all eCheck transactions and Wells Fargo SecureSource Merchants—otherwise optional |
| x_Footer_Email_Receipt | any valid text | optional | optional | optional |
| x_Footer_Html_Payment_Form | any valid text or HTML | optional | optional | optional |
| x_Footer_Html_Receipt | any valid text or HTML | optional | optional | optional |
| x_Freight | any valid amount | Required for all eCheck transactions and Wells Fargo SecureSource Merchants ($0 is valid)—otherwise optional | Required for all eCheck transactions and Wells Fargo SecureSource Merchants ($0 is valid)—otherwise optional | Required for all eCheck transactions and Wells Fargo SecureSource Merchants ($0 is valid)—otherwise optional |
| x_Header_Email_Receipt | any valid text | optional | optional | optional |
| x_Header_Html_Payment_Form | any valid text or HTML | optional | optional | optional |
| x_Header_Html_Receipt | any valid text or HTML | optional | optional | optional |
| x_Invoice_Num | any string | optional | optional | optional |
| x_Last_Name | any string | required for all eCheck transactions and Wells Fargo SecureSource Merchants—otherwise optional | required for all eCheck transactions and Wells Fargo SecureSource Merchants—otherwise optional | required for all eCheck transactions and Wells Fargo SecureSource Merchants—otherwise optional |
| x_Login | any valid merchant login ID | required | required | required |
| x_Logo_URL | any valid URL | optional | optional | optional |
| x_Merchant_Email | any valid email address | optional | optional | optional |
| x_Method | CC, ECHECK | should be set to ECHECK for eCheck transactions—otherwise optional | should be set to ECHECK for eCheck transactions—otherwise optional | should be set to ECHECK for eCheck transactions—otherwise optional |
| x_Password | valid password for the Login ID specified in x_Login | N/A | required for x_Type values of CREDIT, VOID, CAPTURE_ONLY, and PRIOR_AUTH_CAPTURE—otherwise optional | required for x_Type values of CREDIT, VOID, CAPTURE_ONLY, and PRIOR_AUTH_CAPTURE—otherwise optional |
| x_Phone | any string | required for all eCheck transactions and Wells Fargo SecureSource Merchants—otherwise optional | required for all eCheck transactions and Wells Fargo SecureSource Merchants—otherwise optional | required for all eCheck transactions and Wells Fargo SecureSource Merchants—otherwise optional |
| x_PO_Num | any string | optional | optional | optional |
| x_Receipt_Link_Method | LINK, POST, GET | optional | optional | optional |
| x_Receipt_Link_Text | any string ("Continue") | optional | optional | optional |
| x_Receipt_Link_URL | any valid URL (must also exist in Merchant Configuration) | optional | optional | optional |
| x_Recurring_Billing | TRUE, FALSE | optional | optional | optional |
| x_Rename | [OldVariableName], [NewVariableName] | optional | optional | optional |
| x_Ship_To_Address | any string | optional | optional | optional |
| x_Ship_To_City | any string | optional | optional | optional |
| x_Ship_To_Company | any string | optional | optional | optional |
| x_Ship_To_Country | any string | optional | optional | optional |
| x_Ship_To_First_Name | any string | optional | optional | optional |
| x_Ship_To_Last_Name | any string | optional | optional | optional |
| x_Ship_To_State | any string | optional | optional | optional |
| x_Ship_To_Zip | any string | optional | optional | optional |
| x_Show_Form | PAYMENT_FORM (do not use this field if you do not want to show the system’s payment form) | optional | N/A | optional |
| x_State | any string | required for all eCheck transactions and Wells Fargo SecureSource Merchants—otherwise optional | required for all eCheck transactions and Wells Fargo SecureSource Merchants—otherwise optional | required for all eCheck transactions and Wells Fargo SecureSource Merchants—otherwise optional |
| x_Tax | any valid amount | Required for all eCheck transactions and Wells Fargo SecureSource Merchants ($0 is valid)—otherwise optional | Required for all eCheck transactions and Wells Fargo SecureSource Merchants ($0 is valid)—otherwise optional | Required for all eCheck transactions and Wells Fargo SecureSource Merchants ($0 is valid)—otherwise optional |
| x_Tax_Exempt | TRUE, FALSE | optional | optional | optional |
| x_Test_Request | TRUE, FALSE | optional | optional | optional |
| x_Trans_ID | any valid Transaction ID | Required for CREDIT and PRIOR_AUTH_CAP-TURE type transactions, otherwise optional | Required for CREDIT and PRIOR_AUTH_CAP-TURE type transactions, otherwise optional | Required for CREDIT and PRIOR_AUTH_CAP-TURE type transactions, otherwise optional |
| x_Type | AUTH_CAPTURE, AUTH_ONLY, CAPTURE_ONLY, CREDIT, VOID, PRIOR_AUTH_CAPTURE | optional--see the table below for more information | optional--see the table below for more information | optional--see the table below for more information |
| x_Use_Fraudscreen | (Reserved for future use) | Not yet supported | ||
| x_Version | 2.5, 3.0, 3.1 | Optional, but strongly recommended to be set to 3.0 or 3.1 to inform the system that you are passing 3.0 or 3.1 code. | Optional, but strongly recommended to be set to 3.0 or 3.1 to inform the system that you are passing 3.0 or 3.1 code and are expecting a 3.0 or 3.1 response. | Optional, but strongly recommended to be set to 3.0 or 3.1 to inform the system that you are passing 3.0 or 3.1 code and are expecting a 3.0 or 3.1 response. |
| x_Zip | any string | required for all eCheck transactions and Wells Fargo SecureSource Merchants—otherwise optional | required for all eCheck transactions and Wells Fargo SecureSource Merchants—otherwise optional | required for all eCheck transactions and Wells Fargo SecureSource Merchants—otherwise optional |
The following table provides a description of the several different transaction types for use with the x_Type form field.
| Type | Description |
|---|---|
| AUTH_CAPTURE | Auth-Capture is the normal transaction method; a transaction is sent to the system for approval, the transaction is approved, the merchant is notified of the approval, and the transaction automatically settles at the end of the business day without any further action by the merchant. |
| AUTH_ONLY | Auth-Only stands for Authorization-Only and means obtaining an authorization for a certain amount on a customer's credit card without actually charging the card. If the money is not captured within 30 days, the transaction will expire. |
| PRIOR_AUTH_CAPTURE | A Prior-Auth-Capture transaction is used to capture funds authorized previously using an Auth-Only transaction. Prior-Auth-Capture is really just an operation on an already existing transaction. Prior-Auth-Capture should only be used on Auth-Only transactions processed using the system. |
| CAPTURE_ONLY | Capture-Only transactions are used when an authorization-only is obtained through any means other than the system. |
| CREDIT | Credits are not processed in real time, but are submitted at settlement time with other transactions. |
| VOID | Voiding a transaction prevents a charge to a credit card/bank account from occurring. Voids are performed on existing transactions that have yet to be settled. |
The ADC methods provide a way of connecting to the gateway in which a merchant's server can integrate directly with the system to send transactions and receive responses. The table below provides a reference to all of the fields of information that are returned by one of the Automated Direct Connect (ADC) methods.
The ADC Relay Response method will return an HTTP(S) form POST containing the following fields to a script written by the merchant to complete the purchasing process and/or generate an HTML page to be displayed to the customer. The URL of this script is designated using the x_ADC_URL field, and must be set as one of the Valid ADC or Receipt Link URLs in the URL Manager section of the Settings menu. This post will occur after the transaction is processed, and the response given by the merchant's script will be displayed to the customer as the result of the transaction. It is possible that none of the system's pages will ever be displayed using this method.
The ADC Direct Response method will return a simple comma delimited string (field1,field2,field3, etc.) containing the fields from the following table in the order indicated below. This format can be changed in the Automated Direct Connect (ADC) Settings section of the Settings menu. A developer would parse this string to obtain the desired information.
IMPORTANT: The version 3.0 response string is different from the version 3.1 response string. The version 3.0 response string contains system fields 1-38 as shown below and echoes merchant defined fields from field 39 on, in the order the system received them. The version 3.1 response string contains 68 system fields with field number 39 representing the x_cvv2_resp_code. In the version 3.1 response string, merchant defined fields are echoed from field 69 on. Merchants wishing to use the CVV2 response code must switch to response string version 3.1. The response string version is set from within the Merchant Menu Interface.
To change the Response String Version, do the following:
| Position in Direct Response return | Field Name | Description |
|---|---|---|
| 1 | x_response_code | Indicates the result of the transaction. 1 = Approved 2 = Declined 3 = Error |
| 2 | x_response_subcode | A code used by the system for internal transaction tracking. |
| 3 | x_response_reason_code | A code representing more details about the result of the transaction. |
| 4 | x_response_reason_text | Brief description of result, which corresponds with the Response Reason Code. |
| 5 | x_auth_code | Six-digit approval code. |
| 6 | x_avs_code | Indicates the result of Address Verification System (AVS) checks. A = Address (Street) matches, ZIP does not E = AVS error 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 = Exact AVS Match Y = Address (Street) and 5 digit ZIP match Z = 5 digit ZIP matches, Address (Street) does not |
| 7 | x_trans_id | This number identifies the transaction in the system, and can be used to submit a modification of this transaction at a later time via HTTP(S) form POST (such as voiding the transaction, or capturing an Auth Only transaction). |
| 8 | x_invoice_num | Echoed from form input values. |
| 9 | x_description | Echoed from form input values. |
| 10 | x_amount | Echoed from form input values. |
| 11 | x_method | Echoed from form input values. |
| 12 | x_type | Echoed from form input values. |
| 13 | x_cust_id | Echoed from form input values. |
| 14 | x_first_name | Echoed from form input values. |
| 15 | x_last_name | Echoed from form input values. |
| 16 | x_company | Echoed from form input values. |
| 17 | x_address | Echoed from form input values. |
| 18 | x_city | Echoed from form input values. |
| 19 | x_state | Echoed from form input values. |
| 20 | x_zip | Echoed from form input values. |
| 21 | x_country | Echoed from form input values. |
| 22 | x_phone | Echoed from form input values. |
| 23 | x_fax | Echoed from form input values. |
| 24 | x_email | Echoed from form input values. |
| 25 | x_ship_to_first_name | Echoed from form input values. |
| 26 | x_ship_to_last_name | Echoed from form input values. |
| 27 | x_ship_to_company | Echoed from form input values. |
| 28 | x_ship_to_address | Echoed from form input values. |
| 29 | x_ship_to_city | Echoed from form input values. |
| 30 | x_ship_to_state | Echoed from form input values. |
| 31 | x_ship_to_zip | Echoed from form input values. |
| 32 | x_ship_to_country | Echoed from form input values. |
| 33 | x_tax | Echoed from form input values. |
| 34 | x_duty | Echoed from form input values. |
| 35 | x_freight | Echoed from form input values. |
| 36 | x_tax_exempt | Echoed from form input values. |
| 37 | x_po_num | Echoed from form input values. |
| 38 | x_MD5_hash | Generated by the system and to be validated by merchant for added security. |
| 39 (v3.1 only) | x_cvv2_resp_code | Indicates the results of CVV2 verification: M = Match N = No Match P = Not Processed S = Should have been present U = Issuer unable to process request |
| 40 (v3.1 only) | (Reserved for future use.) | |
| 41 (v3.1 only) | (Reserved for future use.) | |
| 42 (v3.1 only) | (Reserved for future use.) | |
| 43 (v3.1 only) | (Reserved for future use.) | |
| 44 (v3.1 only) | (Reserved for future use.) | |
| 45 (v3.1 only) | (Reserved for future use.) | |
| 46 (v3.1 only) | (Reserved for future use.) | |
| 47 (v3.1 only) | (Reserved for future use.) | |
| 48 (v3.1 only) | (Reserved for future use.) | |
| 49 (v3.1 only) | (Reserved for future use.) | |
| 50 (v3.1 only) | (Reserved for future use.) | |
| 51 (v3.1 only) | (Reserved for future use.) | |
| 52 (v3.1 only) | (Reserved for future use.) | |
| 53 (v3.1 only) | (Reserved for future use.) | |
| 54 (v3.1 only) | (Reserved for future use.) | |
| 55 (v3.1 only) | (Reserved for future use.) | |
| 56 (v3.1 only) | (Reserved for future use.) | |
| 57 (v3.1 only) | (Reserved for future use.) | |
| 58 (v3.1 only) | (Reserved for future use.) | |
| 59 (v3.1 only) | (Reserved for future use.) | |
| 60 (v3.1 only) | (Reserved for future use.) | |
| 61 (v3.1 only) | (Reserved for future use.) | |
| 62 (v3.1 only) | (Reserved for future use.) | |
| 63 (v3.1 only) | (Reserved for future use.) | |
| 64 (v3.1 only) | (Reserved for future use.) | |
| 65 (v3.1 only) | (Reserved for future use.) | |
| 66 (v3.1 only) | (Reserved for future use.) | |
| 67 (v3.1 only) | (Reserved for future use.) | |
| 68 (v3.1 only) | (Reserved for future use.) | |
| 39 (v3.0) or 69 (v3.1) | any merchant defined fields in the order the system received them | Echoed from form input values. |