Contents
- Getting Started
- The Life Cycle of a Credit Card Charge
- Business Models
- Terminal Capture vs. Host Capture
- Test Setup
- Transaction Types (Charge, Debit, Credit, Etc.)
- Batch Management and Transaction Searches
- Additional Functionality
- Get Support
Getting Started
4D Payments SDK provides dynamic capabilities for credit card processing for applications and websites running on any platform. 4D Payments SDK enables you to process transactions directly through major payment processors. The guide below details each step of credit card processing and shows how to use the components of 4D Payments SDK to process typical transactions.
Direct-to-processor transactions are typically authorized individually then charged to the payment processor in batches. Merchants can use 4D Payments SDK components to send stored batches of transactions – this process is known as terminal capture and is used to introduce TSYS Integrator in Getting Started with TSYS Integrator. This article details how to use the components to implement another method, host capture, which does not require merchants to put structures in place to securely store batches of transactions that have not yet been captured.
The first step is to determine if you want to use a payment gateway or work directly with a processor.
-
Direct to Processor
A payment processor (Fig. 1) is a service company that performs charges and settlements for credit card transactions. All credit card transactions are eventually processed through a credit card processing network such as TSYS Acquiring Solutions, Global Payments, Paymentech NetConnect, or First Data Merchant Services (FDMS). 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, including settlements (captures), credits, voids, etc. However, these aspects are resource-intensive and security-sensitive.
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: 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 settlement of authorized charges.
Fig. 2
The Life Cycle of a Credit Card Charge
All credit card charges take place in two stages: authorization and capture. The authorization step includes authenticating the customer and verifying 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.
In the capture step the previously authorized funds are transferred from the cardholder’s bank account to the merchant’s 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.
Business Models
The components 4D Payments SDK provide payment processing solutions for a variety of business models. The components provide the same, uniform interface for the card-present and card-not-present transaction types shown later in this article.
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
You can use 4D Payments SDK to process card-not-present transactions essential for e-commerce, such as users entering card data on your 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 also be supplied to further ensure the cardholder’s presence and secure better rates.
Direct Marketing
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 TSYSECommerce for Direct Marketing, set the TransactionType property to “dmtMOTO”.
Retail POS (Point of Sale)
In the past, many companies have leased credit card machines and obtained a dedicated phone line that was 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 are available, track 1 takes precedence over track 2. 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.
You can use 4D Payments SDK to provide this data: To use track 1 or track 2 data, set the CardMagneticStripe and CardEntryDataSource properties of the TSYSRetail component with the track data value returned by your card reader.
Terminal Capture vs. Host Capture
4D Payments SDK offers two different types of transaction settlement with TSYS: terminal capture and host capture. This tutorial shows how to authorize and settle transactions using host capture; for more information on using the terminal capture approach please see Getting Started with TSYS (4D Payments SDK). The guide below outlines both systems in more detail:
Terminal Capture
Terminal capture requires the merchant to store the detail aggregate returned after the processor authorizes a transaction. 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.
Host Capture
Host capture places the burden of storing information between the authorization and settlement on the TSYS servers. Although you will still maintain some transaction-specific information, such as response codes, Ids, etc., this approach allows the merchant to authorize transactions without having to store the aggregate between the authorization and settlement.
Test Setup
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.
You can set up the components of 4D Payments SDK to authenticate your application, device, or website using your merchant account credentials or using a test account. The system you choose to settle transactions affects how you will authenticate the application to the processor. TSYS provides a public test merchant account for the terminal capture system. 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.
As shown in the code below, when using the host capture system with TSYS you must use the TSYSHCTerminalMgr 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:
TSYSHCTerminalMgr1.MerchantId = "300012345678901";
TSYSHCTerminalMgr1.RoutingId = "TSH000";
TSYSHCTerminalMgr1.AuthenticationCode = "ABCD123456";
TSYSHCTerminalMgr1.MerchantZip = "85284";
TSYSHCTerminalMgr1.AuthenticateDevice();
string myGenKey = TSYSHCTerminalMgr1.Response.GenKey;
You can now process credit card transactions with 4D Payments SDK. A GenKey may be reactivated at any time by calling AuthenticateDevice again. Call DeactiveDevice to invalidate the current GenKey value.
Transactions (Charge, Debit, Credit, Etc.)
The components are designed to perform industry-specific types of transactions. The most common transaction types are below:
- CardValidator – Pre-Authorization
- TSYSHCECommerce – Card-not-present transactions
- TSYSHCRetail – Card-present credit card transactions
- TSYSHCDebit – Debit Card transactions
- TSYSHCReversal – Reverse previous authorizations
- TSYSHCAdjustment – Adjust previous authorizations before capturing
- TSYSHCBenefit – EBT card transactions
- TSYSHCGiftCard – Gift card transactions
- TSYSHCLevel3 – Level 3 transactions
Pre-Authorization
Pre-Authorization is used to help eliminate invalid submissions to the processor by verifying a correctly formatted card number and that the card is not expired. While a successful pre-authorization does not guarantee that the credit card is valid, it virtually eliminates bad authorization attempts due to accidental mistyping. 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. You can use the CardValidator component to check the validity of a card before submitting it to the processor for authorization. The component executes the offline checks below:
- Luhn digit check: an algorithm is used to determine if the digits of the card number could be a valid card number.
- Card type check: the card number digits are checked to ensure they are a valid card type.
- Expiration date check.
To use the CardValidator component, set the required credit card properties and call the ValidateCard method:
Cardvalidator1.CardExpMonth = 08;
Cardvalidator1.CardExpYear = 2017;
Cardvalidator1.CardNumber = "4444333322221111";
Cardvalidator1.ValidateCard();
if (Cardvalidator1.DigitCheckPassed && Cardvalidator1.DateCheckPassed)
{
Console.WriteLine("Card may be valid.");
Console.WriteLine("The card type is: " + Cardvalidator1.CardTypeDescription);
}
TSYSHCECommerce
The TSYSHCECommerce component is used to authorize transactions when the card is not present. You can use this component to make a Purchase, Void, or Credit transaction.
Sale
A sale authorizes a transaction and adds it to the open batch. For example:
TSYSHCECommerce1.Card.Number = "4444333322221111";
TSYSHCECommerce1.Card.ExpMonth = 1;
TSYSHCECommerce1.Card.ExpYear = 15;
TSYSHCECommerce1.Card.EntryDataSource = EntryDataSources.edsManualEntryNoCardReader;
TSYSHCECommerce1.TransactionAmount = "1250";
TSYSHCECommerce1.TransactionDesc = "Test trans";
TSYSHCECommerce1.TransactionNumber = 99;
TSYSHCECommerce1.Sale();
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 sale and the original amount. For example:
TSYSHCECommerce1.TransactionDesc = "Void RRN Test";
TSYSHCECommerce1.VoidTransaction("124520900193", "1250");
Credit
A credit is used to return funds to a card and is not based on a previous transaction. Because of this you must specify the card information when performing a credit. For example:
TSYSHCECommerce1.Card.Number = "4444333322221111";
TSYSHCECommerce1.Card.ExpMonth = 1;
TSYSHCECommerce1.Card.ExpYear = 15;
TSYSHCECommerce1.Card.EntryDataSource = EntryDataSources.edsManualEntryNoCardReader;
TSYSHCECommerce1.TransactionAmount = "1250";
TSYSHCECommerce1.TransactionDesc = "Credit test transaction";
TSYSHCECommerce1.TransactionNumber = 13;
TSYSHCECommerce1.Credit();
TSYSHCRetail
The TSYSHCRetail component is used to authorize card-present transactions. The component can be used to make a sale, credit, void, or tip adjustment.
Purchase
A purchase is a typical transaction where a card is authorized. For example:
TSYSHCRetail1.GenKey = "GenKey from HCTerminalMgr.AuthenticateDevice";
TSYSHCRetail1.MerchantId = "300012345678901";
TSYSHCRetail1.RoutingId = "TSH950";
TSYSHCRetail1.Card.Number = "4444333322221111";
TSYSHCRetail1.Card.ExpMonth = 1;
TSYSHCRetail1.Card.ExpYear = 15;
TSYSHCRetail1.Card.EntryDataSource = EntryDataSources.edsManualEntryTrack1Capable;
TSYSHCRetail1.TransactionAmount = "1250";
TSYSHCRetail1.TransactionDesc = "Test trans";
TSYSHCRetail1.TransactionNumber = 99;
TSYSHCRetail1.Sale();
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:
TSYSHCRetail1.GenKey = "GenKey from HCTerminalMgr.AuthenticateDevice";
TSYSHCRetail1.MerchantId = "300012345678901";
TSYSHCRetail1.RoutingId = "TSH950";
TSYSHCRetail1.TransactionDesc = "Void RRN Test";
TSYSHCRetail1.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:
TSYSHCRetail1.GenKey = "GenKey from HCTerminalMgr.AuthenticateDevice";
TSYSHCRetail1.MerchantId = "300012345678901";
TSYSHCRetail1.RoutingId = "TSH950";
TSYSHCRetail1.Card.Number = "4444333322221111";
TSYSHCRetail1.Card.ExpMonth = 1;
TSYSHCRetail1.Card.ExpYear = 15;
TSYSHCRetail1.Card.EntryDataSource = EntryDataSources.edsManualEntryTrack1Capable;
TSYSHCRetail1.TransactionAmount = "1250";
TSYSHCRetail1.TransactionDesc = "Credit test transaction";
TSYSHCRetail1.TransactionNumber = 13;
Tip Adjustment
A tip adjustment transaction is used to add a tip to a previously authorized sale before the batch is closed. The original retrieval number and original amount are required. For example:
TSYSHCRetail1.GenKey = "GenKey from HCTerminalMgr.AuthenticateDevice";
TSYSHCRetail1.MerchantId = "300012345678901";
TSYSHCRetail1.RoutingId = "TSH950";
TSYSHCRetail1.Card.Number = "4444333322221111";
TSYSHCRetail1.Card.ExpMonth = 1;
TSYSHCRetail1.Card.ExpYear = 15;
TSYSHCRetail1.Card.EntryDataSource = EntryDataSources.edsManualEntryTrack1Capable;
TSYSHCRetail1.TransactionAmount = "2450";
TSYSHCRetail1.TransactionDesc = "Adjust Tip Transaction";
TSYSHCRetail1.TransactionNumber = 102;
TSYSHCRetail1.Sale();
string rrn = TSYSHCRetail1.Response.RetrievalNumber;
TSYSHCRetail1.AdjustTip(rrn, "2450", "550");
TSYSHCDebit
The TSYSHCDebit component is used to authorize card-present debit transactions. The component can be used to make a sale, credit, or balance inquiry.
In order to process a debit transaction you will need a PIN pad that has been injected with a key by TSYS to obtain the DUKPT DES/3DES Encrypted Pin and the KSN (Key Sequence Number) values. These will be passed to the component via the DebitPIN and DebitKSN properties, respectively.
Sale
A sale is the most common transaction type. The Sale method sends a sale/purchase request to the TSYS server.
TSYSHCDebit1.GenKey = "GenKey from HCTerminalMgr.AuthenticateDevice";
TSYSHCDebit1.MerchantId = "300012345678901";
TSYSHCDebit1.RoutingId = "TSH950";
TSYSHCDebit1.CardTrack2Data = "9999999800002773=09121015432112345678";
TSYSHCDebit1.DebitPIN = "83C33384650827F6";
TSYSHCDebit1.DebitKSN = "4A00310459400004";
TSYSHCDebit1.TransactionAmount = "1250";
TSYSHCDebit1.TransactionDesc = "Test trans";
TSYSHCDebit1.TransactionNumber = 99;
//TSYSHCDebit1.CashBackAmount = "1000"; //Set CashBackAmount if cash back is desired
TSYSHCDebit1.Sale();
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:
TSYSHCDebit1.GenKey = "GenKey from HCTerminalMgr.AuthenticateDevice";
TSYSHCDebit1.MerchantId = "300012345678901";
TSYSHCDebit1.RoutingId = "TSH950";
TSYSHCDebit1.CardTrack2Data = "9999999800002773=09121015432112345678";
TSYSHCDebit1.DebitPIN = "83C33384650827F6";
TSYSHCDebit1.DebitKSN = "4A00310459400004";
TSYSHCDebit1.TransactionAmount = "1250";
TSYSHCDebit1.TransactionDesc = "Credit test transaction";
TSYSHCDebit1.TransactionNumber = 13;
TSYSHCDebit1.Credit();
Balance Inquiry
A balance inquiry returns the balance left on a card. For example:
TSYSHCDebit1.GenKey = "GenKey from HCTerminalMgr.AuthenticateDevice";
TSYSHCDebit1.MerchantId = "300012345678901";
TSYSHCDebit1.RoutingId = "TSH950";
TSYSHCDebit1.CardTrack2Data = "9999999800002773=09121015432112345678";
TSYSHCDebit1.DebitPIN = "83C33384650827F6";
TSYSHCDebit1.DebitKSN = "4A00310459400004";
TSYSHCDebit1.TransactionAmount = "106";
TSYSHCDebit1.TransactionDesc = "Test trans";
TSYSHCDebit1.TransactionNumber = 14;
TSYSHCDebit1.BalanceInquiry();
string currentBalance = TSYSHCDebit1.Response.Balance;
TSYSHCReversal
The TSYSHCReversal 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 reverses the previous transaction and releases 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:
TSYSHCReversal1.GenKey = "GenKey from HCTerminalMgr.AuthenticateDevice";
TSYSHCReversal1.MerchantId = "300012345678901";
TSYSHCReversal1.RoutingId = "TSH950";
TSYSHCReversal1.TransactionType = TsyshcreversalTransactionTypes.ttCreditAuthorizationReversal;
TSYSHCReversal1.TransactionAmount = TSYSHCRetail1.TransactionAmount;
TSYSHCReversal1.RetrievalNumber = TSYSHCRetail1.Response.RetrievalNumber;
TSYSHCReversal1.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.
You can use the TSYSHCBatchMgr component to close a batch of previously authorized transactions. When you authorize a transaction, the response from the server populates a ResponseBatchNumber field. This shows which batch the transaction is a part of. Each new authorization will be added to the current opened batch (unless the capture mode is set to something besides Normal – the Help documentation provides more information about capture modes).
Close a Batch
Call the CloseBatch method to close the current open batch. In addition to your merchant information you will also need to specify a value for the BatchNumber. For instance:
TSYSHCBatchMgr1.GenKey = "GenKey from HCTerminalMgr.AuthenticateDevice";
TSYSHCBatchMgr1.MerchantId = "300012345678901";
TSYSHCBatchMgr1.RoutingId = "TSH950";
TSYSHCBatchMgr1.BatchNumber = currentBatchNumber;
TSYSHCBatchMgr1.CloseBatch();
string resultCode = TSYSHCBatchMgr1.Response.Code; // "00" indicates success.
Batch Summary and Details
The TSYSHCBatchMgr component also allows you to retrieve summary and detail information about a batch. The GetSummary method populates the SummaryResults collection, which provides information such as the NetAmount for the batch, the 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, amount, retrieval number, transaction number, etc.
Transaction Details
The TSYSHCTransactionDetails 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.
Additional Functionality
When processing transactions through a payment processor, transactions that have already been authorized are typically sent to the processor in batches. You can use the Host Capture method to authorize transactions without having to store an aggregate of transactions before closing a batch. Use the TSYSBatchMgr component to close the batch of already authorized charges for that day. Other components provide additional authentication options and industry-specific transaction types such as healthcare, restaurant, and hotel/lodging.
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 and Track 2 Data
In order to use Track 1 or Track 2 data, you must use set the CardMagneticStripe and CardEntryDataSource properties of the TSYSRetail component to the track data value returned by your card reader.
If your card reader is 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.
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 TSYSHCRetail 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 TSYSHCRetail 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.
If you are track 1 or track 2 capable but you have to manually key-in a card, set the CardEntryDataSource property before calling Authorize to indicate the card was manually entered. Note that merchants should never store track data.
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.
ECI/MOTO
The ECI property should be set for Direct Marketing transactions and for 3D Secure authenticated transactions. 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. To configure the TSYSECommerce component to process direct marketing transactions you must set the TransactionType property to “dmtMOTO”. For a list of supported values, please consult the TSYS DetailRecord documentation of the ECI property.
Get Support
You can find out more about 4D Payments SDK by visiting its product page at https://4dpayments.com/sdk/. Additional information is available in the 4D Payments Credit Card Processing FAQ. You will find the code examples above in the ready-to-compile demo applications included with 4D Payments SDK. Before you can go live, you will need to create a merchant account that supports TSYS with your bank. If you do not already have a merchant account, contact our support team, and they can help you with this.