Contents
- Getting Started
- The Life Cycle of a Credit Card Charge
- Business Models
- Test Setup
- Transaction Types (Charge, Settle, Credit, Etc.)
- Debit Support
- Additional Functionality
- More Information
Getting Started
You can use 4D Payments SDK to process payments directly through the 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
All credit card transactions are ultimately processed by a credit card processing network such as Paymentech, Global Payments, TSYS, or First Data Merchant Services (FDMS). By processing transactions directly through the payment processor, you can avoid the fees charged by payment gateways and retain control over all aspects of the transactions. However, some of these aspects are resource-intensive and security-sensitive.
Fig. 1 -
Internet Payment Gateways
Internet payment gateways are value-added services that work with 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 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. For transactions involving shipping, the capture should not take place until the merchant product has shipped the product to the customer.
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.
As an alternative to the manual settlement process, Paymentech offers an account feature called Host Auto Close. If your Paymentech account is set up with the Host Auto Close feature, no end-of-day batch processing is required from the merchant: The host will close the current open batch at a designated time each day. In order for the merchant’s batch to be included in the Paymentech Host Auto Close process, the merchant parameter file on the host must indicate that the merchant is auto close-capable. Without this flag being set, the merchant’s transactions must be settled with a manual batch release using the PTHostSettle component.
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.
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 charged by the processor for e-commerce and other card-not-present transactions are in one of the highest brackets. This is because the chances of fraudulent e-commerce transactions are much higher than in card-present transactions. At a minimum the card number and expiration date are supplied for the transaction; typically address information and the card verification value can also be supplied to further verify the cardholder and secure better rates. Additionally, you can use 3-D Secure technology to cut down on fraud and reduce interchange fees.
Direct Marketing
Direct marketing transactions are similar to e-commerce transactions in that cards are not present; however, as a result of the transaction occurring through a 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. Because many online gateways do not make a distinction between e-commerce and direct marketing transactions, you may need to process direct marketing transactions directly.
Retail/Point of Sale (POS)
Businesses can simply install a card reader and software on a PC and start processing transactions over a secure Internet connection. The card reader scans “track data” from the magnetic stripe found on the back of a credit card. 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.
Test Setup
Before you can start processing transactions, you will need to provide your merchant account credentials to the components that control the connection to the processor. PTechECommerce authorizes and settles card-not-present transactions with Paymentech; PTechRetail performs card-present transactions. The values coded below use the public Paymentech test account. When you go live, you will need to obtain the correct values for your own account from your bank and from Paymentech. You may also contact Paymentech to obtain your own test account.
//Merchant setup
PTechECommerce1.Server = "https://netconnectvar.paymentech.net/NetConnect/controller";
PTechECommerce1.MerchantNumber = "700000000125";
PTechECommerce1.TerminalNumber = "103";
PTechECommerce1.ClientNumber = "0002";
PTechECommerce1.UserId = "4dpayments01";
PTechECommerce1.Password = "4dpaymentspw01";
PTechRetail1.Server = "https://netconnectvar.paymentech.net/NetConnect/controller";
PTechRetail1.MerchantNumber = "700000000125";
PTechRetail1.TerminalNumber = "103";
PTechRetail1.ClientNumber = "0002";
PTechRetail1.UserId = "4dpayments01";
PTechRetail1.Password = "4dpaymentspw01";
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 avoid submitting errant authorization requests to the processor. 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. The CardValidator component does not connect to the Internet; instead, it computes mathematical algorithms to validate the card information. These checks include:
- 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. An example is below:
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);
}
Auth Only
An auth-only transaction is used to verify and reserve the cardholder’s open-to-buy funds available at the time of purchase. This transaction will NOT be added to the batch. To later capture an auth-only transaction, you will need to securely store the approval code returned in the response from the server. The ResponseApprovalCode property of the component contains the approval code for the last transaction authorized. (The Response properties break down the different parts of the response from the processor and can be used for integration into other systems.) This will add the transaction to the batch.
You can perform an auth-only transaction with just a few lines of code. The code examples below show the information required to authorize different transaction types.
//E-Commerce AuthOnly transaction:
PTechECommerce1.IndustryType = PtechecommerceIndustryTypes.pitECommerce;
PTechECommerce1.GoodsIndicator = PtechecommerceGoodsIndicators.pgiPhysicalGoods;
PTechECommerce1.Card = new CCCard();
PTechECommerce1.Card.EntryDataSource = EntryDataSources.edsManualEntryNoCardReader;
PTechECommerce1.Card.Number = "4444333322221111";
PTechECommerce1.Card.ExpMonth = 08;
PTechECommerce1.Card.ExpYear = 2017;
PTechECommerce1.CustomerAddress = "123 Nowhere Ln."; //Optional AVS data
PTechECommerce1.CustomerZip = "90210"; //Optional AVS data
PTechECommerce1.TransactionAmount = "1.00";
PTechECommerce1.InvoiceNumber = "1234";
PTechECommerce1.AuthOnly();
//Retail AuthOnly transaction:
PTechRetail1.IndustryType = PtechretailIndustryTypes.pitRetail;
PTechRetail1.Card = new CCCard();
PTechRetail1.Card.EntryDataSource = EntryDataSources.edsTrack1;
PTechRetail1.Card.MagneticStripe = "B4788250000028291^PAYMENTECH^05121015432112345678";
PTechRetail1.TransactionAmount = "1.00";
PTechRetail1.AuthOnly();
//Retail manually keyed AuthOnly transaction:
PTechRetail1.IndustryType = PtechretailIndustryTypes.pitRetail;
PTechRetail1.Card = new CCCard();
PTechRetail1.Card.EntryDataSource = EntryDataSources.edsManualEntryTrack1Capable;
PTechRetail1.Card.Number = "4444333322221111";
PTechRetail1.Card.ExpMonth = 08;
PTechRetail1.Card.ExpYear = 2017;
PTechRetail1.TransactionAmount = "1.00";
PTechRetail1.AuthOnly();
Capture / Force
The Capture method is typically used when a merchant has previously utilized the AuthOnly method. A capture transaction adds the transaction to the current open batch, and the transaction will be settled at the next call to the BatchRelease method of the PTechHostSettle. The Paymentech system treats Capture and Force transactions identically, so the Capture method can also be used when a merchant has obtained voice approval over the phone.
PTechECommerce1.Card.Number = "4444333322221111";
PTechECommerce1.Card.ExpMonth = 10;
PTechECommerce1.Card.ExpYear = 2017;
PTechECommerce1.TransactionAmount = "1.00";
//Value from voice auth or ResponseApprovalCode from previous AuthOnly transaction
PTechECommerce1.Capture("123456");
Credit
Use a credit transaction when money needs to be returned to a customer. The credit method 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 used with previously authorized transaction that has not yet been captured; funds are never captured and no charge appears to the customer.
The code examples below show how to process credit transactions with the PTechECommerce, PTechRetail, PTechDebit, and PTechCharge components:
PTechECommerce1.Card.Number = "4444333322221111";
PTechECommerce1.Card.ExpMonth = 10;
PTechECommerce1.Card.ExpYear = 2012;
PTechECommerce1.TransactionAmount = "1.00";
PTechECommerce1.Credit();
Sale
This transaction decrements the cardholder’s open-to-buy funds for the sale amount. The transaction is automatically added to the current open batch, and will be settled after the current batch is released with the PTechSettle component. If you have Host Auto Close configured for your account, calling Sale makes accepting credit cards a simple one-step process. Sample transactions follow:
//E-Commerce Sale transaction:
PTechECommerce1.IndustryType = PtechecommerceIndustryTypes.pitECommerce;
PTechECommerce1.GoodsIndicator = PtechecommerceGoodsIndicators.pgiPhysicalGoods;
PTechECommerce1.Card = new CCCard();
PTechECommerce1.Card.EntryDataSource = EntryDataSources.edsManualEntryNoCardReader;
PTechECommerce1.Card.Number = "4444333322221111";
PTechECommerce1.Card.ExpMonth = 08;
PTechECommerce1.Card.ExpYear = 2017;
PTechECommerce1.CustomerAddress = "123 Nowhere Ln."; //Optional AVS data
PTechECommerce1.CustomerZip = "90210"; //Optional AVS data
PTechECommerce1.TransactionAmount = "1.00";
PTechECommerce1.InvoiceNumber = "1234";
PTechECommerce1.Sale();
//Retail Sale transaction:
PTechRetail1.IndustryType = PtechretailIndustryTypes.pitRetail;
PTechRetail1.Card = new CCCard();
PTechRetail1.Card.EntryDataSource = EntryDataSources.edsTrack1;
PTechRetail1.Card.MagneticStripe = "B4788250000028291^PAYMENTECH^05121015432112345678";
PTechRetail1.TransactionAmount ="1.00";
PTechRetail1.Sale();
//Retail manually keyed Sale transaction::
PTechRetail1.IndustryType = PtechretailIndustryTypes.pitRetail;
PTechRetail1.Card = new CCCard();
PTechRetail1.Card.EntryDataSource = EntryDataSources.edsManualEntryTrack1Capable;
PTechRetail1.Card.Number = "4444333322221111";
PTechRetail1.Card.ExpMonth = 08;
PTechRetail1.Card.ExpYear = 2017;
PTechRetail1.TransactionAmount = "1.00";
PTechRetail1.Sale();
Void
Use the VoidTransaction method of the PTechECommerce, PTechRetail, and PTechCharge components to perform a void. A transaction can only be voided if it exists in the current open batch. If the batch that contained the target transaction has already been released (settled), you must use the Credit method instead.
The VoidTransaction method has two parameters, RetrievalNumberToVoid and LastRetrievalNumber. RetrievalNumberToVoid is the reference number of the transaction you wish to void. Set the LastRetrievalNumber property to the last response number received from the Paymentech server. If LastRetrievalNumber is left blank, this parameter will be set to the ResponseRetrievalNumber of the PTechECommerce component – this field is set by the server when it returns a response to a submitted transaction.
Before sending a void, ensure that the CardNumber property contains the card number from the original transaction. Also note that since auth-only transactions are not added to the current batch, they cannot be voided. The following example creates a sample sale transaction to be voided:
PTechECommerce1.Card.Number = "4444333322221111";
PTechECommerce1.Card.ExpMonth = 10;
PTechECommerce1.Card.ExpYear = 2012;
PTechECommerce1.TransactionAmount = "1.00";
PTechECommerce1.Sale();
cnumToVoid = PTechECommerce1.Card.Number;
refNumToVoid = PTechECommerce1.Response.RetrievalNumber;
...
PTechECommerce1.Card.Number = cnumToVoid;
PTechECommerce1.VoidTransaction(refNumToVoid, "" );
Additional Functionality
You can use the PTechCharge, PTechRetail, and PTechECommerce components of 4D Payments SDK to process 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 Gift and EBT/Benefit cards, as well as processing payments made with Level II corporate purchasing cards.
AVS
The AVS (address verification service) uses the address information of the customer in the authorization request to help prevent fraud. This additional identification information consists of a street address and zip code. After the authorization is sent, the AVSResult field of the Response 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, 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 that provides an extra level of identity verification during an authorization and which 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 TechCharge Sale method, then when the response from the processor returns the CVVResult field of the Response property 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
Track data is read by a card reader from the magnetic stripe on the card. If both track 1 and track 2 data is available, track 1 takes precedence over track 2. You can use the PTechCharge component to transmit transactions with track 1 or track 2 data directly to the processor by setting the MagneticStripe and EntryDataSource fields of the Card property. If the card reader is track 1 or track 2 capable but you must manually enter the card, you can set the EntryDataSource property to “dsManuallyEntered”.
If the IndustryType is itRetail and the EntryDataSource is not dsManuallyKeyed, then the MagenticStripe field must be set with the full magnetic stripe data from the customer’s credit card. This includes everything after but not including the start sentinel (& or ;) and up to but not including the end sentinel (?) and LRC check character. You may only set this property with track 1 or track 2 data, and may not pass both. Use the EntryDataSource field to indicate which track you are sending.
Note that merchants should never store track data.
ECI
ECI (Electronic Commerce Indicator) is a 1-character transaction indicator identifying the type of transaction being authorized. This is also known as mail order/telephone order (MOTO). This value is used only for card-not-present transactions. The ECI property should be set for direct marketing transactions and for 3D-Secure-authenticated transactions.
To identify a direct marketing transaction set the IndustryType property to “PITDirectMarketing” and set the value of the ECI property – this will most often be set to the value of “1” (a one-time occurrence of a mail order or telephone order transaction). For a list of all supported values, please consult the Paymentech PTechCharge documentation of the ECI property.
Level II
Level II (purchasing card) transactions are supported by setting the Level2PurchaseId, Level2SalesTax, and Level2ShipToZip properties of PTechCharge.
Debit Support
You can use the PTechDebit component to add support for debit cards. As of version 4 of 4D Payments SDK, the PTechCharge component supports debit transactions. Debit transactions are only supported by the Retail, Hotel, and Restaurant IndustryTypes, and only for card-present transactions. In order to process a debit transaction you will need a PIN pad that has been injected by Paymentech with a key. Once you have an authorized 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 DebitPIN and DebitKSN properties respectively. Note that if either the DebitPIN or DebitKSN properties are present, the component will process the transaction as a debit card charge.
Below is an example of a debit sale using DebitPIN, DebitKSN, and the track 2 data from a test card.
//Debit Sale Transaction
PTechDebit1.IndustryType = PtechdebitIndustryTypes.pitRetail;
PTechDebit1.CardMagneticStripe = "9999999800002773=05121015432112345678";
PTechDebit1.TransactionAmount = "25.00";
PTechDebit1.DebitPIN = "623F36B53CC18393";
PTechDebit1.DebitKSN = "000000008F000021";
PTechDebit1.DebitCashBack = "5.00";
PTechDebit1.SequenceNumber = 1;
PTechDebit1.Sale();
Get Support
You can find out more about 4D Payments SDK here. You will find the code samples above in the ready-to-compile demo applications included with 4D Payments SDK. Additional information about credit card processing is available in the 4D Payments Credit Card Processing FAQ. Before you can go live, you will need to create a merchant account that supports Paymentech with your bank. If you do not already have a merchant account, contact our support team, and they can help you with this.