Authorize.Net Integration Guide

This document is a comprehensive reference all for the different forms of interaction with the Authorize.Net covering the WebLink method of sending customers to the system's Payment Form, as well as the more advanced methods of processing transactions directly through the system, such as Automated Direct Connect (ADC) and Batch Processing.

Included is also information on Adress Verification System (AVS) and setting the account on Test Mode.

Basic integration concepts

At its most basic level, integration between a merchant's Web site and the system is performed by constructing an HTML form, which does an HTTPS POST to https://secure.authorize.net/gateway/transact.dll. In this form there are several fields that are passed to the system to indicate whatever information the system needs to know about the transaction. Some of this information is required, such as the Login ID and the transaction amount. Other information is optional, but may be specified in the HTML form either to avoid causing the customer to need to re-enter the information elsewhere or to prevent the customer from changing the information. For full details on which form fields are required and which are optional, please see Appendix B - Functional Reference.

Form construction

It is assumed that a developer who is intending integration and desires a level of control over the user experience will already have knowledge of how to construct HTML forms.

ALL forms used to integrate with the system will be submitted to the URL: https://secure.authorize.net/gateway/transact.dll using the HTTPS POST method. The basic HTML tags used to construct such a form would be written as follows:

<FORM METHOD=POST ACTION="https://secure.authorize.net/gateway/transact.dll"></FORM>

Any form fields that needed to be sent to the system would be enclosed as <INPUT> fields within the opening <FORM> tag and the closing </FORM> tag. For example, a form that contained a merchant’s login ID would look like this:

<INPUT TYPE=HIDDEN NAME="x_Login" VALUE="your login ID goes here">

There are a couple of things to note about the sample line above if you're unfamiliar with sample HTML. The <INPUT> is the tag and it does not need a closing tag (unlike <FORM> which needs a closing tag </FORM>). TYPE in the sample above is linked with HIDDEN and not with INPUT. If you think of the equals sign (=) as representative of the word “of,” then the phrase makes sense: “TYPE of HIDDEN.” In this case it means the information being passed to the gateway server would be hidden from the customer (since the information that is being passed is the merchant’s Login ID). The NAME="x_Login" is the category, or field, of information that is being passed, in this case the Login ID of the merchant. And the VALUE="your login ID goes here" is where you would put your merchant login ID (in place of the “your login ID goes here” text but still within the double quotes). The NAME VALUE pair is one of the things that the gateway server looks for when a transaction is submitted. If part of the NAME VALUE pair is not present or improperly formed, the transaction will not go through.

Other things to note

WebLink

The real power and flexibility of the Authorize.Net system is seen in its integration with the World Wide Web. The quickest and easiest way to integrate a Web page with the system is by using the WebLink method.

At its most basic level, interaction between a web page and the system takes the following form:

  1. A customer navigates through a merchant's Web site, selecting what it would like to purchase.
  2. The customer fills in the information that is needed to begin processing the transaction, or the merchant's Web site provides this information during the shopping process. The information is included in an HTML form that has been set up by the merchant to post the information in the form to the Authorize.Net system.
  3. The customer is then connected directly to the Authorize.Net system, which displays the Payment Form. The Payment Form provides a place for the customer to enter any information that is needed which wasn't provided by the merchant's form. When submitted, the Payment Form forwards the customer’s credit card or bank account information to the Authorize.Net system. Authorize.Net forwards this information to the necessary processors, which then validate the credit card or bank account information.
  4. If the transaction is not approved, the result is displayed to the customer, and he or she is given the opportunity to correct any information that may have been submitted in error. If the transaction is approved, a Receipt Page is shown to the customer, which the customer can print out or save for its records.
  5. The Receipt Page that is shown to the customer can have a link back to the merchant's site to complete the transaction.
  6. Unless otherwise specified, a receipt will be emailed to the customer, as well as to the merchant.

Examples of connecting to the Authorize.Net system using WebLink

The Authorize.Net system supports many variations on the WebLink method of connecting to the system. To provide the link between a merchant's Web site and the system, the merchant creates an HTML form that performs an HTTPS form POST to the system. All interaction with the system is done by posting information to https://secure.authorize.net/gateway/transact.dll. The fields that are posted by this form must include the required fields as specified in the Functional Reference, but may also include many optional fields to customize the behavior and appearance of WebLink. The following are some examples of HTML code that can be customized and inserted into a merchant's own Web site to provide easy ways to integrate the Web site with the system.

Example 1 - Bare minimum requirements

The following fields are required for any form sent through WebLink:

The following HTML code represents the bare minimum that would need to be inserted into a page to provide a connection to the system:

<FORM METHOD=POST ACTION="https://secure.authorize.net/gateway/transact.dll">
<INPUT TYPE=HIDDEN NAME="x_Version" VALUE="3.0">
<INPUT TYPE=HIDDEN NAME="x_Login" VALUE="your login ID goes here">
<INPUT TYPE=HIDDEN NAME="x_Show_Form" VALUE="PAYMENT_FORM">
<INPUT TYPE=HIDDEN NAME="x_Amount" VALUE="amount goes here">
<INPUT TYPE=SUBMIT VALUE="Click here for secure payment form">
</FORM>

The result of the above HTML code snippet is a button, which when clicked, will take the user to the system's Payment Form, which will be already set up to charge a predetermined amount. The Payment Form will get the rest of the necessary information from the customer, such as card number and expiration date, and process the transaction.

This type of connection would not include any of the other fields that might be desired, such as names, customer IDs, or descriptions.

Example 2 - Suggested minimum requirements

The following HTML code provides the ability to pass a little more information to the system which will then be included in the Payment Form or Receipt Page. The new fields shown below include:

<FORM METHOD=POST ACTION="https://secure.authorize.net/gateway/transact.dll">
<INPUT TYPE=HIDDEN NAME="x_Version" VALUE="3.0">
<INPUT TYPE=HIDDEN NAME="x_Login" VALUE="your login ID goes here">
<INPUT TYPE=HIDDEN NAME="x_Show_Form" VALUE="PAYMENT_FORM">
<INPUT TYPE=HIDDEN NAME="x_Amount" VALUE="amount goes here">
<INPUT TYPE=HIDDEN NAME="x_Cust_ID" VALUE="a customer identification number or string goes here">
<INPUT TYPE=HIDDEN NAME="x_Description" VALUE="description of transaction">
<INPUT TYPE=HIDDEN NAME="x_Invoice_Num" VALUE="invoice number goes here">
<INPUT TYPE=SUBMIT VALUE="Click here for secure payment form">
</FORM>

The result of this HTML code snippet is a button, which when clicked, sends the customer to the system's Payment Form with some more information than in the previous example. The Payment Form will already display information about the description, the customer ID number, and the invoice number, and this information will appear on the receipt and e-mail confirmation.

Example 3 - Using a form to gather information

The following HTML code demonstrates the ability to send additional information to the system, and have some of that information specified by the customer. The new fields shown below include:

<FORM METHOD=POST ACTION="https://secure.authorize.net/gateway/transact.dll">
<INPUT TYPE=HIDDEN NAME="x_Version" VALUE="3.0">
<INPUT TYPE=HIDDEN NAME="x_Login" VALUE="your login ID goes here">
<INPUT TYPE=HIDDEN NAME="x_Show_Form" VALUE="PAYMENT_FORM">
<INPUT TYPE=HIDDEN NAME="x_Amount" VALUE="amount goes here">
<INPUT TYPE=HIDDEN NAME="x_Cust_ID" VALUE="a unique customer ID goes here">
<INPUT TYPE=HIDDEN NAME="x_Description" VALUE="description of transaction">
<INPUT TYPE=HIDDEN NAME="x_Invoice_Num" VALUE="invoice number goes here">
Enter your first name:
<INPUT TYPE=TEXT NAME="x_First_Name"><BR>
Enter your last name:
<INPUT TYPE=TEXT NAME="x_Last_Name"><BR>
Enter any special shipping instructions:
<INPUT TYPE=TEXT NAME="Shipping_Instructions"><BR>
<INPUT TYPE=SUBMIT VALUE="Click here for secure payment form">
</FORM>

The result of this HTML code snippet is a page that displays a form allowing the customer to specify their name and any specific shipping instructions they have. The x_First_Name and x_Last_Name fields are normal fields recognized by the system. The Shipping_Instructions field is not a field recognized by the system, and so it is treated as a user field. You can also use system-recognized fields to have the user fill out a shipping address with normal shipping information.

User fields

User fields can be named anything that doesn't conflict with one of the system's fields, and can contain any information that might be useful in the transaction. These user fields will be echoed back with the results of the transaction, and will be displayed on the merchant's receipts; they will not be displayed on the customer's receipts.

Many more fields can be sent to the system in this way. For complete details on the operation of all of the fields, please see Appendix B - Functional Reference.

Customizing the Payment Form

Global modifications can be made to the Payment Form through the Merchant Menu, including appearance and which fields are viewable, editable, and required. In addition to these global options, per transaction changes to the appearance of the payment form can be made by sending the proper fields to the system in the WebLink form. These per transaction changes will override any global settings made through the Merchant Menu.

Disabling the Payment Form

If the x_Show_Form field is NOT sent with a value of PAYMENT_FORM, the payment form will not be displayed. Instead, the transaction will be processed based on all of the information that has been included in the WebLink form. It is important to remember that if the Payment Form is not displayed, the WebLink form that is sent to the system must contain all of the information needed to process the transaction, including expiration date and card number.

Customizing the Receipt Page

The Receipt Page can use many of the customizable fields as outlined in "Customizing the Payment Form." Note that it is NOT possible to disable the receipt page using the WebLink methods. If it is necessary to not show the customer a receipt page, that can be accomplished through one of the Automated Direct Connect (ADC) methods. Some Receipt Page specific fields include:

Receipt link

Since the WebLink method directs customers away from a merchant's Web site, and to the system's site for payment processing, an effective way to return the customer to the merchant's Web site must be provided.

The Receipt Link is included on the Receipt Page to provide that method of returning customers to a merchant's Web site. The Receipt Link settings can be set globally through the Merchant Menu. In addition to these global options, per transaction changes to the Receipt Link settings can be made by sending the proper fields to the system in the WebLink form.

Customizing the e-mail receipt

Global modifications can be made to the e-mail receipt that is e-mailed to customers upon the completion of a transaction. In addition to these global options, per transaction changes to the e-mail receipt settings can be made by sending the proper fields to the system in the WebLink form. These per transaction changes will override any global settings made through the Merchant Menu.

Other system-recognized fields can be found in Appendix B - Functional Reference.

ADC Choices

ADC and other forms of interaction

The system supports many other forms of integration, including the Automated Direct Connect (ADC) methods, which bypass the Payment Form and Receipt Page and permit much more advanced integration between a merchant's server and the system.

The Automated Direct Connect (ADC) methods of integration with the system can provide much greater flexibility than the WebLink method of integration. Using the ADC methods, a merchant can connect their server directly to the system's gateway server to process transactions through the system in real time. With proper use of these methods, a merchant can retain full control of the data that is used in the processing of the transaction, and keep the customer on the merchant’s own Web site during the whole transaction process if so desired.

The ADC methods differ from the WebLink method in that they generally require some sort of programming ability to be implemented. CGI scripts or server programs can be written in many different languages and environments to implement ADC connectivity.

Difference between ADC methods

Two types of ADC integration methods are available:

  1. ADC Relay Response
  2. ADC Direct Response

While both are Automated Direct Connect methods, they are as different as chalk and cheese. Both require a greater familiarity with Web programming than the WebLink process.

In ADC Relay Response, the customer's interaction is with the system's gateway server. The merchant's Web page initiates a transaction by creating an HTML form that posts the required transaction information to the gateway server. The customer provides additional information to the gateway server if it is desired for them to do so. The gateway server processes the transaction, and then transmits the results of the transaction to the merchant's server via HTTP(S) form POST. The merchant's server can respond back in whatever way it sees fit based on the results of the transaction. The response back from the merchant's server is sent back to the gateway server, which then relays it on to the customer's browser as if it came directly from the gateway server.

In ADC Direct Response, a customer's Web browser makes a secure connection to a merchant's server and transmits all of the information necessary to process a transaction. The merchant's server connects securely to the system's gateway server, and transmits all of the transaction information via HTTP(S) form POST to the gateway server for processing. The gateway server returns the results of the transaction processing to the merchant's server. The merchant's server can determine from the results of the transaction how to proceed with the customer, and then returns a response to the customer accordingly.

When to use which method

Both ADC methods provide ways for developers to integrate transaction processing into whatever programs or databases they may desire. However, one method might be better for certain situations than another.

Most likely, the main factor that determines which ADC method to use will be the ability to make secure encrypted connections. The ADC Direct Response method will generally be more desirable than the ADC Relay Response method because of the greater control it gives developers over the whole transaction process. However, a developer won't be able to implement the ADC Direct Response method unless they can provide a secure server side connection and initiate a secure client side connection when they send the transaction information to the gateway server. Implementing client side secure connections is made easier by using some of the readily available tools and libraries for implementing protocols like SSL. However, implementing client side security can still be a daunting prospect for many developers. If it's not possible to create a secure connection on both the server and client sides of the link, the ADC Relay Response method provides an excellent alternative where sensitive data such as credit card numbers is only transmitted across the secure link between the system's gateway server and the customer's browser.

In brief:

  1. If you can write a script that can process information sent via an HTTP(S) form POST, then you might want to consider using ADC Relay Response; if you can't do that, use WebLink.
  2. If you can write a script that can process information sent via an HTTP(S) form POST, AND you can provide a secure server side connection and initiate a secure client side connection, then you might want to consider using ADC Direct Response.

ADC Relay Response

To implement the ADC Relay Response method, a developer would design an HTML form that would post all of the information needed to process a transaction to https://secure.authorize.net/gateway/transact.dll. The customer could continue the transaction on the Payment Form or not, just as in the WebLink method. The fields contained in the posted form would be all of the information necessary to process a transaction, plus a couple of additional fields:

Once the gateway server gets all of the transaction information, the transaction is processed. Once the transaction is processed, an HTTP(S) form POST is sent to the URL specified in x_ADC_URL with the results of the transaction. Whatever script or program receives the results at that specified URL could then decide what type of response to return. Any response returned will be relayed to the browser as if it came directly from the gateway server.

Example - Minimum Requirements for ADC Relay Response

The following are the minimum requirements for an ADC Relay Response transaction. It assumes you are using the generic Authorize.Net payment form. If you do not wish to use the Authorize.Net payment form, you would then need to ask for the user's card number and expiration date.

<FORM METHOD=POST ACTION="https://secure.authorize.net/gateway/transact.dll">
<INPUT TYPE=HIDDEN NAME="x_Version" VALUE="3.0">
<INPUT TYPE=HIDDEN NAME="x_Login" VALUE="your login ID goes here">
<INPUT TYPE=HIDDEN NAME="x_Show_Form" VALUE="PAYMENT_FORM">
<INPUT TYPE=HIDDEN NAME="x_Amount" VALUE="amount goes here">
<INPUT TYPE=HIDDEN NAME="x_ADC_Relay_Response" VALUE="True">
<INPUT TYPE=HIDDEN NAME="x_ADC_URL" VALUE="any valid URL">
<INPUT TYPE=SUBMIT VALUE="Click here for secure payment form">
</FORM>

NOTE: The line <INPUT TYPE=HIDDEN NAME="x_Show_Form" VALUE="PAYMENT_FORM"> is optional. Using it indicates you will be using the generic payment form provided by the system. If you do not use this line, you MUST acquire the user's card number and card expiration date for your own payment form.

Tips and Special Requirements

Must use absolute URLs. Since the HTML code that is returned to the browser appears to come from the gateway server, any links to images need to be absolute URLs, with the full path to the server on which the images reside. If relative URLs are used, the customer's browser will try to load the images from the gateway server, which will fail.

x_ADC_URL can't be just a Web page unless the server on which it resides can handle a POST to that URL.
It is intended that the URL specified in x_ADC_URL will be a script or something else that can interactively parse the information that is POSTed to it. If a static response is desired for every transaction, that URL can be a plain HTML page, but the merchant's Web server will need to be configured to allow the POST method to plain HTML pages.

Don't use frames on your pages because even though the Payment Form used will be secure, the lock icon on the user's taskbar will key off the surrounding frame and not off the Payment Form. Thus, to the user, the page will not look secure, thus reducing potential sales.

Don't use redirects in your Relay Scripts as the information may not be transferred properly.

HTTP headers are replaced. When the merchant's response is relayed back to the customer, anything that is in the HTTP headers will be replaced. This means if a developer is relying on custom information to be in these headers, such as Cookies, their implementation will most likely fail.

Use only port 443 for Relay Response information transfers for reasons of security.

Sample scripts are available for ADC Relay Response and ADC Direct Response implementation. These scripts have been provided by third party developers and Authorize.Net does not provide support for these scripts. But these scripts may ease some of your development worries.

ADC Direct Response

To integrate a merchant's system with the payment system using the ADC Direct Response method, a developer MUST be able to provide server side as well as client side security for the connection. A developer would also need to be able to write scripts or develop programs for their Web server to provide the necessary integration.

To implement the ADC Direct Response method:

  1. A developer would design a script that would securely obtain all of the information needed to process a transaction.
  2. The developer would then initiate a secure HTTPS form POST from their server to https://secure.authorize.net/gateway/transact.dll. To the gateway server this connection would appear the same way as if it were coming directly from a Web browser.
  3. The system would process the transaction and directly respond with the results to the merchant, who may then show whatever results necessary to the user, who perceives the information to have come direct from the merchant.

The fields contained in the posted form would be all of the information necessary to process a transaction, plus a couple of additional fields:

The default delimiting character and the default encapsulation character, if used, can be changed. If you have scripts on your end that will handle the transaction information, and your scripts require a specific character as the delimiter, you can change this in your Merchant Menu settings. You can also change this setting on a per-transaction basis by sending the following variable: x_ADC_Delim_Character with a VALUE of whatever character you would like to use.

Example - Minimum Requirements for ADC Direct Response

The minimum information present in the script you write for using Direct Response is listed below. You cannot use our payment form or receipt page when using the Direct Response method, thus you must ask for the Card Number and Expiration Date. You must be able to establish a secure socket connection and provide both client-side and server-side encryption when using this method. Your script must include the following name/value pairs.

NameValue
x_LoginYour Login ID
x_ADC_URLFalse
x_ADC_Delim_DataTrue
x_AmountAmount of purchase calculated on your end
x_Card_NumCustomer's card number
x_Exp_DateCustomer's card expiration date

Tips and Special Requirements

You cannot use the generic Authorize.Net Payment Form or Receipt Page with ADC Direct Response. The system provides the flexibility and power for the merchant to control the transaction and to provide their own custom payment forms and receipt pages.

Don't use frames on your pages because even though the Payment Form used will be secure, the lock icon on the user's taskbar will key off the surrounding frame and not off the Payment Form. Thus, to the user, the page will not look secure, thus reducing potential sales.

Use only port 443 for Direct Response information transfers for reasons of security.

Sample scripts are available for ADC Relay Response and ADC Direct Response implementation. These scripts have been provided by third party developers and Authorize.Net does not provide support for these scripts. But these scripts may ease some of your development worries.

AVS (Address Verification System)

The Address Verification System (AVS) is a feature automatically available to merchants through the Authorize.Net system for the purpose of verifying that the cardholder's address and zip code provided at the time of the transaction "match" the actual address as registered with the cardholder's card issuing bank. While a full address would normally be considered to be the name, address, city, state, and zip code for the purposes of mailing, with the AVS system only the address (number part only) and the five or nine digit zip code are actually verified.

Bankcard processors provide the Address Verification System to aid in the detection of fraud. In the Internet context, customers fill out an online payment form on your Web site with their credit card information including the card billing address. The processing network (e.g., FDC, Vital, Nova, GPS, Paymentech) compares the billing address supplied online with the billing address on file at the credit card issuing bank. From this comparison, the processing network sends an AVS response code to Authorize.Net.

Authorize.Net takes the AVS response code from the processing network and reports it to the merchant. Depending upon the response, the merchant may wish to approve the transaction, reject the transaction, or follow other lines of logic. With so many possible reasons as to why an address and zip code may not match, a merchant is not required to refuse a transaction because the AVS response was a mismatch. With most banks and merchant service providers, use of the AVS system is required in order to avoid non-qualified transaction surcharges (typically an additional 1%). There are two main reasons for voiding transactions that have an AVS mismatch:

  1. Accepting a transaction involving an AVS mismatch response may or may not cause a non-qualified transaction surcharge according to your merchant agreement with your bank or merchant service provider.
  2. The AVS mismatch may indicate fraud.

How to use AVS

AVS responses are automatically sent when transactions with address information are processed. If you decide to use AVS, make sure that your merchant service provider is aware of this. This will enable your merchant service provider to receive the AVS information. If the transactions are processed through one of the integration methods such as WebLink or ADC, the AVS response will be in the form of an AVS code, which is in the following format:

AVS Response CodeMeaning
AAddress (Street) matches, ZIP does not
EAVS error
NNo Match on Address (Street) or ZIP
PAVS not applicable for this transaction
RRetry - System unavailable or timed out
SService not supported by issuer
UAddress information is unavailable
W9 digit ZIP matches, Address (Street) does not
XExact AVS Match
YAddress (Street) and 5 digit ZIP match
Z5 digit ZIP matches, Address (Street) does not

When transactions are viewed as part of a batch in the Transaction Activity area of the Merchant Menu, the full AVS response is displayed, rather than just the code.

Testing

Test Mode

Test Mode is a special mode of interacting with the system that is useful during the initial setup phase, where a merchant may want to test its setup without processing live card data. To set an account to Test Mode, click the Test Mode checkbox in the General Settings area of the Settings menu.

When an account is set to Test Mode, all transactions appear to be processed as real transactions, with the exception that a payment processor is never contacted, and so all transactions with valid card numbers are approved. Transactions submitted in Test Mode are not stored on the system, and will not appear in any reports or lists. It is strongly suggested to leave an account in Test Mode until the merchant is sure that all aspects of its interaction with the Authorize.Net system are functioning properly, so as to avoid possibly incorrectly charging real credit cards.

When an account is not in Test Mode, it is required to make a secure, encrypted connection with the system. This is necessary to protect the integrity of the live credit card data that is being sent across a public network. When an account is in Test Mode, it is assumed that real credit card data is not being used, and so it is not required that connections be secure and encrypted. It is therefore the responsibility of the merchant to ensure that they are not using real credit card data in their testing unless a secure, encrypted connection to the system is being made.

One other key difference between Test Mode and normal usage of the system is that batch processing is not supported in Test Mode. Since the system checks the format of the batch file as it is being uploaded, it becomes impossible to upload incorrect data. This makes batch uploading unnecessary in Test Mode.

x_Test_Request

If an account is not in Test Mode, and it is necessary to perform a test on a single transaction, it is possible to send the x_Test_Request="TRUE" field as part of the transaction. Sending this field set to TRUE overrides the setting of Test Mode in the merchant's settings, and invokes Test Mode for the particular transaction with which the field is sent. Note that if Test Mode is turned on in a merchant's settings, that setting can't be overridden by sending x_Test_Request="FALSE".

Test credit card numbers

Because a payment processor is never contacted in test mode, all properly formatted transactions appear to be approved. There are many situations, however, where a developer will need the system not to approve transactions or to generate errors in order to test all possible responses from the system.

Any of the following card numbers can be used to run tests on your Authorize.Net account. It must be noted that these are not real card accounts, and will not generate an approval if your account is in live mode. They will return a decline in live mode, and an approval in test mode.

Use any expiration date after the current day's date.

370000000000002American Express Test Card
6011000000000012Discover Test Card
5424000000000015MasterCard Test Card
4007000000027Visa Test Card

There is also a testing card number that can be used to generate errors. THIS CARD IS INTENDED TO PRODUCE ERRORS, and should only be used if that is your intent.

To cause the system to generate a specific error, send a transaction with the card number 4222222222222, and an amount equal to the number of the error you want the system to return,

For example, if a transaction is sent to the system in test mode with a credit card number of 4222222222222, and an amount of 12 dollars, the system will respond with error 12, "Authorization Code is required but is not present."

Batch Uploading

Aside from the automated ways of integrating with the system, batches of transactions can be uploaded to the system for processing. All transactions contained in the uploaded file are processed in the currently open batch and are settled with any other transactions pending in that same batch.

One way this capability can be useful is for merchants who collect their transaction information over the course of the day, and want to upload their transactions for processing all at one time.

This capability can also be useful for merchants who have recurring transactions, such as monthly subscription fees. Each month a merchant could upload a file containing all of their customers' transaction information to bill their customers for another month.

In addition to being able to upload batches of transactions, the system allows a merchant to download settlement batches as a file to their own computer.

Batch uploads configuration

The file format of an uploaded batch file is completely customizable. By configuring different settings in the system, a merchant can designate which fields the system requires to be included in the file, the order of those fields, the delimiting character that separates the fields, and the encapsulation character that encloses all of the data within a field. All of the settings relating to configuration of the batch upload file format can be found in the Transaction Batch Upload Settings item of the Settings area of the Merchant Menu.

Default file format

Unless otherwise changed in the Transaction Batch Upload Settings item of the Settings area of the Merchant Menu, the default format of a batch upload file is a comma-delimited file. Each field in the file is encapsulated by a beginning and ending double quote character ("). The default order of the fields is as follows:

Position in Default File FormatField NameEquivalent Form Field Name (Appendix B)Notes
1Invoice Numberx_Invoice_Num 
2Descriptionx_Description 
3Amountx_AmountUse positive amount for Credit transactions of type CREDIT
4Payment Methodx_MethodPossible Values: CC or ECHECK
5Transaction Typex_TypeMust be exactly one of: AUTH_CAPTURE, AUTH_ONLY, CAPTURE_ONLY, CREDIT, VOID, PRIOR_AUTH_CAPTURE
6Authorization Codex_Auth_CodeRequired and necessary only for CAPTURE_ONLY type transactions
7Transaction IDx_Trans_IDRequired and necessary only for CREDIT, VOID or PRIOR_AUTH_CAPTURE type transactions
8Credit Card Numberx_Card_Num 
9Credit Card Expiration Datex_Exp_DateMust be either mmyy or mm/yy
10Bank Account Numberx_Bank_Acct_NumFor ECHECK method transactions—up to 17 digits
11Bank ABA Routing Codex_Bank_ABA_CodeABA Transit/Routing number for ECHECK method transactions—must be 9 digits
12Bank Namex_Bank_NameFor ECHECK method transactions
13Customer IDx_Cust_ID 
14Customer First Namex_First_Name 
15Customer Last Namex_Last_Name 
16Customer Companyx_Company 
17Customer Addressx_AddressSuggested for Address Verification System (AVS)
18Customer Cityx_City 
19Customer Statex_State 
20Customer ZIPx_ZipSuggested for Address Verification System (AVS)
21Customer Phonex_Phone 
22Customer Faxx_Fax 
23Customer E-Mailx_EmailIf provided, customer will receive a standard email receipt, assuming that your account is configured to send customers an email receipt

Note: Credits submitted via batch upload will be accepted by the system but may then later be declined. These declines will appear on the Declined Items report.

Note: Minimum field requirements apply to batch uploaded transactions. Please see Appendix B - Functional Reference for more information regarding transaction specific field requirements.

Note: Batch Uploads are limited to 10,000 transactions per batch.

Sample batch upload file

Following is an example of a properly formatted batch upload file using the default file format of comma delimited and double-quote encapsulated fields:

 "11111","Door welding kit","99.00","CC","AUTH_CAPTURE", , ,"4111111111111111","0202", , , ,"BDUKE001","Bo" ,"Duke", ,"555 Duke Farm Road","Hazzard County","GA","30603","404-555-1234","404-555-4321","bo@dukefarm.com"
 "11112","Door unwelding kit","99.00","ECHECK","AUTH_CAPTURE",,,,,"3201456789","123456789","Bank of Hazzard", "LDUKE001","Luke","Duke",,"555 Duke Farm Road ","Hazzard County","GA","30603","404-555-1234","404-555-4321","luke@dukefarm.com"
 "11113","Subscription to weight loss plan","55.00","CC","AUTH_ONLY", , ,"4222222222222222","0202",,,,"JDUKE001" ,"Jesse","Duke",,"555 Duke Farm Road ","Hazzard County","GA","30603","404-555-1234","404-555-4321", "unclejesse@dukefarm.com"
 "11114","Refund for ill-fitting denim shorts","34.95","CC","CREDIT",,,"4333333333333333","0202",,,,"DDUKE001" ,"Daisy","Duke",,"555 Duke Farm Road ","Hazzard County","GA","30603","404-555-1234","404-555-4321", "daisy@dukefarm.com"
 "11115","Hair combs","19.95","CC","CAPTURE_ONLY",111111,,"4444444444444444","0202",,,, "CDUKE001","Coy","Duke", ,"555 Duke Farm Road ","Hazzard County","GA","30603","404-555-1234","404-555-4321","coy@dukefarm.com"
 "11116","Watch fob","19.95","CC","VOID",,654321,"4555555555555555","0202",,,,"VDUKE001","Vance","Duke",,"555 Duke Farm Road ","Hazzard County","GA","30603","404-555-1234","404-555-4321","vance@dukefarm.com"
 "11117","Dog Food","41.95","CC","PRIOR_AUTH_CAPTURE",,123456,"4666666666666666","0202", , , ,"RCOLTRANE001", "Rosco","Coltrane", "Hazzard County Sheriff's Department","Municipal Building, Suite 123","Hazzard County","GA","30603","404-555-9099","404-555-9098","rpcoltrane@hazzard.co.ga.us"

Other fields

Other fields that are not included in the default batch upload file, but can be configured to be included are listed in the following table.

Field NameEquivalent Form Field Name (Appendix B)Notes
Bank Account Typex_Bank_Acct_Type 
Customer Countryx_Country 
Shipping First Namex_Ship_To_First_Name 
Shipping Last Namex_Ship_To_Last_Name 
Shipping Companyx_Ship_To_Company 
Shipping Addressx_Ship_To_Address 
Shipping Cityx_Ship_To_City 
Shipping Statex_Ship_To_State 
Shipping ZIPx_Ship_To_Zip 
Shipping Countryx_Ship_To_Country 
Level 2 Taxx_TaxRequired for all eCheck transactions and Wells Fargo SecureSource Merchants ($0 is valid)—otherwise optional
Level 2 Dutyx_Duty 
Level 2 Freightx_FreightRequired for all eCheck transactions and Wells Fargo SecureSource Merchants ($0 is valid)—otherwise optional
Level 2 Tax Exemptx_Tax_Exempt 
Level 2 PO Numberx_PO_Num 
Currency Code x_Currency_CodeDefault is USD (US Dollars)
Customer IP Addressx_Customer_IPAdditional field required for Wells Fargo SecureSource Merchants only
Customer SSNx_Customer_Tax_IDAdditional field required for Wells Fargo SecureSource Merchants only
Customer Typex_Customer_Organization_TypeAdditional field required for Wells Fargo SecureSource Merchants only
Driver License Numberx_Drivers_License_NumAdditional field required for Wells Fargo SecureSource Merchants only
Driver License Statex_Drivers_License_StateAdditional field required for Wells Fargo SecureSource Merchants only
Driver License Date of Birthx_Drivers_License_DOBAdditional field required for Wells Fargo SecureSource Merchants only

Changing the file format

There are many situations where it might be advantageous to upload transaction information in a different format than the default file upload format. One example might be if transactions are being exported from a database. The file upload format of the system could be changed to mirror the file format of the exported transactions, eliminating any data conversion that might otherwise have to take place.

To change the file format of batch uploaded files, go to the Transaction Batch Upload Settings item of the Settings area of the Merchant Menu. In the Transaction Batch Upload Settings, four items can be changed:

Once any changes have been made to the Transaction Batch Upload Settings, click the "Submit" button to save the changes to the system.

Assembling the file

A file of transactions to upload to the system can be created by exporting transactions from another program, such as a database or spreadsheet program, or a program can be written to construct the file.

When constructing a file of transactions to upload, fields that have no information for a particular transaction (for example, credit card number for an eCheck transaction) should be represented with just the delimiting characters with no characters in between them. For example, if three fields needed to be included because of the way the file format is configured but information was only available for the first and third, a transaction using the default file format might be assembled like this: "data",,"data"

When the file has been assembled and stored on your local machine, it can be given any filename and extension that is meaningful to you. Most text files end with a .txt extension.

Uploading

The process of uploading a batch transaction file is initiated from the Batch Uploads area of the Merchant Menu. To upload a new file of transactions:

  1. Go to the Uploaded Transaction Batch Files section.
  2. Click the radio button next to Upload a batch of new transactions and press the View button. A page will appear with an input field for the path and filename of the file to be uploaded.
  3. Click the Browse button to select a file on your local system.
  4. Once the correct file has been selected, click the Upload Batch File button to start the upload process.

Data Validation

As the file is being uploaded to the system, various checks are performed to determine that the file contains usable transaction data that the system will be able to process. The system will check to make sure that the correct number of fields is in each line, as well as check to see that the right types of data are in each field. If any errors in the file are encountered, the upload process will be aborted, and the system will display which lines had errors so that the file can be corrected and re-uploaded.

Processing

As soon as the successful upload of the file is completed, processing of the transactions begins. The system scans through the file and processes each transaction, line by line. Transactions that require authorization are authorized during this process. When finished processing, the system inserts the transactions as part of the current batch of unsettled transactions.

Checking the status of an uploaded file

In the Uploaded Transaction Batch Files section of the Batch Uploads area of the Merchant Menu, full status information can be obtained about batch files that have been uploaded to the system. To obtain status information on a previously uploaded file, make sure the Status Check radio button is selected, then choose the desired file from the dropdown list and click the View button. The status screen will display:

Batch Downloads File Format

The Batch Download file format contains transaction information in a fixed format. Each line of the downloaded file contains all of the relevant information for a single transaction, and is terminated with a standard Windows Carriage Return and Line Feed character combination. The line of transaction information itself is a tab-delimited string of information in the following format. This information is available via the Download Transactions option in the Merchant Menu. If you are using one of the Automated Direct Connect (ADC) methods, check Appendix B - Functional Reference for similar information that is provided to the merchant.

PositionField NameDescription of field contents
1Response CodeIndicates the result of the transaction. 1 = Approved 2 = Declined 3 = Error
2Authorization CodeSix-digit approval code.
3AVS ResponseIndicates 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
4Transaction IDThis number identifies the transaction in the system, and can be used to submit a modification of this transaction at a later time via HTML form POST (such as voiding the transaction, or capturing an Auth Only transaction).
5Submit Time StampThe time this transaction was submitted to the system.
6Credit Card NumberEchoed from the original submission of the transaction.
7Credit Card Expiration DateEchoed from the original submission of the transaction.
8Invoice NumberEchoed from the original submission of the transaction.
9DescriptionEchoed from the original submission of the transaction.
10AmountEchoed from the original submission of the transaction.
11Payment MethodEchoed from the original submission of the transaction.
12Transaction TypeEchoed from the original submission of the transaction.
13Customer IDEchoed from the original submission of the transaction.
14Customer First NameEchoed from the original submission of the transaction.
15Customer Last NameEchoed from the original submission of the transaction.
16Customer CompanyEchoed from the original submission of the transaction.
17Customer AddressEchoed from the original submission of the transaction.
18Customer CityEchoed from the original submission of the transaction.
19Customer StateEchoed from the original submission of the transaction.
20Customer ZipEchoed from the original submission of the transaction.
21Customer CountryEchoed from the original submission of the transaction.
22Customer PhoneEchoed from the original submission of the transaction.
23Customer FaxEchoed from the original submission of the transaction.
24Customer E-MailEchoed from the original submission of the transaction.
25Ship To First NameEchoed from the original submission of the transaction.
26Ship To Last NameEchoed from the original submission of the transaction.
27Ship To CompanyEchoed from the original submission of the transaction.
28Ship To AddressEchoed from the original submission of the transaction.
29Ship To CityEchoed from the original submission of the transaction.
30Ship To State ProvinceEchoed from the original submission of the transaction.
31Ship To ZipEchoed from the original submission of the transaction.
32Ship To CountryEchoed from the original submission of the transaction.
33TaxEchoed from the original submission of the transaction.
34DutyEchoed from the original submission of the transaction.
35FreightEchoed from the original submission of the transaction.
36Tax ExemptEchoed from the original submission of the transaction.
37Purchase OrderEchoed from the original submission of the transaction.
38Bank ABA Routing CodeEchoed from the original submission of the transaction.
39Bank Account NumberEchoed from the original submission of the transaction.
40(v. 3.1 only)CVV2/CVC2 Response CodeIndicates the results of CVV2 verification:
M = Match
N = No Match
P = Not Processed
S = Should have been present
U = Issuer unable to process request
41(v. 3.1 only)Recurring BillingEchoed from the original submission of the transaction.
42(v. 3.1 only)Settlement Time StampThe time the transaction was submitted for settlement.
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.) 

Last updated: 3/6/2002