Back
Appendix A – Migrating from an earlier version of the system

This 3.0 version of the payment gateway system offers many new features that weren’t available on older versions of the system, as well as improved functionality of many other features. At the same time, some functions that were available in previous versions of the system either work slightly differently in this version or are no longer available.

This information will be useful if you’d like to modify your system to take advantage of the new 3.0 features and need more specific information on the differences between this version and previous versions. This information will also be useful if you were using a previous version of the system and are experiencing problems under the latest version.

Quick tips

Keeping a few things in mind during the migration process will help you to more easily achieve good results, or to more easily troubleshoot things that may not appear to be working correctly

Using the submit buttons to commit changes

In version 3.0 of the system, the Merchant Menu is always available at the top of your web browser while you view statistics or edit settings. Because of this, it’s very easy to switch from area to area within the Merchant Menu. When changing any settings or changing anything related to a transaction you’re viewing, you must click on one of the submit buttons on the bottom of the page to send the changes that you made back to the system so that they can be stored.  The submit buttons might have different names, such as "Submit", "Refresh", or "Save", depending on which area of the Merchant Menu you are in. The important thing to remember is that if you make changes to a setting or a transaction and then switch to another area in the Merchant Menu without clicking the submit button, your changes will not be saved.

Converting to 3.0 functions and methods

While the information in this section is intended to ensure that merchants who are using an older version’s methods and functions will still be able to process transactions with a minimum of problems, there is a strong case to be made for converting your transaction processing to the new functionality of version 3.0. In the event any problems or difficulties arise with your transaction processing system, whether or not they are related to the migration to version 3.0, we’d like to suggest that time as an opportune one to explore converting your systems to the new version 3.0 methods and functions. We’re sure you’ll find the new features, ease of use, and additional functionality to be well worth the relatively small effort that would be required to bring your systems into full compliance with the version 3.0 functionality as explained in this documentation.

We’re here to help!

If at any time difficulties arise relating to your operation of the system don’t hesitate to contact our support department for assistance.

Highlights of new features

This version of the system offers many new features that might seem different than older versions. This section will highlight some of these new features and how they might differ from older versions of the system.

New virtual terminal

The Virtual Terminal in version 3.0 of the system has been redesigned to allow much more flexibility in the information in you provide. Through the Merchant Settings area in the Merchant Menu, you can set which fields of information are asked for by the system before it processes a transaction. For example: if your use of the terminal deals with customers with whom you already have a trusted relationship, you might not need to use the AVS (Address Verification System). If so, you wouldn’t need to have the address fields displayed in the virtual terminal screen. Every field on the Virtual Terminal screen except the bare minimum required to process a transaction can be hidden if so desired.

New batch upload

The ability to upload a file containing batched transactions to the system for processing has received several improvements in this new version of the system.

Configurable File Formatting

Through the Merchant Settings area in the Merchant Menu, you can configure which fields of information will appear in which order in the file you upload to the system, as well as field delimiting or encapsulation characters. This is extremely useful if you have transactions generated by a database or other program that outputs the transactions in a specific, non-configurable file format. Now you can change your Merchant Settings to reflect the format of the file, and upload it as is. The system will process the fields of information in the order you’ve designated.

If you were previously using an older version of the system, your Batch Upload Settings have been automatically changed to reflect the file format that was expected by the upload process in the previous version. This ensures that any existing files you upload will be uploaded successfully.

Automatic validation of the upload

The process of uploading a file for batch processing in 3.0 has been modified to ensure a successful upload every time. As the file is being uploaded to the system, the server will check the file format to make sure that it matches the format you’ve specified in your Merchant Settings. If there is a problem with the file, the upload will be rejected. In the event that the file upload is rejected, either the file will need to be regenerated or repaired to ensure that it matches the formatting you’ve specified in your Merchant Settings, or your Merchant Settings will need to be changed to accurately reflect the format of the file that you are trying to upload.

In previous versions of the system, if the file format was not correct, it was not processed after uploading, and resulted in a delay in processing that batch. With the new real-time validation of the uploaded file, a batch that’s uploaded can be successfully processed every time.

Automated processing

In previous versions of the system, files that were uploaded to the systems for batch processing were held until the system had an opportunity to the process them. In the 3.0 version of the system, batch processing is started immediately after the successful upload of a batch file. The speed of the whole process of uploading a batch file and processing the transactions depends on several factors, including the number of transactions in the file, and current system load. However, because of the immediate processing of batch files and internal improvements to the system for the 3.0 version, processing of batch files will be significantly faster than it was in previous version.

Status check

As part of the automated immediate processing of batch files, real-time status information is now available which will inform you of the exact processing phase that the system is in with respect to your batch file. Elapsed time is also provided.

Support for automated batch uploading

By sending a properly formatted HTTP POST request to the URL that the batch upload submits the file to, you can submit a file directly for batch processing. This allows you to automate the uploading of batch files on your end, which would be useful for recurring transactions or other situations for which greater automation would be helpful. Full instructions on how to automate the process of batch uploads will be included in this documentation at a later date.

eCheck batch reporting

In the new 3.0 version of the system, eCheck transaction information is reported in the same fashion as credit card transaction information. eCheck transaction information is also included in statistical information in conjunction with credit card transaction information.

Duplicate transaction detection

Version 3.0 of the system checks incoming transactions for duplication. If a transaction comes in through the system that’s determined to be a duplicate transaction (for example, when a customer accidentally double-clicks the submit button on a payment form), the system prevents the duplicate transaction from being processed and returns and error to the merchant. 

Time Zone support

In the Merchant Settings area of the Merchant Menu, a time zone can now be designated. Once a time zone is designated, all information in reports, lists and statistics is displayed in the merchant’s local time.

Improved contact list

A merchant, through the Merchant Settings area in their merchant menu can now designate multiple e-mail contacts, and customize which of the automated e-mails from the system each contact will get. This is useful for sending receipt information to one person while sending error information to another, for example.

Independent Payment Form and Receipt customizations

This version of the system allows more customization of the Payment Form independently of the Receipt. For example, the Payment Form can have a different background color, header text, and footer text than the Receipt.

ADC (Automated Direct Connect)

In previous versions of the system, a merchant or their webmaster could fashion some direct interaction with the gateway system that could send information directly to our gateway system, or get information sent directly back to their system after a transaction. This provided additional benefits over the standard WebLink method, such as automated entry of transactions into a database on the merchant’s server.

In the 3.0 version of the system, these capabilities have been greatly expanded and improved. In addition to standard WebLink functionality, the new version of the system provides a new method of interaction with the gateway system called Automated Direct Connect (or ADC). Two ADC methods, Direct Response and Relay Response, are available. Through ADC Direct Response, a merchant could have a customer interact only with their web site, and process transactions through our gateway system in the background, bypassing the standard WebLink Payment Form and Receipt. Through ADC Relay Response, a customer interacts with the Payment Form on our gateway server, which then processes the transaction. After the transaction is processed, the gateway server will transmit the results of the transaction to the merchant’s server. The merchant’s server then has the opportunity to do any additional processing to determine what information should be returned to the customer. Any information that is returned from the merchant’s server to the gateway server is then relayed to the customer’s web browser directly from the gateway server.

Additional security features have been developed to work with the more flexible ADC methods, such as an MD5 hash of the transaction information and merchant information. By checking this MD5 hash, a merchant can ensure that a transaction was processed by the gateway system and not from any other source.

For more information on how the ADC methods work and how they can be implemented, please see the relevant ADC sections of the Developer’s Guide

ADC specific URL management

Previous versions of the system allowed one to designate a URL that the gateway system would send information to after a transaction. With the greatly expanded capabilities of the ADC methods, many URLs could be used by a developer throughout the course of interaction with the system. A new URL manager was developed as part of the Merchant Settings area in the Merchant Menu. Many URLs can be designated, and each URL can be modified to tell the system exactly in which cases it should be used. In addition, Referrer URLs can be designated as an additional security feature for the ADC Direct Response method, to help ensure that transaction requests only come from the merchant’s designated server.

Deprecated functions or inconsistent results

Certain ways of interacting with the system in older versions may not produce the same results under the new version of the system. Great care was taken to ensure that merchants connecting to the gateway system using older methods would not be affected by the transition to the new 3.0 version of the system. However, certain ways of interacting with the system that were never officially supported may not be supported at all under 3.0. In addition, some forms of interaction may produce slightly different results under certain conditions. These methods of interaction and associated and information are highlighted below.

Unsupported functions

The following functions are not supported under the 3.0 version of the system. If you have any thing in your programming that connects directly to one of these functions, you will need to modify your programming to connect to the gateway system using one of the supported methods as outlined in the Developer’s Guide. Connections to pre-3.0 functions not listed here will in most cases work in exactly the same fashion as in previous versions, with a few caveats as noted in the next section.

virtualterminal.asp

Access to the Virtual Terminal can be had by selecting the Virtual Terminal item from the Merchant Menu.

vtdotrans.asp

Access to the Virtual Terminal can be had by selecting the Virtual Terminal item from the Merchant Menu.

uploadbatch.asp

Direct connections to the batch upload functions can be made by following the automated batch upload directions in the batch upload section of the Developer’s Guide

Interface scripts

Any connection to any of the scripts that were used for merchant configuration or login will not be supported under version 3.0. It’s possible that a merchant might have a URL to one of these scripts bookmarked in their browser. An example would be one of the previous login URLs, such as merchantlogin.asp. All logging in should be done from the Merchant Login link on the system’s home page.

Functions supported with caveats or issues

authrequest.asp

Response text is different

The response text that’s returned as part of the result of a call to authrequest.asp has changed. This response text is the explanatory text that is included within the delimited data response. The new version of the systems has more possible responses that more accurately reflect the status of the transaction.

If any part of your system is expecting to see a particular string of text in the response text field, it will most likely fail under version 3.0. Parsing for text strings in the response text field is not the recommended way to determine the status of the transaction. A much more effective way would be to replace your use of authrequest.asp with the new 3.0 delimited data response formats as explained in the Developer’s Guide. The results of those transactions will include a response code along with the response text. The response text can be an effective string to pass along to a customer, but it may change in wording at any time. If you need to programmatically test for a specific response, use the response codes as defined in Appendix C.

authpost.asp

Results will be returned as HTTP POST, not GET

authpost.asp is a deprecated function whose functionality had been replaced by authpost2.asp in previous versions of the system. Any calls to authpost.asp will still return a result in version 3.0. However, the result will be returned in the form of an HTTP POST request, and will be identical to the HTTP POST request that would come from authpost2.asp. If your system is calling authpost.asp and depending on the results to be an HTTP GET request, it will fail. In this case, you should explore reworking your system to use new 3.0 functions as explained in the Developer’s Guide to achieve your desired result.

General caveats

The merchant version setting in the system

One important setting that the system stores is the concept of merchant version number. If you have been using the system before the release of version 3.0, and haven’t contacted support to indicate otherwise, then your merchant version number will be stored as a version 2.5 merchant. New merchants that are new to the system since version 3.0 was released, or those merchants who have specifically upgraded themselves through support to version 3.0 merchant status are stored in the system as version 3.0 merchants.

Version 3.0 merchants

If a merchant is designated as a 3.0 merchant, they will process transactions using the version 3.0 methods as outlined in the Developer’s Guide and Appendix B. All procedures and functions will work as documented in the Developer’s Guide and elsewhere in this documentation.

Version 2.5 merchants

Any merchants who are designated as version 2.5 merchants and process transactions using the old 2.5 methods will still see the same results and functionality as they always have, subject to the caveats addressed above in this section.

Any merchants who are designated as version 2.5 merchants and process transactions using the new 3.0 functions and methods will not necessarily see results as they are documented here. Instead, for purposes of backwards compatibility, the results experienced will be the same as if the merchant had processed the transaction using the equivalent 2.5 functions. If a version 2.5 merchant using version 3.0 functions wants the results to be consistent with the version 3.0 functions as they are documented here, they must identify themselves to the system as a version 3.0 merchant. This can be done a per-transaction basis by sending the x_Version=3.0 field with the transaction. This setting can be changed permanently by contacting support.

Case sensitivity

Several of the scripts that could be called in previous versions of the system would return values to a merchant’s system in the form of variable=value, such as AVSDATA=YYY. In many cases in the previous versions of the system, the variable names were composed of all upper case characters. In version 3.0 of the system, these same scripts will return variable names where the first character is uppercase, and all subsequent characters are lowercase. If your system is case sensitive, that is, if it expects to see those variable names in the exact upper or lower case state all the time, it will fail. It is strongly advised that now and in the future any systems that interface with ours should be case insensitive.

The difference between METHOD and x_method

In previous versions of the system, a merchant would use the METHOD field to tell the gateway server whether the transaction was a credit card transaction or an eCheck transaction as well as to indicate the type of credit card. In version 3.0 the gateway server no longer needs to know the type of credit card. Thus the 3.0 replacement for the METHOD field, x_method, has only two possible values, cc & echeck.

Text in e-mails has changed

The text of all of the e-mails which are sent out by the system, whether to the customer or the merchant, has significantly changed. If a merchant or developer has programmed anything that parses an e-mail for a specific string of text, it will most likely fail. Now and in the future, it is strongly advised that developers do not depend on the text of the e-mail to make any decisions programmatically, but rather, use the existing interfaces as documented in the Developer’s Guide.

Differences in batch file download

Previous versions of the system have offered the ability to download the contents of a batch to a computer by saving the information from a web browser to a file. Version 3.0 improves on this functionality in several ways.

Actual file download

Rather than having to save the file that is displayed in the browser, version 3.0 of the system starts saving the file automatically just like any file that would be downloaded from the Internet.

All transactions are included

In a downloaded batch file, all transactions are listed, including declined transactions or transactions for which errors occurred. The type of transaction can be determined by checking the code, where 1 = approval, 2 = decline, and 3 = error.

Changes to file format

The downloaded batch file in version 3.0 is in a slightly different format than in previous versions. If you download batch files and then process them further with another program, that additional program may need to be modified. For specific details of the batch download file format, see the Batch Processing section of the Developer’s Guide.

What functionality can be used to replace disablereceipt=true in version 3.0?

In previous versions of the software, a developer could pass disablereceipt=true to the gateway server to bypass the system’s receipt page and get the results of the transaction sent directly to the URL they had configured as the “Return script or link URL” in their configuration. Any configurations using this functionality will still work subject to the other caveats discussed in this section.

If a developer wanted to achieve similar functionality using version 3.0, the ADC (Automated Direct Connect) methods provide several ways to achieve similar or improved functionality. For more information about the ADC methods, see the ADC section of the Developer’s Guide

Voided transactions appear in reports

In previous versions of the system, once a transaction was voided, it would no longer appear in the report of the current batch and could not be un-voided. In version 3.0, transactions that have been voided still show up in batch reports and can be UN-voided and re-voided as many times as necessary all the way up to settlement time. Similarly, a transaction can be marked for capture of funds or unmarked as many times as is necessary before settlement.

Transactions which are void or marked for funds capture have a check box in the respective capture or void fields in a batch report. If changes are made to those fields, one of the buttons on the bottom of the page must be clicked on for the information to be sent to the system and committed.

Non-secure transactions no longer accepted

To provide additional protections against fraud and theft of credit card data, our system will not accept any HTTP connections that aren’t encrypted using a Secure Socket Layer. This applies to connections from a merchant server for transaction processing as well as merchant logins for administrative purposes.

If a customer is connecting directly to the payment form on the gateway server (for example, using the WebLink or ADC Relay Response methods) their browser must support secure connections for them to be able to complete the transaction. If a transaction is coming from your own merchant server (for example, using the ADC Direct Response method), your server must be able to make a client side SSL connection to our gateway server in order to transfer information. Additionally, the merchant server will need to support server side SSL for any HTTP POST requests that the gateway server makes to return information to the merchant server. For more information about the ADC processing methods and the situations in which the merchant server will need to support secure connections, see the Developer’s Guide.

In cases where it's a customer's or merchant's web browser that is making the connection to our system, it's often as simple as replacing http:// with https:// in the URL to ensure that the connection is being made securely.

The only situation in which a non-secure HTTP connection will be allowed is if the merchant’s account is in test mode. For more information on test mode, please see the Getting Started guide.

Last updated: Monday, September 27, 19994:03 PM MDT
Back to Home