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

SurePay real-time credit card and eCheck processing
Surepay Real-time Payment Processing in WebStore
Online Demo

 
General Information
Authorizing and Processing Transactions
Credit Cards
Electronic Checks
Surepay Installation and Configuration
Net::SSLeay and OpenSSL
Install OpenSSL
Install Net::SSLeay
Modify SSLeay.pm for Surepay
Configure WebStore's setup file for Surepay
$merchant_file
%form_files
Configure WebStore's merchant file for Surepay
pr_Login
pr_Password
pr_Mode
WSSurepay.pl - Configured Settings
$merchant_log
$merchant_log_size
$pr_host_live | $pr_path_live | $pr_port_live
$pr_host_test | $pr_path_test | $pr_port_test
$pr_login_test | $pr_password_test
Sending Test Authorization Requests
Sending Live Authorization Requests
 
 

 
 
General Information
 
 
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:
 
  1. WebStore application on the merchant's web site
  2. First Data SurePay Gateway
  3. First Data Merchant Services processing center
  4. Cardholder's financial institution
 
Credit card payment process:
 
  1. The WebStore order form on the merchant's web site collects the customer's billing address, shipping address, payment information, etc.
  2. This information is converted to an authorization request and sent to the First Data SurePay Gateway.
  3. The gateway stores the information and sends the request to the FDMS processing center.
  4. The processing center contacts the cardholder's financial institution to obtain authorization for the payment.
  5. The financial institution sends an authorization response (authorized, declined, or referred) which is returned to all previous points in the process.
  6. 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 AcceptanceSM Service. A merchant account may be obtained from Surepay.
 
Four points in processing electronic check payments:
 
  1. WebStore application on the merchant's web site
  2. First Data SurePay Gateway
  3. TeleCheck International processing center
  4. Check writer's financial institution
 
Electronic check payment process:
 
  1. The WebStore order form on the merchant's web site collects the customer's billing address, shipping address, payment information, etc.
  2. This information is converted to an authorization request and sent to the First Data SurePay Gateway.
  3. The gateway stores the information and sends the request to the TeleCheck International processing center.
  4. TeleCheck International contacts the check writer's financial institution to verify the checking account is valid obtain authorization for the payment.
  5. The financial institution sends an authorization response (authorized or declined) which is returned to all previous points in the process.
  6. 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:
 
 
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:
 
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
 
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.
 
Test Amount 
A Test Amount field exists on this order form for submitting the order totals listed above.
 
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.
 
TeleCheck Authorizations
 
 
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:
 
 
 
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