WebStore 400CS Shopping Cart - Surepay real-time payment processing

The integration of Surepay real-time payment processing in WebStore is designed for use by programmers or developers knowledgeable in Perl, CGI, and SSL.

WebStore supports credit card and electronic check authorization requests for transactions. Submitted transaction requests are sent through the First Data SurePay Gateway Service to the FDMS (First Data Merchant Services) or TeleCheck International processing centers.

Merchants who have acquired a merchant account with the FDMS for credit card transactions and a merchant account with TeleCheck for electronic check transactions can accept either types of payment using the WebStore shopping cart/cash register application.

You may obtain a merchant account for credit card transactions, electronic check transactions, or both.

WebStore handles authorization requests and responses only. To view the status and history of transactions, use the First Data SurePay Manager.

Index

Authorizing and Processing Transactions

WebStore supports credit card and electronic check authorization requests for transactions.

Credit Cards:

You must have a merchant account with FDMS to process credit card payments. A merchant account may be obtained from Surepay.

Four points in processing credit card payments:

WebStore application on the merchant's web site First Data SurePay Gateway First Data Merchant Services processing center Cardholder's financial institution

Credit card payment process:

The WebStore order form on the merchant's web site collects the customer's billing address, shipping address, payment information, etc. This information is converted to an authorization request and sent to the First Data SurePay Gateway. The gateway stores the information and sends the request to the FDMS processing center. The processing center contacts the cardholder's financial institution to obtain authorization for the payment. The financial institution sends an authorization response (authorized, declined, or referred) which is returned to all previous points in the process. WebStore informs the customer of the outcome. If the transaction is authorized, the order is accepted. If the transaction is not authorized, the customer must provide another payment method for the order.

An authorization does not complete the payment or guarantee the merchant will receive funds for the order. It only confirms the credit card exists and funds were available at the time of authorization to cover the purchase amount. After the merchant fulfills the order, he must mark the order fulfilled in the SurePay Manager. After the order is marked, the transaction is settled in a daily batch file which transfers the funds to the merchant's bank account.

Electronic Checks:

You must have a merchant account with TeleCheck International to use the TeleCheck^® Internet Check Acceptance^SM Service. A merchant account may be obtained from Surepay.

Four points in processing electronic check payments:

WebStore application on the merchant's web site First Data SurePay Gateway TeleCheck International processing center Check writer's financial institution

Electronic check payment process:

The WebStore order form on the merchant's web site collects the customer's billing address, shipping address, payment information, etc. This information is converted to an authorization request and sent to the First Data SurePay Gateway. The gateway stores the information and sends the request to the TeleCheck International processing center. TeleCheck International contacts the check writer's financial institution to verify the checking account is valid obtain authorization for the payment. The financial institution sends an authorization response (authorized or declined) which is returned to all previous points in the process. WebStore informs the customer of the outcome. If the transaction is authorized, the order is accepted. If the transaction is not authorized, the customer must provide another payment method for the order.

After a check authorization is received, the funds are settled the same day without further action by the merchant. Unlike credit cards, where the transaction cannot be settled until the order is fulfilled, electronic check payment is settled within a day. The merchant must fulfill the order as soon as possible, notifying the client of any delays.

Index

Surepay Installation and Configuration

WebStore requires the following in order to process real-time payment transactions with the First Data SurePay Gateway:

An Internet merchant account obtained from Surepay System requirements: Perl 5.005+ Telnet access if installing Perl modules and OpenSSL An SSL (Secure Socket Layer) implementation consisting of: Net::SSLeay 1.05 Perl module - download entire Net::SSLeay module now openssl-0.9.5 or openssl-0.9.6 c library WebStore's store setup file configured for Surepay WebStore's merchant configuration file for Surepay contains merchant account details

RDC Software does not redistribute SSL products (openssl) or Perl modules. It is the responsibility of the user to set up an SSL implementation on their server.

Index

Net::SSLeay and OpenSSL:

Authorization requests to the SurePay gateway hub must be sent using the https protocol, ensuring private information is transferred securely. The SSL implementation used by WebStore to accomplish this is Net::SSLeay, the Perl extension for using OpenSSL.

WebStore has been tested using Net::SSLeay 1.05 with openssl-0.9.5 and openssl-0.9.6.

Download Net::SSLeay 1.05 from CPAN (Comprehensive Perl Archive Network):

Net::SSLeay 1.05 Perl module page

Download the following files:

Net_SSLeay.pm-1.05.README

Net_SSLeay.pm-1.05.tar.gz

Download the entire Net::SSLeay Perl module now

Download openssl-0.9.6 from http://www.openssl.org.

Prior to installing OpenSSL or Net::SSLeay, review the following files:

OpenSSL	README INSTALL LICENSE
Net::SSLeay	README

Index

Install OpenSSL:

If your server already has openssl installed, skip the installation of openssl and install Net::SSLeay.

Review the INSTALL, README, and LICENSE files prior to installing OpenSSL.

Install the openssl c library you downloaded from http://www.openssl.org first.
Net::SSLeay will not install if openssl can not be located on your server.

After transferring openssl-0.9.6.tar.gz to your server, telnet to your account and extract it:

tar xvzpf openssl-0.9.6.tar.gz    (GNU tar)
-OR-
gunzip openssl-0.9.6.tar.gz
tar xvf openssl-0.9.6.tar

All files are stored under the openssl-0.9.6 directory.

If you are installing openssl in a location other than /usr/local/ssl (a user's domain, etc.) the following command will install files under /PATH/TO/ssl:

./config --prefix=/PATH/TO/ssl --openssldir=/PATH/TO/ssl/openssl

/PATH/TO may be the UNIX path to a user's domain root.

Complete the installation of openssl by issuing the following commands:

make
make test
make install

Index

Install Net::SSLeay:

Modify SSLeay.pm for Surepay before installing Net::SSLeay

Review the README file prior to installing Net::SSLeay.

After transferring Net_SSLeay.pm-1.05.tar.gz to your server, telnet to your account and extract it:

tar xvzpf Net_SSLeay.pm-1.05.tar.gz    (GNU tar)
-OR-
gunzip Net_SSLeay.pm-1.05.tar.gz
tar xvf Net_SSLeay.pm-1.05.tar

All files are stored under the Net_SSLeay.pm-1.05 directory.

Before installing Net::SSLeay, you must change two lines of code in SSLeay.pm. After extracting the files in Net_SSLeay.pm-1.05.tar.gz, make the following changes to Net_SSLeay.pm-1.05/SSLeay.pm:

Line	Original Code	Change To
1191	CTX_set_options($ctx, &OP_ALL);	CTX_set_options($ctx, &OP_NO_TLSv1);
1266	CTX_set_options($ctx, &OP_ALL);	CTX_set_options($ctx, &OP_NO_TLSv1);

These changes must be made to SSLeay.pm so the SSL implementation on your server can properly connect to the SurePay gateway server.

If you are installing Net::SSLeay under a user's domain and openssl has been installed in a location other than /usr/local/ssl, edit LINE 14 in Makefile.PL prior to the installation of Net::SSLeay:

Original Code:  $openssl_path = shift || '/usr/local/ssl';
Change to:      $openssl_path = '/PATH/TO/ssl';

/PATH/TO equals the UNIX path to the domain's root.

After modifying Makefile.PL, issue the following commands:

perl Makefile.PL PREFIX=/PATH/TO/perl
make
make test
make install

This will install Net::SSLeay under /PATH/TO/perl.

Add the appropriate use lib statement to WebStore's global setup file, ws_global.setup:

use lib '/PATH/TO/perl/lib/site_perl/5.6.0';
use lib '/PATH/TO/perl/lib/site_perl/5.6.0/i686-linux';

Library paths will differ between operating systems and Perl versions.

Another use lib example:

use lib '/PATH/TO/perl/lib/site_perl/5.005';

Index

Configure WebStore's setup file for Surepay

Variables listed in this section are located in WebStore's setup file, /Web_store/Databases/outlet.setup.

The variables shown below are configured for Surepay.

$merchant_file = 'merchant.surepay.cfg';

$merchant_file is the merchant configuration file for the real-time payment processor you are using.

The processor name must be included in the merchant configuration filename. For example, Surepay must be included as part of the filename for the Surepay merchant configuration file, merchant.surepay.cfg. The processor name is case insensitive in the merchant configuration filename.

Merchant configuration files are located in the /Library sub-directory.

Protect your merchant file from viewing:

Move the /Library sub-directoy to an area which can not be accessed using a web browser or place the /Library sub-directoy under HTACCESS. Rename the /Library sub-directoy defined in $libr_directory in WebStore's global setup file, ws_global.setup. Rename the merchant file. Store the merchant file under a sub-directory: Create a directory under the /Library sub-directory Store the merchant file under the newly created sub-directory Set $merchant_file = 'sub-directory/merchant.xxxx.cfg';

Modify the variables in the merchant configuration file you are using. Variables included in the configuration file are your merchant ID, merchant password, etc.

Setting $merchant_file = '' disables real-time payment processing.

$merchant_file is disabled in the WebStore distributions.

%form_files = ( # KEYS zero one '10' => ['OrderForm.Surepay.CreditCard.setup', 'Credit Card'], '11' => ['OrderForm.Surepay.Check.setup', 'Personal Check - US citizens'], '12' => ['Demo.OrderForm.Surepay.CreditCard.setup', 'Surepay Demo: Credit Card'], '13' => ['Demo.OrderForm.Surepay.Check.setup', 'Surepay Demo: Personal Check'], ); # DO NOT REMOVE - terminates %form_files

%form_files is a hash of arrays listing WebStore order form setup files.

Element zero of each array lists an order form's filename in the /Databases sub-directory. WebStore adds .setup to the filename listed in element zero if the filename does not end in .setup.

Element one is the order form's descriptive label.

Order forms stored under $form_files{10} and $form_files{11} are configured for live order transactions with Surepay.

Order forms stored under $form_files{12} and $form_files{13} are configured for test transactions with Surepay. Additional form fields exist on these forms for enabling diagnostic features built into the WebStore application software and WebStore's program library for Surepay.

Test form file arrays, $form_files{12} and $form_files{13}, should be commented out or removed from %form_files after your Surepay configuration has been fully tested. If you do not accept payment by check, comment out or remove $form_files{11} as well.

WebStore sorts the arrays in %form_files by their KEYS, in ascending order. The array with the least significant KEY becomes the default order form printed by WebStore when no payment method is selected by the client. $form_files{10} is the default order form in the WebStore distributions.

Index

Configure WebStore's merchant file for Surepay

Variables listed in this section are located in the Surepay merchant configuration file, /Web_store/Library/merchant.surepay.cfg. Protect your merchant configuration file from hackers.

Variables in the merchant configuration file may be disabled by leaving the variable's value blank, commenting out a variable, or removing the variable from the configuration file.

Variable names and values must be on the same line, separated by a single space.

Comment lines begin with a # (pound sign). The # (pound sign) can not used in a variable's value.

Comment lines and blank lines are bypassed in this file.

Trailing comments on variable lines are truncated at the first # (pound sign), removing all trailing whitespace from the variable's value.

The variable values shown below (in blue) are configured for Surepay's test server.

pr_Login 1001

pr_Login is the Surepay merchant login ID.

pr_Password password

pr_Password is the Surepay merchant login password.

pr_Mode test # live or test

pr_Mode is the Surepay mode of operation.

Valid values for pr_Mode are live and test.

When pr_Mode is set to test, submitted authorization requests are sent to Surepay's test server.

When pr_Mode is set to live, submitted authorization requests are sent to Surepay's live or production server.

pr_Mode defaults to test if mis-configured.

Index

WSSurepay.pl - Configured Settings

Variables listed below are located in the DEFINE VARIABLES section of the Surepay program library, /Web_store/Library/WSSurepay.pl.

The variable values shown below are pre-set in the distibutions of WebStore and should not require modification by the user.

$merchant_log = 'Surepay.log';

$merchant_log is the file used to store transaction status messages, located in the /Web_store/Logs directory.

Non-test values for credit card number and merchant login id stored in the log file are replaced with * (asterisks). Values for merchant password are always replaced with * (asterisks).

Setting $merchant_log = '' disables the log file routine.

$merchant_log_size = '100000'; (log file size = 100K)

$merchant_log_size equals the maximum size of the merchant log file before overwrite occurs.

Setting $merchant_log_size = '' disables overwrite of the merchant log file. You must manually delete the merchant log file.

$pr_host_live = 'xml.surepay.com'; $pr_path_live = '/xml'; $pr_port_live = '443';

Surepay production gateway system

Transaction URL = https://xml.surepay.com/xml

$pr_host_test = 'xml.test.surepay.com'; $pr_path_test = '/xml'; $pr_port_test = '443';

Surepay test system

Transaction URL = https://xml.test.surepay.com/xml

$pr_login_test = '1001'; $pr_password_test = 'password';

Surepay test login and password.

The value of $pr_login_test is also used to determine when to hide the merchant's login ID present in the merchant configuration file.

Index

Sending Test Authorization Requests

Before sending live transaction requests through the Surepay production system you should send test transactions through the SurePay test server. Test transactions are routed to the First Data test system.

The Surepay merchant configuration file, /Library/merchant.surepay.cfg, is pre-configured with a test merchant ID and password for connecting to the SurePay test server.

Testing the Surepay system allows you to verify your requests are sent correctly and allows you to verify the responses are handled correctly by WebStore. Make sure all required fields contain values when you send the test authorizations.

Use the values shown below for submitting test credit card and check authorizations:

Credit Card Authorizations

Mastercard or Visa credit card
Credit card number 4111111111111111
Valid expiration month and year
The First Data test system returns specific responses based on the value of the order's total. Send at least one authorization with each of the following total amounts. Your response for the authorization should match the response listed below:

Order Totals Response

Up to $100.00 Authorized

$101.00 to $1,000.00 Referred

Over $1,000 Declined

Order Totals		Response

Up to $100.00		Authorized
$101.00 to $1,000.00		Referred
Over $1,000		Declined

Demo.OrderForm.Surepay.CreditCard.setup is a pre-configured order form distributed with WebStore for submitting credit card test transaction requests to the Surepay test server. The form values listed above are included in this order form setup file.

A Test Amount field exists on this order form for submitting the order totals listed above.

Turning on Diagnostic Mode will print additional program information at the bottom of the order form and at the bottom of the Confirmation of Order page.

TeleCheck Authorizations

Check number 1001
MICR number 1234567804390850001001
All order totals return an authorized response.

Demo.OrderForm.Surepay.Check.setup is a pre-configured order form distributed with WebStore for submitting TeleCheck test transaction requests to the Surepay test server. The form values listed above are included in this order form setup file. Diagnostic Mode Turn on diagnostic mode Turning on Diagnostic Mode will print additional program information at the bottom of the order form and at the bottom of the Confirmation of Order page. The MICR number on WebStore order forms is split between the Bank Routing Number, Bank Account Number, and the Check Number fields: Bank Routing Number 123456780 Bank Account Number 439085000 Check Number 1001

Index

Sending Live Authorization Requests

After testing your WebStore's configuration by sending test transaction requests through the SurePay test server, switch to SurePay's production server to begin sending actual requests. To do this, change the following values in the Surepay merchant file, merchant.surepay.cfg:

pr_Login
Change the value of pr_Login to the merchant ID number you received when you established your SurePay account.
pr_Password
Change the value of pr_Password to the merchant password you received when you established your SurePay account.
pr_Mode live
Change the value of pr_Mode to live.

Index

OpenSSL:

WebStore real-time payment processing uses software developed by the OpenSSL Project for use in the OpenSSL Toolkit (http://www.openssl.org/). OpenSSL is based on the SSLeay library developed by Eric A. Young and Tim J. Hudson. The OpenSSL toolkit is licensed under an Apache-style license, which basically means you are free to get and use it for commercial and non-commercial purposes subject to some simple license conditions. RDC Software strongly recommends that users fully understand the laws and regulations relating to encryption and the Internet. THE IMPORT/EXPORT OR USE OF STRONG CRYPTOGRAPHY SOFTWARE IS ILLEGAL IN SOME PARTS OF THE WORLD. YOU ARE ADVISED TO PAY CLOSE ATTENTION TO ANY IMPORT/EXPORT OR USE LAWS WHICH APPLY TO YOU. RDC SOFTWARE IS NOT LIABLE FOR ANY VIOLATION OF LAW YOU MAKE WITH RESPECT TO THE IMPORT/EXPORT OR USE OF STRONG CRYPTOGRAPHY SOFTWARE. IT IS YOUR RESPONSIBILITY.

Top of Page

Previous \| Next	Main Index: Frames \| No Frames
Document: Frames \| No Frames