Products
Support
Downloads
Purchase
Company
Subscriptions
Search: 
Tutorial - Getting Started with Vital/TSYS Integrator

By Lance Robinson - Technical Evangelist, /n software
James Neeley - E-Commerce Support, /n software.
and Spencer Brown - E-Commerce Support, /n software.

Requirements:

  • Vital/TSYS Integrator
  • Before you can go live, you'll need a merchant account with your bank that supports Vital (Vital 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

  1. Getting Started
  2. Vital/TSYS Integrator
  3. The Life Cycle of a Credit Card Charge
  4. PreAuthorize
  5. Transactions (Charge, Settle, Credit, Etc.)
  6. Debit Support
  7. Testing
  8. Business Models
  9. International Support
  10. Miscellaneous
  11. 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 Vital/TSYS Acquiring Solutions, 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 Vital/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 backend 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 Vital/TSYS or using an Internet payment gateway.

If you're working with the Vital/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 Vital. 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.

Vital/TSYS Integrator

Processing credit card transactions with your application is extremely easy using the Vital/TSYS Integrator. Vital/TSYS Integrator can be used to add credit card transaction processing to your application by communicating directly with the Vital Processing Services processor. The Vital/TSYS Integrator contains seven components: CCSettle, CCECommerce, CCRetail, DetailRecord, Level2Extension, Level3Extension, and CCCharge (for backwards compatibility with previous versions of the toolkit) which I will discuss in this article.

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.

PreAuthorize

The PreAuthorize method of the CCECommerce component 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. The PreAuthorize method performs a Luhn digit check (in which a mathematical algorithm is used to determine if the digits of the card number could be a valid card number), a card type check (in which the card number digits are checked to make sure they are a valid card type, e.g. Visa, MasterCard, Amex, etc), and finally an expiration date check.

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 this offline PreAuthorize method to avoid submitting errant authorization requests to the processor.

Transactions (Charge, Settle, Credit, Etc.)

The CCRetail and CCECommerce components are used to perform Charges only. The CCSettle is used to settle those transactions, as well as to perform other types of transactions (e.g. credit, force).

Authorize

The CCRetail and CCECommerce components' Authorize method sends an authorization request to the processor. When the method is complete, the ResponseCode property will indicate the status of the request (whether or not it was approved). The response code merely indicates that funds were available and were put on hold for the merchant. The response code does not indicate that the transaction passed any sort of fraud tests. You should inspect the values of the ResponseAVS and ResponseCVVResult properties to determine if you want to honor the transaction and capture the funds or let the transaction be voided.

You can perform an authorization with just a few lines of code: 

        // Set card and customer properties			
	Ccecommerce1.CardExpMonth = "01";
	Ccecommerce1.CardExpYear = "08";
	Ccecommerce1.CardNumber = "4444333322221111";
				
	// Set merchant-setup properties
	// Some of these values need to be obtained from your bank, 
	// and some from Vital		
	Ccecommerce1.MerchantBankId = "999995";		
	Ccecommerce1.MerchantCategoryCode = "5999";
	Ccecommerce1.MerchantName = "NSOFTWARE";
	Ccecommerce1.MerchantNumber = "999999999911";
	Ccecommerce1.MerchantServiceNumber = "800-1234567";
	Ccecommerce1.MerchantState = "NC";
	Ccecommerce1.MerchantStoreNumber = "0011";
	Ccecommerce1.MerchantTerminalNumber = "9911";
	Ccecommerce1.MerchantTimeZone = "705";  //North Carolina		
	Ccecommerce1.MerchantZip = "27609";
			
	//Set Transaction Properties
	Ccecommerce1.TransactionAmount = "100";  //$1.00
	Ccecommerce1.TransactionNumber = "0001";
	Ccecommerce1.TransactionType = CcecommerceTransactionTypes.ttECommerce;
	Ccecommerce1.Authorize();

Or with CCRetail: 

				
	// Set merchant-setup properties
	// Some of these values need to be obtained from your bank, 
	// and some from Vital		
	Ccretail1.MerchantBankId = "999995";		
	Ccretail1.MerchantCategoryCode = "5999";
	Ccretail1.MerchantName = "NSOFTWARE";
	Ccretail1.MerchantNumber = "999999999911";
	Ccretail1.MerchantLocation = "Durham";
	Ccretail1.MerchantState = "NC";
	Ccretail1.MerchantStoreNumber = "0011";
	Ccretail1.MerchantTerminalNumber = "9911";
	Ccretail1.MerchantTimeZone = "705";  //North Carolina		
	Ccretail1.MerchantZip = "27609";
			
	//Set Transaction Properties
	Ccretail1.TransactionAmount = "100";  //$1.00
	Ccretail1.TransactionNumber = "0001";
	Ccretail1.TransactionType = CcretailIndustryTypes.itRetail;
	Ccretail1.AuthorizeTrack1("B4444333322221111^SMITH/JOHN E ^03<snip>...");
You can cut and paste this code into your own application and make a live test transaction with the Vital processor.

You'll notice that the code above sets a lot of Merchant properties. These values coded above are for a live test account, which you can freely use during testing. When you go live, you'll need to obtain the correct values for your own account from your bank and from Vital.

Important: Since the capture of funds takes place at a different place in time from the initial authorization, the response data for the authorized transaction needs to be securely recorded for later use. It is easiest to store the aggregate returned by the GetDetailAggregate method, since it contains the contents of the transaction in an XML aggregate that is easily passed to the CCSettle component during the capture phase. Alternatively, the Response properties break down the response from the processor into its different parts and can be used for integration into other systems.

Settle

After making any number of authorizations with the CCECommerce or CCRetail component, the response data from those authorization approvals can be used to "settle" the transactions by capturing them. Captures are performed using the CCSettle component's SendSettlement method.

After setting the merchant properties to the same values as those set to the CCECommerce or CCRetail component, the CCSettle component's DetailAggregate property array should be set to contain the response data of the previous authorization(s). The DetailAggregate property is an array, indexed from 0 to DetailRecordCount -1 (the number of transactions to capture), in which each index corresponds to a particular authorized transaction.

When SendSettlement is called, the CCSettle component sends these detail records to the processor for capturing. The ResponseCode property can be used to determine the success state of the settlement. If errors occur during the settlement, the ResponseCode property will return "RB" (Rejected Batch), and the ErrorSequenceNumber, ErrorDataFieldNumber, and ErrorData properties will indicate which transaction could not be processed. Should this occur, corrections should be made to the corresponding transaction, and the entire batch should be sent again using the same BatchNumber to avoid duplicate charges.

In the example below, a batch of transactions is being captured. The response data from previous transactions is stored in a string array named transAggregates. DetailRecordCount is set to the number of authorized transactions that have been recorded in transAggregates (the aggregates returned by CCECommerce or CCRetail's GetDetailAggregate method for all of the authorized transactions that are ready for settlement), and the DetailAggregate property array indices get set to the corresponding index in transAggregates. 

	CCSettle1.BatchNumber = txtBatchNumber.Text;

	// Set Merchant properties
	Ccsettle1.MerchantBankId = "999995";
	Ccsettle1.MerchantCategoryCode = "5999";
	Ccsettle1.MerchantCountryCode = "840";  //US
	Ccsettle1.MerchantCurrencyCode = "840";  //US Dollars
	Ccsettle1.MerchantLanguage = "00"; //English
	Ccsettle1.MerchantName = "NSOFTWARE";
	Ccsettle1.MerchantNumber = "999999999911";
	Ccsettle1.MerchantLocation = "800-1234567";
	Ccsettle1.MerchantState = "NC";
	Ccsettle1.MerchantStoreNumber = "0011";
	Ccsettle1.MerchantTerminalNumber = "9911";
	Ccsettle1.MerchantTimeZone = "705";  //North Carolina		
	Ccsettle1.MerchantZip = "27609";
	
	Ccsettle1.AgentBankNumber = "000000";
	Ccsettle1.AgentChainNumber = "000000";
	Ccsettle1.TerminalId = "00000001";
	Ccsettle1.MerchantLocationNumber = "00001";
	
        //E-Commerce
	Ccsettle1.IndustryType = CcsettleIndustryTypes.itDirectMarketing;
	//Set Detail record properties
         Ccsettle1.DetailRecordCount = transAggregates.Length;
         for (int i=0; i< transAggregates.Length; i++)
         {
	      Ccsettle1.DetailAggregate[i] = transAggregates[i];
         }

	// Do settlement
	Ccsettle1.SendSettlement();

Credit

When money needs to be returned to a customer, a credit transaction is used. This is sometimes confused with a void, but the two are very different. A credit is used to return all or part of the funds of a previously captured transaction back to the customer. A void is simply when a previously authorized transaction does not get captured, so funds are never captured and no charge appears to the customer.

The CCSettle component can perform the credit using the SendSettlement method in conjunction with the DetailRecord component. This can be done at any time or along with the rest of the transactions during the normal settlement process.

When performing a credit, you do not use the aggregate from CCRetail or CCECommerce since the credit is not tied to a particular previous transaction. Instead you must fill out other properties for a new detail record which represents the credit. 


      Detailrecord1.TransactionType = 
           DetailrecordTransactionTypes.dttOffLineCredit;
      Detailrecord1.IndustryType = DetailrecordIndustryTypes.itRetail;
      Detailrecord1.TransactionNumber = 0001;
      Detailrecord1.CardNumber = "4444333322221111";
      Detailrecord1.AuthorizedAmount = "0";
      Detailrecord1.SettlementAmount = "200";

      // Set Merchant properties for CCSettle
      ...
      
      Ccsettle1.DetailRecordCount = 1;
      Ccsettle1.DetailAggregate[0] = Detailrecord1.GetDetailAggregate();
      Ccsettle1.IndustryType = CcsettleIndustryTypes.itRetail;
      Ccsettle1.SendSettlement();

Void

As explained earlier, a void is for a transaction that has been authorized, but not captured. This is done before any funds have been actually transferred. A void cancels the originally authorized transaction so it will not be captured.

To perform a void, you can use the DetailRecord component in conjunction with CCSettle similarly to performing a Credit. 

      Detailrecord1.ParseAggregate(Ccecommerce1.GetDetailAggregate());
      Detailrecord1.VoidTransaction = true;

      // Set Merchant properties for CCSettle
      ...
      
      Ccsettle1.DetailRecordCount = 20;
      Ccsettle1.DetailAggregate[0] = Detailrecord1.GetDetailAggregate();
      ...
      Ccsettle1.IndustryType = CcsettleIndustryTypes.itDirectMarketing;
      Ccsettle1.SendSettlement();

Note that Void transaction amounts are not factored into the BatchNetDeposit. If you do not perform a Void and you do not capture the authorized funds, after a period of time the authorized transaction will be timed out by the processor, and the hold on the funds will go away.

Force

Sometimes the processor will respond to your authorization request with instructions to "call". In these situations, you must call the credit card issuer to achieve authorization for the transaction. During the phone conversation with the card issuer, if the transaction is authorized, you will be given an authorization number.

To complete the forced transaction, you must use the SendSettlement method. Use the DetailRecord component to create a new detail record which represents the force transaction. This must include the ResponseApprovalCode property, which should be set to the approval code obtained from the card issuer on the telephone. In addition, set the TransactionType property of the DetailRecord component to ForceCardNotPresent (3) or ForceCardPresent (4) depending on whether the card is present or not. 


      Detailrecord1.TransactionType = 
           DetailrecordTransactionTypes.dttForceCardNotPresent;
      Detailrecord1.IndustryType = DetailrecordIndustryTypes.itDirectMarketing;
      Detailrecord1.ResponseApprovalCode = "123456";
      Detailrecord1.CardNumber = "4444333322221111";
      Detailrecord1.SettlementAmount = "600";
      Detailrecord1.TransactionNumber = 100;
      Detailrecord1.TransactionDate = "041907";
      Detailrecord1.TransactionTime = "180943";

      // Set Merchant properties for CCSettle
      ...
      
      Ccsettle1.DetailRecordCount = 1;
      Ccsettle1.DetailAggregate[0] = Detailrecord1.GetDetailAggregate();
      Ccsettle1.IndustryType = CcsettleIndustryTypes.itDirectMarketing;
      Ccsettle1.SendSettlement();

Debit Support

With the Vital/TSYS Integrator, Debit transactions are supported through the use of the CCDebit component. In order to process a debit transaction you will need a PIN Pad that has been injected with a key by Vital/TSYS. Once you have a PIN Pad you will need to obtain the DUKPT DES/3DES Encrypted Pin and the KSN (Key Sequence Number) values. These will be passed to the component via the CardPIN and CardKSN properties respecitively.

Below is an example of a debit sale using CardPIN, CardKSN, and the track 2 data from a test card. 

      CCDebit1.MerchantBankId = "999995"; //(BIN Number)
      CCDebit1.MerchantNumber = "888000002447";
      CCDebit1.MerchantName = "TEST MERCHANT";
      CCDebit1.MerchantTerminalNumber = "1515";
      CCDebit1.MerchantStoreNumber = "5999";
      CCDebit1.MerchantCategoryCode = "5999";
      CCDebit1.MerchantLocation = "Durham";
      CCDebit1.MerchantState = "NC";
      CCDebit1.MerchantZip = "27713";
      CCDebit1.MerchantTimeZone = "705";
      CCDebit1.MerchantABANumber = "123456789";
      CCDebit1.MerchantSettlementAgent = "V123";
      CCDebit1.AgentBankNumber = "000000";
      CCDebit1.AgentChainNumber = "111111";
      CCDebit1.ReimbursementAttribute = 
            CcdebitReimbursementAttributes.raStandardRetail
      CCDebit1.SharingGroup = "GWQEV5"; 
      CCDebit1.IndustryType = CcdebitIndustryTypes.itRetail
  
      CCDebit1.TransactionNumber = "1";
      CCDebit1.CardPIN = "83C33384650827F6";
      CCDebit1.CardKSN = "4A00310459400004";
      CCDebit1.TransactionAmount = "200";
      CCDebit1.CardTrack2Data = "9999999800002773=09121015432112345678";
      CCDebit1.Purchase();

Testing

Vital provides testing facilities, in the form of a public test merchant account. To use this test merchant account, all that is necessary is to set the MerchantBankId property to "999995" and the MerchantZip property to a valid U.S. zip code. When you are ready to go live, make sure that you are setting all of the Merchant properties using the values provided to you by your bank and Vital.

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

    Vital/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 set this indicator with CCCharge, you need to set the ECI property (electronic commerce indicator). For direct marketing transactions, this will most often be set to the default value of "7" (one time occurrence of a mail/telephone order transaction).

  • 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 the AuthorizeTrack1 or AuthorizeTrack2 method of the CCRetail 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 use the ManualAuthorize method of the CCRetail component.

International Support

  • International Currencies

    Ordinarily, the Vital/TSYS Integrator accepts transactions in U.S. Dollars, but Canadian Dollars are also supported. If you wish to accept Canadian Dollars, you must first configure your merchant account with the Vital processor, and set the MerchantCurrencyCode to "124" for Canadian Dollars.

  • International Merchant Accounts

    Vital supports merchant accounts with banks outside of the U.S. If you have a non-U.S. merchant account, contact your bank to see if they are able to set you up with the Vital processor. If you are using a non-U.S. merchant account, the MerchantCountryCode property should be set to the code corresponding to the country in which your bank is located. Please contact your bank to obtain this code.

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 IP*Works! 3-D Secure MPI toolkit, for which there is a sample tutorial on our website.

Level II and Level III

Level II and Level III transactions are supported by the Level2Extension and Level3Extension components. 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 AuthorizeTrack1 method should be used 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 AuthorizeTrack2 method should be used 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 Vital/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 Vital/TSYS Integrator by visiting its product page at http://www.nsoftware.com/ibiz/vital/. In addition, there is a general Credit Card Processing FAQ available on the nsoftware.com website. The trial download of Vital/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.
| About | Privacy Policy | Terms of Use |
© Copyright 2008 /n software inc.