/n software inc. - Getting Started with TSYS Integrator

Tutorial - Getting Started with TSYS Integrator (Host Capture)

Requirements:

TSYS Integrator
Before you can go live, you'll need a merchant account with your bank that supports TSYS (TSYS Approved). If you do not already have a merchant account, contact our support team, and they can help you with this.

Download Demo: Download

Chapter Listing

Getting Started
TSYS Integrator
Terminal Capture vs Host Capture
The Life Cycle of a Credit Card Charge
Merchant Setup
PreAuthorize
Transactions (Charge, Debit, Credit, Etc.)
Batch Management and Transaction Searches
Testing
Business Models
Miscellaneous
More Information

Getting Started

The first step is to determine if you want to use a payment gateway or work directly with a processor. If you do not already know which of these you prefer, below is a description of these options.

Direct to Processor
All credit card transactions eventually end up in the hands of a credit card processing network, such as TSYS Acquiring Solutions, Global Payments (Global Payments Integrator), Paymentech NetConnect (Paymentech Integrator), or First Data Merchant Services (FDMS Integrator). Working directly with the processor means that you have control over everything. Not only do you perform the authorizations, but you also have control of all other types of transactions including settlements (captures), credits, voids, etc.
A payment processor is a service company that performs charges and settlements for credit card transactions. Every credit card transaction eventually goes through a payment processor like TSYS (Fig. 1). Processing transactions directly through the payment processor is generally less expensive than communicating through a payment gateway, and you maintain complete control over all aspects of the transactions that you process.

Fig. 1
Internet Payment Gateways
Internet payment gateways are value-added services that work with you (the merchant) and a back-end processor (Fig 2.). The benefits of using a payment gateway are significant, since the gateway handles all of the communication with the processor and offers a variety of configuration options and additional services (typically via a web interface) such as transaction logging, reporting, security and fraud prevention, credit and voiding capabilities, and automatic settling of authorized charges.

Fig. 2

Note: While the basic concepts discussed in the article apply to credit card processing in general, the implementation and methods used vary depending on whether or not you're working directly with a payment processor such as TSYS or using an Internet payment gateway.

If you're working with the TSYS Acquiring Solutions processor, then you're in the right place.
If you're working with an Internet payment gateway, please read the E-Payment Integrator guide.

The next step is to make sure that you have a merchant account that supports TSYS. If you do not have a merchant account setup with a bank, you'll need to do that before you can go live and complete real transactions (if you're not sure how to go about setting up a merchant account, our support team can help you get setup correctly). A merchant account is a special bank account where money from credit card transactions is first routed to and held before transfer to your own business account. Money is then transferred into your standard business account in real-time or during various times in a 24 hour period.

TSYS Integrator

Processing credit card transactions with your application is extremely easy using the TSYS Integrator. TSYS Integrator can be used to add credit card transaction processing to your application by communicating directly with the TSYS Processing Services processor. The TSYS Integrator contains ten components: CardValidator, CCBenefit, CCDebit, CCDetailRecord, CCECommerce, CCGiftCard, CCLevel2, CCLevel3, CCRetail, and CCSettle which will be used in this tutorial.

Terminal Capture vs Host Capture

The TSYS Integrator offers two different types of processing with TSYS. These are Terminal Capture and Host Capture.

Terminal Capture

Terminal Capture requires the merchant to store the detail aggregate returned after the authorization. At the end of day the stored aggregates are used to build a batch of transactions to be settled. This offers fine grained control over transactions however it does require the storage and management of sensitive data between the authorization request and settlement.

For more information on using the Terminal Capture approach please see TSYS Terminal Capture guide. This tutorial focuses only on Terminal Capture.

Host Capture

Host Capture places the burden of storing information between the authorization and settlement on the TSYS servers. This approach allows you as the merchant to authorize transactions without having to store the aggregate between the authorization and settlement. Additionally to settle you release the current batch instead of building the batch from a series of aggregates. This offers an easier way to handle transactions. Of course you would still maintain transaction specific information, such as response codes, ids, etc, but you are freed from having to store the aggregate used at settlement.

The Life Cycle of a Credit Card Charge

All credit card charges take place in two stages: authorization and capture.

Authorization is the act of obtaining the authorization for a certain dollar amount on a customer's credit card (i.e., making sure that the card has enough funds to cover the amount). No actual money changes hands during the authorization, but a hold is placed on those authorized funds.

Capture is the act of actually transferring the previously authorized funds from the cardholder bank account to the merchant bank account. The capture should not take place until the product has been shipped to the customer (if applicable).

Most often, companies that are making charges directly with the processor perform all their authorizations at the time of the submission of the credit card, and then perform one "settlement" at the end of the business day. Each previously authorized transaction (for which the product has been delivered) is captured during this settlement process. The CCRetail and CCECommerce components are used to make authorizations and hold funds during a credit card transaction.

Merchant Setup

When using the Host Capture system with TSYS you must use the HCTerminalMgr component to obtain a "GenKey" value that is used in all subsequent requests. The AuthenticateDevice method communicates with TSYS and returns the "GenKey" value. For example:

HCTerminalMgr1.MerchantId = "300012345678901";
HCTerminalMgr1.RoutingId = "TSH000";
HCTerminalMgr1.AuthenticationCode = "ABCD123456";
HCTerminalMgr1.MerchantZip = "85284";
HCTerminalMgr1.AuthenticateDevice();
string myGenKey = HCTerminalMgr1.Response.GenKey;

A GenKey may be re-activated at any time by calling AuthenticateDeveice again. DeactiveDevice will invalidate the current GenKey value.

PreAuthorize

Pre-Authorization is the process you use to check the validity of a card before submitting it to the processor for authorization, and can be performed by the CardValidator component. This is an offline check to make sure the expiration date is valid, the digits pass a Luhn digit check, and the card type is valid.

Pre-Authorization is used to help eliminate invalid submissions to the processor by verifying a correctly formatted card number and non-expired valid-thru date. This is particularly important because the processor will charge a small fee every time you attempt to process a charge, regardless of whether or not the charge is successful.

While a successful PreAuthorize does not guarantee that the credit card is valid, it virtually eliminates bad authorization attempts due to accidental mistyping. It is recommended that you always use an offline Pre-Authorization method to avoid submitting errant authorization requests to the processor.

Below is an example of using the CardValidator component:

C#
Cardvalidator1.CardExpMonth = 08;
Cardvalidator1.CardExpYear = 2010;
Cardvalidator1.CardNumber = "4444333322221111";
Cardvalidator1.ValidateCard();

if (Cardvalidator1.DigitCheckPassed && Cardvalidator1.DateCheckPassed)
{
  Console.WriteLine("Card may be valid.");
  Console.WriteLine("The card type is: " + Cardvalidator1.CardTypeDescription);
}

Transactions (Charge, Debit, Credit, Etc.)

There are a variety of components designed to perform different types of transactions. These are:

HCECommerce - Card Not Present transactions
HCRetail - Card Present Credit Card transactions
HCDebit - Debit Card transactions
HCReversal - Reverse previous authorizations
HCAdjustment - Adjust previous authorizations before capturing
HCBenefit - EBT Card transactions
HCGiftCard - Gift Card Transactions
HCLevel3 - Level 3 Transactions

HCECommerce

The HCECommerce component is used to authorize transactions when the card is not present. You can make a Purchase, Void, or Credit transaction.

Purchase

A Purchase transaction is a transaction that authorizes a transaction and adds it to the open batch. For example:

HCECommerce1.GenKey = "GenKey from HCTerminalMgr.AuthenticateDevice";
HCECommerce1.MerchantId = "300012345678901";
HCECommerce1.RoutingId = "TSH950";
      	
HCECommerce1.Card.Number = "4444333322221111";
HCECommerce1.Card.ExpMonth = 1;
HCECommerce1.Card.ExpYear = 15;
HCECommerce1.Card.EntryDataSource = CCEntryDataSources.edsManualEntryNoCardReader;
HCECommerce1.TransactionAmount = "1250";
HCECommerce1.TransactionDesc = "Test trans";
HCECommerce1.TransactionNumber = 99;
HCECommerce1.Purchase();

Void

A Void is used to cancel a previous Sale transaction before the batch has been closed. If the batch is closed you can use a Credit to return funds to the card holder. A Void requires the original retrieval number from the Purchase and the original amount. For example:

HCECommerce1.GenKey = "GenKey from HCTerminalMgr.AuthenticateDevice";
HCECommerce1.MerchantId = "300012345678901";
HCECommerce1.RoutingId = "TSH950";
	
HCECommerce1.TransactionDesc = "Void RRN Test";
HCECommerce1.VoidTransaction("124520900193", "1250");

Credit

A Credit is used to return funds to a card. A Credit is not based on a previous transaction. Because of this you must specify the card information when performing a credit. For example:

HCECommerce1.GenKey = "GenKey from HCTerminalMgr.AuthenticateDevice";
HCECommerce1.MerchantId = "300012345678901";
HCECommerce1.RoutingId = "TSH950";	
	
HCECommerce1.Card.Number = "4444333322221111";
HCECommerce1.Card.ExpMonth = 1;
HCECommerce1.Card.ExpYear = 15;
HCECommerce1.Card.EntryDataSource = CCEntryDataSources.edsManualEntryNoCardReader;
HCECommerce1.TransactionAmount = "1250";
HCECommerce1.TransactionDesc = "Credit test transaction";
HCECommerce1.TransactionNumber = 13;

HCECommerce1.Credit();

HCRetail

The HCRetail component is used to authorize card present transactions. The component can be used to make a Purchase, Credit, Void, or Tip Adjustment.

Purchase

A Purchase is a typical transaction where a card is authorized. For example:

HCRetail1.GenKey = "GenKey from HCTerminalMgr.AuthenticateDevice";
HCRetail1.MerchantId = "300012345678901";
HCRetail1.RoutingId = "TSH950";	
	
HCRetail1.Card.Number = "4444333322221111";
HCRetail1.Card.ExpMonth = 1;
HCRetail1.Card.ExpYear = 15;
HCRetail1.Card.EntryDataSource = CCEntryDataSources.edsManualEntryTrack1Capable;
HCRetail1.TransactionAmount = "1250";
HCRetail1.TransactionDesc = "Test trans";
HCRetail1.TransactionNumber = 99;

HCRetail1.Purchase();

Void

HCRetail1.GenKey = "GenKey from HCTerminalMgr.AuthenticateDevice";
HCRetail1.MerchantId = "300012345678901";
HCRetail1.RoutingId = "TSH950";		
	
HCRetail1.TransactionDesc = "Void RRN Test";
HCRetail1.VoidTransaction("126621903416", "1250");

Credit

A Credit is used to return funds to a card. A Credit is not based on a previous transaction. Because of this you must specify the card information when performing a credit. For example:

HCRetail1.GenKey = "GenKey from HCTerminalMgr.AuthenticateDevice";
HCRetail1.MerchantId = "300012345678901";
HCRetail1.RoutingId = "TSH950";		
	
HCRetail1.Card.Number = "4444333322221111";
HCRetail1.Card.ExpMonth = 1;
HCRetail1.Card.ExpYear = 15;
HCRetail1.Card.EntryDataSource = CCEntryDataSources.edsManualEntryTrack1Capable;
HCRetail1.TransactionAmount = "1250";
HCRetail1.TransactionDesc = "Credit test transaction";
HCRetail1.TransactionNumber = 13;

Tip Adjustment

A Tip Adjusment is used to add a tip to a previously authorized Purchase before the batch is closed. The original retrieval number and original amount are required. For example:

HCRetail1.GenKey = "GenKey from HCTerminalMgr.AuthenticateDevice";
HCRetail1.MerchantId = "300012345678901";
HCRetail1.RoutingId = "TSH950";		
	
HCRetail1.Card.Number = "4444333322221111";
HCRetail1.Card.ExpMonth = 1;
HCRetail1.Card.ExpYear = 15;
HCRetail1.Card.EntryDataSource = CCEntryDataSources.edsManualEntryTrack1Capable;
HCRetail1.TransactionAmount = "2450";
HCRetail1.TransactionDesc = "Adjust Tip Transaction";
HCRetail1.TransactionNumber = 102;

HCRetail1.Purchase();
string rrn = HCRetail1.Response.RetrievalNumber;
      
SetupComponent();      
HCRetail1.AdjustTip(rrn, "2450", "550");

HCDebit

The HCDebit component is used to authorize card present Debit transactions. The component can be used to make a Purchase, Credit, or Balance Inquiry.

Purchase

A Purchase is a typical sale transaction. For example:

HCDebit1.GenKey = "GenKey from HCTerminalMgr.AuthenticateDevice";
HCDebit1.MerchantId = "300012345678901";
HCDebit1.RoutingId = "TSH950";		

HCDebit1.CardTrack2Data = "9999999800002773=09121015432112345678";
HCDebit1.DebitPIN = "83C33384650827F6";
HCDebit1.DebitKSN = "4A00310459400004";	
HCDebit1.TransactionAmount = "1250";
HCDebit1.TransactionDesc = "Test trans";
HCDebit1.TransactionNumber = 99;
//HCDebit1.CashBackAmount = "1000"; //Set CashBackAmount if cash back is desired

HCDebit1.Purchase();

Credit

A Credit returns funds to the card holder. It is not based on a previous transaction so the card data is required. For example:

HCDebit1.GenKey = "GenKey from HCTerminalMgr.AuthenticateDevice";
HCDebit1.MerchantId = "300012345678901";
HCDebit1.RoutingId = "TSH950";

HCDebit1.CardTrack2Data = "9999999800002773=09121015432112345678";
HCDebit1.DebitPIN = "83C33384650827F6";
HCDebit1.DebitKSN = "4A00310459400004";	
HCDebit1.TransactionAmount = "1250";
HCDebit1.TransactionDesc = "Credit test transaction";
HCDebit1.TransactionNumber = 13;

HCDebit1.Credit();

Balance Inquiry

A Balance Inquiry returns the balance left on a card. For example:

HCDebit1.GenKey = "GenKey from HCTerminalMgr.AuthenticateDevice";
HCDebit1.MerchantId = "300012345678901";
HCDebit1.RoutingId = "TSH950";	
	
HCDebit1.CardTrack2Data = "9999999800002773=09121015432112345678";
HCDebit1.DebitPIN = "83C33384650827F6";
HCDebit1.DebitKSN = "4A00310459400004";		
HCDebit1.TransactionAmount = "106";
HCDebit1.TransactionDesc = "Test trans";
HCDebit1.TransactionNumber = 14;

HCDebit1.BalanceInquiry();	
      
string currentBalance = HCDebit1.Response.Balance;

HCReversal

The HCReversal component is used to reverse Credit, Debit, and Gift Card transactions. The component can be used to Reverse a previous transaction that is not yet captured.

Reverse

The Reverse transaction immediately reverse the previous transaction and released any funds that were held on the card as a result of the initial authorization. The original retrieval number or transaction number is required. For example:

HCReversal1.GenKey = "GenKey from HCTerminalMgr.AuthenticateDevice";
HCReversal1.MerchantId = "300012345678901";
HCReversal1.RoutingId = "TSH950";
	
HCReversal1.TransactionType = HcreversalTransactionTypes.ttCreditAuthorizationReversal;
HCReversal1.TransactionAmount = HCRetail1.TransactionAmount;
HCReversal1.RetrievalNumber = HCRetail1.Response.RetrievalNumber;
HCReversal1.Reverse();

Batch Management and Transaction Searches

In the host capture system batch information is maintained by TSYS. At the end of the day you would typically close the open batch. You can also get details and a summary of transactions in the current batch, as well as details about a particular transaction.

When you authorize a transaction with HCRetail etc. there is a Response.BatchNumber field that is populated. This tells you which batch the transaction is a part of. Each new authorization will be added to the currently opened batch (unless the capture mode is set to something besides Normal - see the help files for more information about this case).

At the end of the business day to capture the batch you can use the HCBatchMgr component to close the current batch.

Closing a Batch To close the current open batch you can use the HCBatchMgr component. In addition to your merchant information you will also need to specify a value for the BatchNumber. For instance:

HCBatchMgr1.GenKey = "GenKey from HCTerminalMgr.AuthenticateDevice";
HCBatchMgr1.MerchantId = "300012345678901";
HCBatchMgr1.RoutingId = "TSH950";    
    
HCBatchMgr1.BatchNumber = currentBatchNumber;
HCBatchMgr1.CloseBatch();
string resultCode = HCBatchMgr1.Response.Code; // "00" indicates success.

Batch Summary and Details

The HCBatchMgr component also allows you to retrieve summary and detail information about a batch. The GetSummary method populates the SummaryReults collection which provides information such as the NetAmount for the batch, total number of refunds, etc.

The GetDetails method populates the DetailResults collection and provides information about each of the transactions in the batch including the last four digits of the card number, the card type, amout, retrieval number, transaction number, etc.

Transaction Details

The HCTransactionDetails component can be used to obtain detailed information about the original authorization. To use the component pass the TransactionNumber or RetrievalNumber from the original authorization response. After calling the GetDetails method the Response properties will hold information such as TransactionAmount, TransactionTime, CVVResult, CardType, AVSResult, ApprovalCode, etc.

Testing

TSYS provides testing facilities, in the form of a test merchant account. Since there is not a public merchant account for the TSYS Host Capture system you will need to contact TSYS directly to obtain a test account. Once you have an account follow the steps in Merchant Setup to get started.

Business Models

There are various fees involved with accepting and processing credit cards. In addition to the base percentage charged from the credit card companies, every type of credit card transaction has fees based on the level of risk associated with funding a transaction. These extra fees are called interchange fees, and they exist partially to encourage merchants to take security measures to reduce fraudulent charges. Card number, customer address information, card verification values, and track data all have an affect on the rate that the payment processor charges for credit card processing. Rates are dependant upon the likelihood of fraud given the type of transaction.

E-commerce
TSYS Integrator can be used in e-commerce transactions where users enter card data at a website. Typically, the interchange fees that are charged by payment processors for charging these cards will be in one of the highest brackets (these types of transactions are referred to as "card not present" transactions). This is because in e-commerce situations, with no physical evidence of the card and cardholder's presence, the chances of fraudulent transactions are much higher than in card present transactions. At a minimum a card number and expiration date are supplied for the transaction, but typically address information and the card verification value can be supplied to further ensure the cardholder's presence and secure better rates. Some merchants are using 3D-Secure technology to cut down on fraud and get lower interchange fees.
Direct Marketing (moto/phone)
Direct marketing is similar to e-commerce transactions in that cards are not present; however credit card numbers are communicated by the cardholder to the merchant by phone and this ensures a greater degree of protection against fraud. As a result of this telephone conversation, merchants receive a better rate from the payment processor. When a Direct Marketing authorization is sent to the payment processor, an indicator is supplied to let the processor know that the charge was received via telephone order. To configure the HCECommerce for Direct Marketing you must set the TransactionType property to ttMOTO.
Retail POS (Point of Sale)
Most businesses will accept credit cards via a card reader. In the past, many companies have leased credit card machines and obtained a dedicated phone line that is always connected to the processor (some have also used a modem to dial in to the processor for each transaction). Presently, businesses can simply install a card reader and software on a PC and process transactions over a secure Internet connection. The card reader scans data from the magnetic stripe found on the back of a credit card (Track 1 or Track 2 data). If both Track 1 and Track 2 data is available, Track 1 takes precedence over Track 2. Merchants should never store this track data. When the track data is submitted to the credit card processor, it is used to indicate that the card was physically available for the transaction. While this doesn't rule out all fraud, it does curtail fraud to such a degree that obtaining a "card present" transaction rate is significantly more desirable that obtaining a "card not present" rate.
In order to use Track 1 or Track 2 data, you must use set the CardMagenticStripe and CardEntryDataSource properties of the HCRetail component with the track data value returned by your card swiper. If you are Track 1 or Track 2 capable but you have to manually key-in a card, you should set the CardEntryDataSource property before calling Authorize to indicate the card was manually entered.

Miscellaneous

3D Secure Merchant Plug-in Interface (MPI)

E-commerce rates can be reduced greatly by using a technology called 3-D Secure MPI. This technology is implemented by a few card issuers:

Visa's Verified By Visa
MasterCard SecureCode
JCB J/Secure

Participating cardholders can authenticate directly with their bank via a secret question and answer prior to submitting credit card information. Participating merchants will receive three special properties from a 3D Secure authentication: a Cardholder Authentication Verification Value (CAVV), a Transaction Id (XID), and an Electronic Commerce Indicator (EDI). These values must be submitted along with your normal credit card authorization in order to qualify for a better rate (comparable to a "card present" transaction). The goal of this technology is to provide incentive for e-Commerce transactions by allowing for online merchants to obtain favorable rates, allow cardholders to feel more secure about shopping online, and to curb online fraud. E-commerce merchants who are interested in implementing 3-D Secure MPI should take a look at the /n software E-Payment Integrator toolkit, for which there is a sample tutorial on our website.

Level II and Level III

Level II and Level III transactions are supported. Sample code using these components is included in the help files. If you require any additional assistance, please contact our support team.

AVS

AVS (Address Verification Service) is where the address information of the customer is checked for accuracy during the authorization request to help prevent fraud. This information consists of a street address and zip code.

After the authorization is sent, the ResponseAVS property will contain the results of the address verification which can be used by the merchant to decide whether or not to honor the transaction and capture the funds or let it void.

CVV2

CVV2 (Card Verification Value 2), is an alphanumeric field that contains the three digit Visa "Card Verification Value 2", MasterCard "Card Verification Code" (CVC), or four-digit American Express "Card Identification Number" (CID). This value appears on the card signature line on the back of the credit card (or on the front of an AMEX card). The CVV2 value is an optional field which provides an extra level of identity verification during an authorization and can be used to determine if the customer is actually in possession of the credit card. If the CardCVVData property is set prior to calling the CCECommerce Authorize method, then when the response from the processor comes back the ResponseCVVResult property will show the result of the CVV check. Note that authorization does not necessarily depend on a successful CVV2 match. CVV values may not be stored by merchants.

Track 1 Data This is a variable length field with a maximum data length of 76 characters. For Retail Card Present transactions, if Track 1 data is available, it should be used. The CCRetail component's CardMagneticStripe property should be set with the entire unaltered track as read from a credit card's magnetic stripe, including all framing characters. The component then checks that the Track 1 data's parity and LRC values are correct before the data is converted from 6-bit ASCII on the card to the format required by the protocol in use.

Track 2 Data This is a variable length field with a maximum data length of 37 characters. For Retail Card Present transactions, if Track 1 data is not available and Track 2 data is, the CCRetail component's CardMagenticStripe property should be set with the entire unaltered track as read from a credit card's magnetic stripe, including all framing characters. The component then checks that the Track 2 data's parity and LRC values are correct before the data is converted from 4-bit ASCII encoded on the card to the format required by the protocol in use.

ECI/MOTO ECI (Electronic Commerce Indicator) is a 1-character transaction indicator identifying the type of transaction being authorized. This is also known as "MOTO" (Mail Order/Telephone Order). This value is used only for Card Not Present transactions. For a list of supported values, please consult the TSYS DetailRecord documentation of the ECI property. The ECI property should be set for Direct Marketing transactions and for 3D Secure authenticated transactions.

More Information

You can find out more about TSYS Integrator by visiting its product page at http://www.nsoftware.com/ibiz/. In addition, there is a general Credit Card Processing FAQ available on the nsoftware.com website. The trial download of TSYS Integrator includes working demo applications.

We appreciate your feedback. If you have any questions, comments, or suggestions about this article please contact our support team at kb@nsoftware.com.