 |
|
|
 |
|
 |
|
|
|
|
 |
|
|
|
|
 |
|
|
|
|
 |
|
|
|
|
 |
|
|
|
|
 |
Free Bi-Monthly
Marketing Newsletter
|
|
|
|
|
|
 |
Merchants, Click
Below To Login
|
|
|
|
|
|
|
|
This section of the documentation is intended to be a comprehensive reference for all of the
different forms of interaction with the system. This section covers the
WebLink methods 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 Batch Processing and Automated Direct Connect (ADC).
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 HTTP POST to https://secure.quickcommerce.net/gateway/transact.dll.
In this form 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 have to reenter 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
Functional Reference.
Form Construction
It is assumed that a developer who is intending larger scale integration than the basic WebLink
functions would already have a knowledge of how to construct HTML forms.
To impart a working knowledge of HTML would be beyond the scope of this
documentation, however, a brief overview of HTML forms is provided here.
All forms used to integrate with the system will be submitted to the URL https://secure.quickcommerce.net/gateway/transact.dll
using the HTTP POST method. The basic HTML tags used to construct such a form would be written as follows:
<FORM METHOD=POST
ACTION="https://secure.quickcommerce.net/gateway/transact.dll">
</FORM>
Any form fields that needed to be sent to the system would be enclosed within the opening
<FORM>
tag and the closing
</FORM>
tag.
WebLink
The simplest and easiest form of integration between a merchant's website and the system is the WebLink method. At its most basic level, integration with the system through the WebLink method takes the following form:
- A customer navigates through a merchant's web page, selecting what they would like to purchase.
- The customer fills in the information that is needed to begin processing the transaction. This is done using an HTML form that has been set up to post the information in the form to the system.
- The customer is then connected directly to the system, which displays the Payment Form. The Payment Form provides a place for the customer to enter any information that it needed which wasn't provided by the merchant's form.
- When submitted, the Payment form validates the credit card.
- If the transaction is not approved, the result is displayed to the customer, and they are given the opportunity to correct any information that they may have 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 their records.
- The Receipt Page that is shown to the customer can have a link back to the merchant's site to complete the transaction
Unless otherwise specified, a receipt will be emailed to the customer, as well as to the merchant.
Customizing the behavior of WebLink
To provide the link between a merchant's web site and the system, an HTML form is inserted into the merchant's web page that performs an HTTP form POST to the system. 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.
Customizing the Payment Form
As specified in the User's Guide, global modifications can be made to the Payment Form, 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.
- x_Logo_URL - A valid URL sent in this field will cause the target of that URL to be displayed at the top of both the Payment Form and the Receipt Page. This is ideal for displaying a merchant's logo on
these pages.
- x_Background_URL - A valid URL sent in this field will cause the target of that URL to be displayed as the background image for both the Payment Form and the Receipt Page.
- x_Color_Background - Any valid HTML color name or color hex code sent in this field will set that color as the background color for both the Payment Form and the Receipt Page.
- x_Color_Link - Any valid HTML color name or color hex code sent in this field will set that color as the color of HTML links for both the Payment Form and the Receipt Page.
- x_Color_Text - Any valid HTML color name or color hex code sent in this field will set that color as the color of text for both the Payment Form and the Receipt Page.
- x_Header_HTML_Payment_Form - Any text or HTML code sent in this field will display at the top of the Payment Form. This text will be displayed underneath the logo, if present, and above the rest of
the Payment Form fields.
- x_Footer_HTML_Payment_Form - Any text or HTML code sent in this field will display at the bottom of the Payment Form. This text will be displayed above the "Submit Transaction" button, and below
the rest of the Payment Form fields.
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
As specified in the User's Guide, global modifications can be made to the Receipt Page. In addition to these global options, per transaction changes to the appearance of the Receipt Page can be made by sending the proper fields to the
system in the WebLink 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.
- x_Logo_URL - A valid URL sent in this field will cause the target of that URL to be displayed at the top of both the Payment Form and the Receipt Page. This is ideal for displaying a merchant's logo on
these pages.
- x_Background_URL - A valid URL sent in this field will cause the target of that URL to be displayed as the background image for both the Payment Form and the Receipt Page.
- x_Color_Background - Any valid HTML color name or color hex code sent in this field will set that color as the background color for both the Payment Form and the Receipt Page.
- x_Color_Link - Any valid HTML color name or color hex code sent in this field will set that color as the color of HTML links for both the Payment Form and the Receipt Page.
- x_Color_Text - Any valid HTML color name or color hex code sent in this field will set that color as the color of text for both the Payment Form and the Receipt Page.
- x_Header_HTML_Receipt - Any text or HTML code sent in this field will display at the top of the Receipt Page. This text will be displayed underneath the logo, if present, and above the rest of the
Receipt Page information.
- x_Footer_HTML_Receipt - Any text or HTML code sent in this field will display at the bottom of the Receipt Page. This text will be displayed below the rest of the Receipt Page information.
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 as specified in the User's Guide. 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.
- x_Receipt_Link_Method - The value of this field can be either LINK, POST, or GET. This field specifies what kind of link is made back to a merchant's web site. If the value of this field is LINK, a
regular HTML hyperlink is created. If the value of this field is POST or GET, an HTML form is created in the Receipt Page, with the method as specified in this field. This HTML form has hidden fields
containing the Result Fields of the transaction as specified in Appendix B - Functional Reference. Using an x_Receipt_Link_Method of POST or GET can be a simple yet effective way to get the
results of a transaction posted back to a script on the merchant's server. One scenario where this would be effective would be a merchant selling access to a password protected web site. To continue
after processing their payment, a customer would submit the form, sending the results of the transaction to a script on the merchant's server. The script could then either grant or deny access to the rest
of the web site based on whether or not the form indicated the transaction was approved.
- x_Receipt_Link_Text - The value of this field is a text string that becomes the hyperlinked text on the Receipt Page if x_Receipt_Link_Method is LINK, or becomes the text of the submit button if
x_Receipt_Link_Method is POST or GET. Most merchants would use this field to display some invitation to the customer to follow the link back to the merchant's web site (e.g. "Click here to
continue")
- x_Receipt_Link_URL - The URL specified in this field will become the target of the hyperlink on the Receipt Page if x_Receipt_Link_Method is LINK, or it will become the action of the HTML form if
x_Receipt_Link_Method is POST or GET. Any URL specified in this field must also be present in the URL Manager, and specified as a Valid ADC or Receipt Link URL. If this field is not sent,
or no URL is specified, then the system will use the Receipt Link Default URL if one is specified in the URL Manager.
Customizing the email receipt
As specified in the User's Guide, global modifications can be made to the email receipt that is emailed to customers upon the completion of a transaction. In addition to these global options, per transaction changes to the email receipt
settings can be made by sending the proper fields to the system in the WebLink form.
- x_Email_Customer - This field contains either the value TRUE or FALSE. If set to TRUE, an email receipt is sent to the email address specified in the x_Email field. If set to FALSE, no email is sent.
- x_Header_Email_Receipt - Any text sent in this field will display at the top of the email receipt.
- x_Footer_Email_Receipt - Any text sent in this field will display at the bottom of the email receipt.
ADC
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 directly through the system in real time. With proper use of these methods, a merchant can retain full control of the data that's used in the processing of the transaction, and keep the
customer on their 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: ADC Direct Response and ADC Relay Response.
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 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.
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
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.
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.
ADC Direct Response implementation
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, a developer would design an HTML form that would securely obtain all of the information needed to process a transaction. The developer would then initiate a secure HTTP 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. The fields contained in the posted form would
be all of the information necessary to process a transaction, plus a couple of additional fields:
- x_ADC_Delim_Data - This field must be included with a value of TRUE for an ADC Direct Response transaction. When this field is set to TRUE, it specifies that the results of the transaction should be
sent back in a machine readable format as specified in Appendix B - Functional Reference.
- x_ADC_URL - The value of this field must be set to FALSE for ADC Direct Response.
ADC Relay Response implementation
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:
- x_ADC_Relay_Response - This field must be in the form and set to a value of TRUE to tell the system that it will be doing an ADC Relay Response transaction.
- x_ADC_URL - The value of this field is the URL to which the system will return the results of the transaction. The results of the transaction will be returned via a HTTP form POST to the specified URL.
As an extra security precaution, the URL specified in this field must be a Valid ADC or Receipt Link URL, as specified in the URL Manager.
Once the gateway server gets all of the transaction information, the transaction is processed. Once the transaction is processed, an HTML 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 can 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.
Caveats
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 server can handle a POST to it.
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 configure to allow the POST method to plain HTML pages.
HTTP header replacement
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.
AVS
The Address Verification System (AVS) is a feature available to merchants 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. It is intended to help the merchant make an informed decision at the time of purchase whether or not to accept a person's credit card. 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 providers, use of the AVS system is required in order to avoid non-qualified
transaction surcharges (typically an additional 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 provider.
How to use AVS
AVS responses are automatically sent when transactions with address information are processed. 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:
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.
Test Mode
Test Mode is a special mode of interacting with the system which is useful during the initial setup
phase, where a merchant may want to test their 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 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 it is sure that
all aspects of a merchant's interaction with the 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 which 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 performs 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 set to not be 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, even if invalid credit card numbers are used. There are many situations, however, where a developer will need
the system to not approve transactions or to generate errors in order to test all possible responses from the system.
The system has been designed so that a special test credit card number, 4222222222222, can be used to generate error responses from the system. 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, as enumerated in Error & Response Codes.
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 Processing
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.
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:
Fields marked as Required in the above table must be included in the uploaded file in order to process a transaction, although their position in the file is fully customizable, as detailed in the Changing the File Format section.
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.
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, three items can be changed:
- The E-Mail Customer setting specifies whether or not customers in the batch upload file are emailed with a receipt for their transaction. If this setting is set to "Yes", an email receipt will be sent to each customer in the batch
upload file just as if the transaction had been processed interactively. Note that if this setting is set to "Yes", a valid email address must be included as one of the fields in the uploaded file.
- The Default Field Separator setting is used to tell the system which character separates, or delimits the field in the uploaded file. This delimiting character marks the end of one field and the beginning of the next. To change this
setting, a merchant can choose a new delimiting character from the drop down list. If the character the merchant would like to use is not in the drop down list, the "Other" choice should be selected in the drop down list and the
desired character can be typed into the box to the right of the drop down list.
- The Default Field Encapsulation Character setting is used to specify a character to be used to enclose all of the data within a field. This can be useful if the data within a field might contain the same character that is used as a
delimiting character. By specifying an encapsulation character, the system will now that all characters within the encapsulation characters are part of the same field, even if one or more of those characters are the same as the
field delimiting characters. To change this setting, a merchant can choose a new encapsulating character from the drop down list. If the character the merchant would like to use is not in the drop down list, the "Other" choice
should be selected in the drop down list and the desired character can be typed into the box to the right of the drop down list.
The Field Inclusion And Order Settings allow a merchant to specify which fields will be included in the uploaded batch file, and in which order those fields will appear. To change these settings, the drop down list next to each field
name can be set to indicate the field's position in the file, or to exclude the field entirely.
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, go to the Uploaded Transaction Batch Files section. 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. Click the Browse button to select a file on your local system. 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 ensure 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 download 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:
- The system's internal file ID for the file.
- The Date and Time that the file was uploaded.
- The number of transactions found in the file.
- The current status of each of the four phases of processing (File Upload, Data Formatting, Transaction Processing, and Receipt Emailing)
- The elapsed time of the processing of the file.
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 transaction information itself is a
comma delimited string of information in the following format:
|
|
|
|
