Requirements: 4D Payments SDK
Chapter Listing
- Getting Started
- The Life Cycle of a Credit Card Charge
- Terminal Capture vs. Host Capture
- Business Models
- Test Setup
- Transactions Types (Charge, Settle, Credit, Etc.)
- International Support
- Additional Functionality
- Get Support
Getting Started
You can use 4D Payments SDK to enable direct-to-processor payment processing in applications and websites on any development platform. 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.
The first step is to determine whether you will settle transactions directly with a processor or through an online payment gateway.
-
Direct to Processor
All credit card transactions are ultimately handled by a credit card processing network such as TSYS Acquiring Solutions, Global Payments, Paymentech NetConnect, or First Data Merchant Services (FDMS Integrator). A payment processor authorizes charges and makes settlements (payments) for credit card transactions. 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. However, some of these aspects are resource-intensive and require that you follow the best practices for securely transmitting and storing data. Not only do you perform the authorizations, but you also have control of all other types of transactions including settlements (captures), credits, voids, etc.
Fig. 1 -
Internet Payment Gateways
Internet payment gateways are value-added services that work with you (the merchant) and a back-end processor. 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 settling 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 obtaining authorization for a certain dollar amount from the customer, including ensuring that the card has enough funds to cover the amount. No 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 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 TSYSRetail and TSYSECommerce components are used to make authorizations and hold funds during a credit card transaction. The TSYSSettle component performs capture; this process is described in the next section.
Terminal Capture vs. Host Capture
4D Payments SDK offers two different types of processing with TSYS: Terminal Capture and Host Capture. For more information on using the host capture approach please see the 4D Payments SDK (TSYS Host Capture) guide. The example transactions in this tutorial use terminal 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 without requiring 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 you, as the merchant, to authorize transactions without having to store the aggregate between the authorization and settlement.
Business Models
The components of 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, 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.
Direct Marketing
Additional authorization information is used by processors to distinguish direct marketing transactions from other card-not-present transactions. 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. This ensures a greater degree of protection against fraud.
Retail POS (Point of Sale)
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. 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.
Test Setup
Before the production system goes live, you will need a merchant account that supports TSYS. 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 at predefined times in a 24-hour period. If you’re not sure how to go about setting up a merchant account, our support team can help you set one up correctly.
TSYS provides testing facilities in the form of a public test merchant account – when you are ready to go live, you will need to provide your merchant authentication credentials provided to you by your bank and TSYS. The code below shows the properties required to authorize the merchant, using a test account:
// Set merchant-setup properties
// Some of these values need to be obtained from your bank,
// and some from TSYS
TSYSECommerce1.Merchant.BankId = "999995";
TSYSECommerce1.Merchant.CategoryCode = "5999";
TSYSECommerce1.Merchant.Name = "4DPAYMENTS";
TSYSECommerce1.Merchant.Number = "999999999911";
TSYSECommerce1.Merchant.ServicePhone = "800-1234567";
TSYSECommerce1.Merchant.State = "NC";
TSYSECommerce1.Merchant.StoreNumber = "0011";
TSYSECommerce1.Merchant.TerminalNumber = "9911";
TSYSECommerce1.Merchant.TimeZone = "705"; //North Carolina
TSYSECommerce1.Merchant.Zip = "27609";
Transactions (Charge, Settle, Credit, Etc.)
The components allow you to perform any of the transactions below:
Pre-Authorization
You can use the CardValidator component to eliminate invalid submissions to the processor. 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. This component performs the following offline checks:
- The card is not expired
- The Luhn digit check, an algorithm that determines whether the card number could belong to a valid card
- The card type is valid
Below is an example of using the CardValidator component:
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);
}
Authorize
The Authorize method of the TSYSRetail and TSYSECommerce components 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 properties break down the different parts of the response from the processor and can be used for integration into other systems. 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 can 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 authorize a card-not-present with just a few lines of code:
// Set card and customer properties
TSYSECommerce1.Card.ExpMonth = 01;
TSYSECommerce1.Card.ExpYear = 2012;
TSYSECommerce1.Card.Number = "4444333322221111";
//Set Transaction Properties
TSYSECommerce1.TransactionAmount = "100"; //$1.00
TSYSECommerce1.TransactionNumber = 1;
TSYSECommerce1.TransactionType = TsysecommerceTransactionTypes.dmtECommerce;
TSYSECommerce1.Authorize();
The TSYSRetail component features the same interface and is used for card-present transactions:
//Set Transaction Properties
TSYSRetail1.TransactionAmount = "100"; //$1.00
TSYSRetail1.TransactionNumber = 0001;
TSYSRetail1.IndustryType = TsysretailIndustryTypes.sitRetail;
TSYSRetail1.Card.MagneticStripe = "B4444333322221111^SMITH/JOHN E ^03<snip>...";
TSYSRetail1.Authorize();
Because the capture of funds takes place at a different time than the initial authorization, the response data for the authorized transaction needs to be securely recorded for later use. You can accomplish this by storing the aggregate returned by the GetDetailAggregate method; this method returns the contents of the transaction in an XML aggregate that can be easily passed to the TSYSSettle component during the capture phase.
Settle
After making authorizations with the TSYSECommerce and TSYSRetail components, the response data from those authorization approvals can be used to subsequently settle (capture) the transactions. Captures are performed using the SendSettlement method of the TSYSSettle component.
The DetailRecords collection of the TSYSSettle component is set to the response data of the previous authorization(s). This data is returned by the GetDetailAggregate method of TSYSECommerce or TSYSRetail. In .NET and Java, DetailRecords is a collection that new records can be added to. In other editions you must set the DetailRecordCount property to indicate the number of records that will be sent in the settlement. Then the DetailRecordAggregate property must be used to add individual records. The DetailRecordAggregate 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.
TSYSEcommerce1.Authorize();
TSYSSettle.DetailRecords.Add(new TSYSRecordType(TSYSEcommerce1.GetDetailAggregate()));
TSYSSettle.SendSettlement();
In the example above, a batch of transactions is captured. The authorized transactions that are ready for settlement are added to the DetailRecords collection of TSYSSettle. When SendSettlement is called, the TSYSSettle 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. After correcting the corresponding transaction, you will need to resend the entire batch. To avoid duplicate charges, set the BatchNumber property of the component to the appropriate batch number.
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. Use a void when a previously authorized transaction does not get captured, so funds are never captured and no charge appears to the customer.
The TSYSSettle component can perform a 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 TSYSRetail or TSYSECommerce since the credit is not tied to a particular previous transaction. Instead you must create a new detail record which represents the credit.
TSYSDetailRecord1.TransactionType =
TsysdetailrecordTransactionTypes.dttOffLineCredit;
TSYSDetailRecord1.IndustryType = TsysdetailrecordIndustryTypes.sitRetail;
TSYSDetailRecord1.TransactionNumber = 0001;
TSYSDetailRecord1.CardNumber = "4444333322221111";
TSYSDetailRecord1.AuthorizedAmount = "0";
TSYSDetailRecord1.SettlementAmount = "200";
TSYSSettle1.DetailRecords.Add(
new TSYSRecordType(TSYSDetailRecord1.GetDetailAggregate());
TSYSSettle1.IndustryType = TsyssettleIndustryTypes.sitRetail;
TSYSSettle1.SendSettlement();
Void
As explained earlier, a void is for a transaction that has been authorized, but not captured. 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 TSYSSettle – similar to performing a credit.
TSYSDetailRecord1.ParseAggregate(TSYSECommerce1.GetDetailAggregate());
TSYSDetailRecord1.VoidTransaction = true;
TSYSSettle1.DetailRecords.Add(
new TSYSRecordType(TSYSDetailRecord1.GetDetailAggregate()));
TSYSSettle1.IndustryType = TsyssettleIndustryTypes.sitDirectMarketing;
TSYSSettle1.SendSettlement();
Note that the amounts of void transactions are not factored into the value of BatchNetDeposit. If you do not perform a void and you do not capture the authorized funds, the authorized transaction will eventually 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, you will be given an authorization number if the transaction is authorized.
To complete the forced transaction, you must use the SendSettlement method. First, use the TSYSDetailRecord component to create a new detail record which represents the force transaction. This must include the ResponseApprovalCode property set to the approval code obtained from the card issuer on the telephone. In addition, set the TransactionType property of the TSYSDetailRecord component to ForceCardNotPresent (3) or ForceCardPresent (4), depending on whether the card is present or not.
TSYSDetailRecord1.TransactionType = TsysdetailrecordTransactionTypes.dttForceCardNotPresent;
TSYSDetailRecord1.IndustryType = TsysdetailrecordIndustryTypes.sitDirectMarketing;
TSYSDetailRecord1.ResponseApprovalCode = "123456";
TSYSDetailRecord1.CardNumber = "4444333322221111";
TSYSDetailRecord1.SettlementAmount = "600";
TSYSDetailRecord1.TransactionNumber = 100;
TSYSDetailRecord1.TransactionDate = "041907";
TSYSDetailRecord1.TransactionTime = "180943";
TSYSSettle1.DetailRecords.Add(
new TSYSRecordType(TSYSDetailRecord1.GetDetailAggregate()));
TSYSSettle1.IndustryType = TsyssettleIndustryTypes.sitDirectMarketing;
TSYSSettle1.SendSettlement();
Debit Support
Debit transactions are supported through the use of the TSYSDebit component. In order to process a debit transaction you will need a PIN pad that has been injected with a key by TSYS in order 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.
Below is an example of a debit sale using DebitPIN, DebitKSN, and the track 2 data from a test card.
TSYSDebit1.Merchant.BankId = "999995"; //(BIN Number)
TSYSDebit1.Merchant.Number = "888000002447";
TSYSDebit1.Merchant.Name = "TEST MERCHANT";
TSYSDebit1.Merchant.TerminalNumber = "1515";
TSYSDebit1.Merchant.StoreNumber = "5999";
TSYSDebit1.Merchant.CategoryCode = "5999";
TSYSDebit1.Merchant.City = "Durham";
TSYSDebit1.Merchant.State = "NC";
TSYSDebit1.Merchant.Zip = "27713";
TSYSDebit1.Merchant.TimeZone = "705";
TSYSDebit1.MerchantABANumber = "123456789";
TSYSDebit1.MerchantSettlementAgent = "V123";
TSYSDebit1.AgentBankNumber = "000000";
TSYSDebit1.AgentChainNumber = "111111";
TSYSDebit1.ReimbursementAttribute =
TsysdebitReimbursementAttributes.raStandardRetail;
TSYSDebit1.SharingGroup = "GWQEV5";
TSYSDebit1.IndustryType = TsysdebitIndustryTypes.sitRetail;
TSYSDebit1.TransactionNumber = 1;
TSYSDebit1.DebitPIN = "83C33384650827F6";
TSYSDebit1.DebitKSN = "4A00310459400004";
TSYSDebit1.TransactionAmount = "200";
TSYSDebit1.CardTrack2Data = "9999999800002773=09121015432112345678";
TSYSDebit1.Sale();
International Support
International Currencies
Ordinarily, the 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 TSYS processor, and set the MerchantCurrencyCode to “124” for Canadian dollars.
International Merchant Accounts
TSYS supports merchant accounts with banks outside of the U.S. If you have a non-U.S. merchant account, contact your bank about creating a merchant account set up for the TSYS 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.
Additional Functionality
You can use the TSYSRetail and TSYSECommerce components of 4D Payments SDK to authorize and settle card-present and card-not-present transactions. Other components provide additional authentication options and industry-specific transaction types such as healthcare, restaurant, and hotel/lodging. 4D Payments SDK also supports debit card transactions and Level II and III purchases.
ECI/MOTO
To configure the TSYSECommerce component to process direct marketing transactions you must set the TransactionType property to “dmtMOTO”. The ECI property should be set for direct marketing transactions and for 3-D Secure authenticated transactions. The 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 TSYSDetailRecord documentation of the ECI property.
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 TSYSECommerce 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. Also note that 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, set the CardEntryDataSource property before calling Authorize to indicate the card was manually entered. Note that merchants should never store track data.
Track 1 Data
This is a variable-length field with a maximum data length of 76 characters. For card-present retail transactions, if track 1 data is available, it should be used. The TSYSRetail component’s CardMagneticStripe property should be set to the entire unaltered track, as read from the 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 card-present retail transactions, if track 1 data is not available and track 2 data is, the TSYSRetail component’s CardMagneticStripe property should be set to the entire unaltered track, as read from the 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.
Level II and Level III
Level II and Level III transactions are supported by the TSYSLevel2 and TSYSLevel3 components. Sample code using these components is included in the help files. If you require any additional assistance, please contact our support team.
Get Support
You can find out more about 4D Payments SDK here. Additional information is available in the 4D Payments Credit Card Processing FAQ. You will find the ready-to-compile code examples above in the included demo applications. 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.