Appendix A Migrating from an earlier version of the system
This 3.0 version of the payment gateway system offers many new features
that werent 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 youd 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.
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
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, its very easy to switch
from area to area within the Merchant Menu. When changing
any settings or changing anything related to a transaction
youre 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.
to 3.0 functions and methods
While the information in this section is intended to ensure that merchants
who are using an older versions 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, wed like
to suggest that time as an opportune one to explore converting
your systems to the new version 3.0 methods and functions.
Were sure youll 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.
here to help!
If at any time difficulties arise relating to your operation of the system
dont 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.
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 wouldnt 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.
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
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 youve
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 youve 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 thats uploaded can be successfully
processed every time.
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.
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.
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
Version 3.0 of the system checks incoming transactions for duplication.
If a transaction comes in through the system thats 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.
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 merchants
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,
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.
(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 merchants 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 merchants server. The merchants 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 merchants server
to the gateway server is then relayed
to the customers web browser directly from the gateway
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 Developers Guide
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
merchants designated server.
Deprecated functions or inconsistent
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.
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 Developers 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.
Access to the Virtual Terminal can be had by selecting the Virtual Terminal
item from the Merchant Menu.
Access to the Virtual Terminal can be had by selecting the Virtual Terminal
item from the Merchant Menu.
Direct connections to the batch upload functions can be made by following
the automated batch upload directions in the batch upload
section of the Developers
Any connection to any of the scripts that were used for merchant configuration
or login will not be supported under version 3.0. Its 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 systems home page.
supported with caveats or issues
text is different
The response text thats 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 Developers
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
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 Developers
Guide to achieve your desired result.
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 havent 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.
If a merchant is designated as a 3.0 merchant, they will process transactions
using the version 3.0 methods as outlined in the Developers Guide and
B. All procedures and functions will work as documented
in the Developers Guide and elsewhere in this documentation.
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.
Several of the scripts that could be called in previous versions of the
system would return values to a merchants 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 Developers 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.
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.
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.
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 Developers
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 systems 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
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
arent 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 Developers 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 merchants account is in test
mode. For more information on test
mode, please see the Getting
Last updated: Monday, September 27, 19994:03
Back to Home