Products
Support
Downloads
Purchase
Company
Subscriptions
Search: 
Tutorial - Getting Started with the Paymentech Integrator

By Spencer Brown - Technical Support, /n software.

Requirements:

  • Paymentech Integrator
  • Before you can go live, you'll need a merchant account with your bank that supports Paymentech.
Download Demo: Download

Chapter Listing

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

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

Paymentech Integrator

Processing credit card transactions with your application is extremely easy using the Paymentech Integrator. /n software Paymentech Integrator can be used to add credit card transaction processing to your application by communicating directly with the Paymentech processor. The Paymentech Integrator contains six components: CardValidator, PTBenefit, PTCharge, PTGiftCard, PTCanadianDebit, and PTSettle 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 PTCharge, PTBenefit, and PTGiftCard components are used to make authorizations and hold funds during a credit card transaction.

As an alternative to the manual settlement process, Paymentech offers an account feature called Host Auto Close. If your Paymentech account is setup with the Host Auto Close feature, you need take no further action. The host will close the current open batch at a designated time each day. This means that there is no end of day batch processing required from the merchant. 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. Without this flag being set, the merchant's transactions must be settled with a Manual Batch Release using the PTSettle component.

Pre-Authorization

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

There are two options to perform these checks. You can either use the PreAuthorize method of the PTCharge component. Or you may use the CardValidator component. The CardValidator component extends the list of card types supported by PTCharge's PreAuthorize method and also provides a set of properties to check the results. It is recommended that you use CardValidator for these reasons.

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

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

Below is an example of using the CardValidator component: 

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

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

Transactions (Charge, Settle, Credit, Etc.)

The PTCharge component allows you to perform any of the following transactions.

Auth Only

An Auth Only transaction is used to verify and reserve the cardholder's open-to-buy funds available at that time. This transaction is NOT added to the open batch. In order to settle (be paid) for this transaction, the merchant must run a Capture transaction using the original ResponseApprovalCode obtained during this Auth Only transaction. This will add the transaction to the batch.

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

C#
//Merchant setup
Ptcharge1.Server = "https://netconnectvar.paymentech.net/NetConnect/controller";
Ptcharge1.MerchantNumber = "700000000125";
Ptcharge1.TerminalNumber = "103";
Ptcharge1.ClientNumber = "0002";
Ptcharge1.UserId = "nsoftware01";
Ptcharge1.Password = "nsoftwarepw01";

//E-Commerce AuthOnly transaction: 
Ptcharge1.IndustryType = PtchargeIndustryTypes.itECommerce;
Ptcharge1.GoodsIndicator = PtchargeGoodsIndicators.giPhysicalGoods;
Ptcharge1.Card = new PTCardType();
Ptcharge1.Card.EntryDataSource = EEntryDataSources.dsManuallyEntered;
Ptcharge1.Card.Number = "4444333322221111";
Ptcharge1.Card.ExpMonth = 08;
Ptcharge1.Card.ExpYear = 2010;
Ptcharge1.CustomerAddress = "123 Nowhere Ln."; //Optional AVS data
Ptcharge1.CustomerZip = "90210"; //Optional AVS data
Ptcharge1.TransactionAmount = "1.00";
Ptcharge1.AuthOnly();

//Retail AuthOnly transaction: 
Ptcharge1.IndustryType = PtchargeIndustryTypes.itRetail;
Ptcharge1.Card = new PTCardType();
Ptcharge1.Card.EntryDataSource = EEntryDataSources.dsTrack1;
Ptcharge1.Card.MagneticStripe = "B4788250000028291^PAYMENTECH^05121015432112345678";
Ptcharge1.TransactionAmount = "1.00";
Ptcharge1.AuthOnly();
   
//Retail manually keyed AuthOnly transaction:: 
Ptcharge1.IndustryType = PtchargeIndustryTypes.itRetail;
Ptcharge1.Card = new PTCardType();
Ptcharge1.Card.EntryDataSource = EEntryDataSources.dsManuallyEntered;
Ptcharge1.Card.Number = "4444333322221111";
Ptcharge1.Card.ExpMonth = 08;
Ptcharge1.Card.ExpYear = 2010;
Ptcharge1.TransactionAmount = "1.00";
Ptcharge1.AuthOnly();
You can cut and paste this code into your own application and make a live test transaction with the Paymentech processor.

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 Paymentech.

The Response properties break down the response from the processor into its different parts and can be used for integration into other systems. If you plan to later Capture the Auth Only transaction you'll need to securely store the value of ResponseApprovalCode.


Capture / Force

Capture (Prior Sales) are 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 PTSettle component's BatchRelease method. The Paymentech system treats Capture and Force transactions identically, so this method may also be used when a merchant has obtained voice approval over the phone. 

C#
Ptcharge1.Card.Number = "4444333322221111";
Ptcharge1.Card.ExpMonth = "01";
Ptcharge1.Card.ExpYear = "06";
Ptcharge1.TransactionAmount = "1.00"; 

//Value from voice auth or ResponseApprovalCode from previous AuthOnly transaction
Ptcharge1.Capture("123456");

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.

You can perform a Credit with the PTCharge component by doing the following: 

	
C#
Ptcharge1.Card.Number = "4444333322221111";
Ptcharge1.Card.ExpMonth = "01";
Ptcharge1.Card.ExpYear = "06";
Ptcharge1.TransactionAmount = "1.00";
Ptcharge1.Credit();

Sale

This transaction decrements the cardholder's open-to-buy funds for the sale amount. This transaction is automatically added to the current open batch, and will be settled after the current batch is released with the PTSettle component. If you have Host Auto Close configured for you account, calling Sale makes accepting credit cards a simple one step process. Sample transactions follow. 

//Merchant setup
Ptcharge1.Server = "https://netconnectvar.paymentech.net/NetConnect/controller";
Ptcharge1.MerchantNumber = "700000000125";
Ptcharge1.TerminalNumber = "103";
Ptcharge1.ClientNumber = "0002";
Ptcharge1.UserId = "nsoftware01";
Ptcharge1.Password = "nsoftwarepw01";

//E-Commerce AuthOnly transaction: 
Ptcharge1.IndustryType = PtchargeIndustryTypes.itECommerce;
Ptcharge1.GoodsIndicator = PtchargeGoodsIndicators.giPhysicalGoods;
Ptcharge1.Card = new PTCardType();
Ptcharge1.Card.EntryDataSource = EEntryDataSources.dsManuallyEntered;
Ptcharge1.Card.Number = "4444333322221111";
Ptcharge1.Card.ExpMonth = 08;
Ptcharge1.Card.ExpYear = 2010;
Ptcharge1.CustomerAddress = "123 Nowhere Ln."; //Optional AVS data
Ptcharge1.CustomerZip = "90210"; //Optional AVS data
Ptcharge1.TransactionAmount = "1.00";
Ptcharge1.Sale();

//Retail AuthOnly transaction: 
Ptcharge1.IndustryType = PtchargeIndustryTypes.itRetail;
Ptcharge1.Card = new PTCardType();
Ptcharge1.Card.EntryDataSource = EEntryDataSources.dsTrack1;
Ptcharge1.Card.MagneticStripe = "B4788250000028291^PAYMENTECH^05121015432112345678";
Ptcharge1.TransactionAmount = "1.00";
Ptcharge1.Sale();
   
//Retail manually keyed AuthOnly transaction:: 
Ptcharge1.IndustryType = PtchargeIndustryTypes.itRetail;
Ptcharge1.Card = new PTCardType();
Ptcharge1.Card.EntryDataSource = EEntryDataSources.dsManuallyEntered;
Ptcharge1.Card.Number = "4444333322221111";
Ptcharge1.Card.ExpMonth = 08;
Ptcharge1.Card.ExpYear = 2010;
Ptcharge1.TransactionAmount = "1.00";
Ptcharge1.Sale();

Void

By using the VoidTransaction method of the PTCharge component you can 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 ResponseRetrievalNumber of the transaction you wish to void. LastRetrievalNumber should be set to the last ResponseRetrievalNumber received from the Paymentech Server. If LastRetrievalNumber is left blank, the contents of the ResponseRetrievalNumber property will be used instead.

Before sending a void, you must make sure that the CardNumber property contains the card number from the original transaction. Also note that since AuthOnly transactions are not added to the current batch, they cannot be voided. Examples follow. 

C#
Ptcharge1.Card.Number = "4444333322221111" ;
Ptcharge1.Card.ExpMonth = "01" ;
Ptcharge1.Card.ExpYear = "06" ;
Ptcharge1.TransactionAmount = "1.00" ;
Ptcharge1.Sale();

cnumToVoid = Ptcharge1.Card.Number;
refNumToVoid = Ptcharge1.Response.RetrievalNumber;

...  more sale transactions ...

//All that's needed for a void: 
Ptcharge1.Card.Number = cnumToVoid;
Ptcharge1.VoidTransaction(refNumToVoid, "" );

Debit Support

As of version 4 of the Paymentech Integrator Debit transactions are supported. In order to process a debit transaction you will need a PIN Pad that has been injected with a key by Paymentech. 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 DebitPIN and DebitKSN properties respectively.

Note: If either the DebitPIN or DebitKSN properties are present, the component will assume this is a debit card transaction. Debit transactions are only supported by the Retail IndustryType, and only for Card Present transactions.

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

C#
Ptcharge1.IndustryType = PtchargeIndustryTypes.itRetail; 
Ptcharge1.Card = new PTCardType();
Ptcharge1.Card.EntryDataSource = EEntryDataSources.dsTrack2;
Ptcharge1.Card.MagneticStripe = "9999999800002773=05121015432112345678";
Ptcharge1.TransactionAmount = "25.00";
Ptcharge1.PINCapability = PtchargePINCapabilities.ppVerifiedPIN;
Ptcharge1.DebitPIN = "623F36B53CC18393";
Ptcharge1.DebitKSN = "000000008F000021";
Ptcharge1.DebitCashBack = "5.00";
Ptcharge1.Sale();

Testing

Paymentech provides testing facilities in the form of a test merchant account. The demos included in our toolkit use a public test merchant account that you may use. You may also contact Paymentech to obtain your own test account.

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

    Paymentech 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 PTCharge, you need to set the IndustryType to itDirectMarketing and the ECI property (electronic commerce indicator). For direct marketing transactions, this will most often be set to the value of "1" (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 set the FullMagneticStripe and EntryDataSource properties of the PTCharge component. If you are Track 1 or Track 2 capable but you have to manually key-in a card, you should set the EntryDataSource property to dsManuallyEntered.

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

Level II (purchasing card) transactions are supported by setting the Level2PurchaseId, Level2SalesTax, and Level2ShipToZip properties of PTCharge

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 PTCharge Sale 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

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

ECI

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 Paymentech PTCharge 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 Paymentech Integrator by visiting its product page at http://www.nsoftware.com/ibiz/paymentech. In addition, there is a general /n software Credit Card Processing FAQ available on the nsoftware.com website. The trial download of the Paymentech 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.