Back
Developer’s Guide
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.RTWare.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 Appendix B – Functional Reference.

Form construction

It is assumed that a developer who is intending larger scale integration than the basic WebLink functions would already have 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.RTWare.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.RTWare.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.

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:

1.        A customer navigates through a merchant's web page, selecting what they would like to purchase.

2.        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.

3.        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.

4.        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.

5.        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 e-mailed 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 e-mail receipt

  As specified in the User's Guide, 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.

  • x_Email_Customer - This field contains either the value TRUE or FALSE. If set to TRUE, an e-mail receipt is sent to the e-mail address specified in the x_Email field. If set to FALSE, no e-mail is sent.
  • x_Header_Email_Receipt - Any text sent in this field will display at the top of the e-mail receipt.
  • x_Footer_Email_Receipt - Any text sent in this field will display at the bottom of the e-mail 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.RTWare.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.RTWare.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 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 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.

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 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 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 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 Appendix C.

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.

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 format	Field Name	Required?	Notes
  1	Invoice Number	Recommended
  2	Description	Recommended
  3	Amount	Required	Use positive amount for Credit transactions of type CREDIT
  4	Payment Method	Required	Possible Values: CC or ECHECK
  5	Transaction Type	Required	Must be exactly one of: AUTH_CAPTURE, AUTH_ONLY, CAPTURE_ONLY, CREDIT, VOID, PRIOR_AUTH_CAPTURE
  6	Authorization Code	Optional	Required and necessary only for CAPTURE_ONLY type transactions
  7	Transaction ID	Optional	Required and necessary only for VOID or PRIOR_AUTH_CAPTURE type transactions
  8	Credit Card Number	Required
  9	Credit Card Expiration Date	Required	Must be either mmyy or mm/yy
  10	Bank Account Number	Optional	For ECHECK method transactions - up to 17 digits
  11	Bank ABA Routing Code	Optional	ABA Transit/Routing number for ECHECK method transactions - must be 9 digits
  12	Bank Name	Optional	For ECHECK method transactions
  13	Customer ID	Recommended
  14	Customer First Name	Recommended
  15	Customer Last Name	Recommended
  16	Customer Company	Optional
  17	Customer Address	Recommended	Suggested for Address Verification System (AVS)
  18	Customer City	Optional
  19	Customer State	Optional
  20	Customer ZIP	Recommended	Suggested for Address Verification System (AVS)
  21	Customer Phone	Optional
  22	Customer Fax	Optional
  23	Customer E-Mail	Optional	If provided, customer will receive a standard E-Mailed receipt, assuming that your account is configured to send customers an E-mail receipt

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 of this developer’s guide.

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.