Before you can go live, you'll need a merchant account with your bank, and an account with one of the supported gateways.
If you do not already have a merchant account, contact our support team, and they can help you with this.
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 Global Payments (Global Payments Integrator), TSYS Acquiring Solutions (TSYS Integrator), Paymentech NetConnect (Paymentech Integrator), or First Data Merchant Services (FDMS Integrator).
Working directly with the processor means that you have control over everything. Not only do you perform the authorizations, but you also have control of all other types
of transactions including settlements (captures), credits, voids, etc.
A payment processor is a service company that performs charges and settlements for credit card transactions. Every credit card transaction eventually goes through a payment processor
like TSYS (Fig. 1). Processing transactions
directly through the payment processor is generally less expensive than communicating through a payment gateway, and you maintain
complete control over all aspects of the transactions that you process.
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, 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.
Note: While the basic concepts discussed in this article apply to credit card processing in general, the implementation and methods used vary depending on whether or not
you're using an internet payment gateway or working directly with a processor.
If you're working with an internet payment
gateway, then you're in the right place.
If you're working with a payment processor such as TSYS Processing Services (VitalPS), please read
the TSYS Integrator guide.
The next step is to make sure that you have a merchant account. If you do not have a merchant account setup with a bank,
you'll need to do that before you can go live and complete
real transactions (if you're not sure how to go about setting up a merchant account, our support team can help you
get setup correctly). A merchant account is a special bank account where money from credit card transactions is
first routed to and held before transfer to your own business account. Money is then transferred into your standard
business account in real-time or during various times in a 24 hour period.
Making credit card transactions from your application is extremely easy using the E-Payment Integrator.
E-Payment Integrator can be used to add credit card and electronic check transaction processing to your application by communicating
with major Internet payment gateways.
The E-Payment Integrator contains two components: ICharge, ECheck, and CardValidator, but
this article will focus specifically on credit card transactions using the ICharge component. You can download the package from
the URL above and take a look at the working demo applications.
Supported Payment Gateways
The current list of supported payment gateways include:
If you do not see your preferred gateway listed above, do not worry. To find a complete list of supported
payment gateways, either contact our support team or download the fully functional trial product and check the documentation of
the Gateway property. If you still do not find your gateway, it is possible that support for your gateway can be added to the E-Payment Integrator. If you'd like to look into this, please
contact our support team.
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.
Most often, e-commerce companies that are making charges through a payment gateway perform all their authorizations
at the time of the submission of the credit card, and then the gateway automatically (with no extra effort on the part of
the merchant) performs one "settlement" at the end of the business day, during which each previous sale or capture
is settled. This is the default behavior of the component's Authorize method. Before trying an Authorize, you
should do what you can to verify that the credit card information that you have is valid.
The CardValidator component is used to help eliminate invalid submissions to the gateway by verifying
that a card number is correctly formatted and not expired. This is particularly important because gateways typically
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 perform any internet communication, but merely runs mathematical checks on the card information.
These checks include a Luhn digit check (in which
a mathematical algorithm is used to determine if the digits of the card number could be a valid card number), a card type
check (in which the card number digits are checked to make sure they are a valid card type, e.g. Visa, MasterCard, Amex, etc), and
finally an expiration date check. An example of using the CardValidator is below.
While CardValidator 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 the CardValidator component to avoid submitting errant authorization requests to the gateway.
Transaction Types (Charge, Settle, Credit, Etc.)
The ICharge component can perform all different types of transactions (Note: not all gateways support all types of transactions. To see what
transaction types your gateway supports, check the "ICharge Gateway Setup and Required Properties" section of the documentation.):
The Sale method is the most commonly used transaction type and
is used to process a sale. The Sale transaction authorizes the transaction, and then marks the transaction to be
automatically settled by the gateway at the end of the business day. If your customer is purchasing physical goods, and those
goods cannot be immediately shipped (for example, due to being on backorder), you should instead submit an
AuthOnly transaction and then follow that with a Capture after the goods have shipped.
In a Sale transaction, the following actions occur:
Transaction gets sent for authorization (via the Sale method).
Merchant gets notified of the approval status (via the Response properties of the ICharge component).
Gateway automatically captures the transaction at the end of the business day.
You can perform a sale with just a few lines of code, like so:
//set the gateway:
ICharge1.Gateway = nsoftware.IBizPay.IchargeGateways.gwAuthorizeNet;
ICharge1.GatewayURL = "https://test.authorize.net/gateway/transact.dll";
//set the customer address information
//(for address verification service implemented by the gateways)
ICharge1.Customer.Address = "1234 Nowhere Ln";
ICharge1.Customer.Zip = "90210";
//set the customer card information:
ICharge1.Card.CVV2Data = "123";
ICharge1.Card.ExpMonth = 2;
ICharge1.Card.ExpYear = 2012;
ICharge1.Card.Number = "4000200011112222";
//set my merchant information, the amount, and authorize the transaction:
ICharge1.MerchantLogin = "cnpdev1047";
ICharge1.MerchantPassword = "SsVxS6trU8whvBwz";
ICharge1.TransactionAmount = "1.00";
In fact, the above code is fully functional code. You can cut and paste this code into your own application and make a
live test transaction with the Authorize.NET gateway right now.
You'll notice that the code above sets the Customer.Address and Customer.Zip properties. This is not always required (it depends on the gateway
and your account with that gateway), but it is highly recommended that you provide at least this much information for Address Verification Service (AVS).
Another optional security measure is the card verification value 2.
An Auth Only transaction asks for authorization only. All transactions authorized in this way will not be captured until
a Capture transaction is performed on them. In order to perform an auth-only transaction, you'll need to set call AuthOnly.
Note: an AuthOnly transaction followed by a Capture is the same as a single Sale transaction.
A Capture should only be performed on a previous Auth-Only transaction. This will tell the gateway to go
ahead and capture this transaction with the others during the settlement process. The Capture method can be used,
and it requires as arguments a transaction ID (for the previous AuthOnly transaction) as well as the dollar amount.
When money needs to be returned to a customer, a credit transaction is used. This is sometimes confused with a void
transaction, but the two are very different. A void operates on a transaction that has been authorized, but not captured.
In this case no money has actually been transferred, but a hold is placed on the funds. The void cancels
the authorized transaction and it will not be captured. Unlike a void, a credit almost always operates on a transaction
that has already been captured. Note: a few gateways do not require a previous transaction and a credit can be used to transfer
funds even if a previous transaction has not occurred.
You'll need to check with your gateway (usually through its merchant web interface) to see whether or not a
particular transaction has been settled in order to know whether you need to perform a credit or a void.
The ICharge component's Credit method can be used to easily perform credit operations. All that is needed is the transactionId
of the previous transaction, which is always conveniently supplied after a Sale in the Response.TransactionId property.
If you do not have a previous transaction but you'd like to credit a card, contact your gateway to make sure they allow credits without a previous transaction.
If so, you can simply send an empty transactionId parameter and be sure to specify the correct credit card information (i.e. CardNumber, CardExpMonth, CardExpYear).
As explained earlier, a void operates on a transaction that has been authorized, but not captured.
This is before any funds have been actually transferred. The void cancels the originally authorized
transaction and it will not be captured.
The VoidTransaction method needs only a transaction ID to void. The ID is that of the previously
authorized (but not captured) transaction that will be voided.
Sometimes the gateway will respond to your authorization request with a response containing instructions to "call".
In these situations, you must call the credit card issuer to achieve authorization for the transaction. During the phone conversation with the card issuer,
if the transaction is authorized, you will be given an authorization number. You'll have to resubmit the initial authorization
as a force transaction with this authorization number included. The Force method takes one parameter for the voice authorization code that was obtained over the phone.
For more information, contact your gateway or our technical support team.
After you resubmit the authorization with the authorization number included, you will get approval.
An AVS Only transaction checks only AVS data such as CustomerAddress and CustomerZip, and returns the result in the Response.AVSResult property.
No funds are authorized in an AVS Only transaction. To send an AVSonly transaction just call AVSOnly.
Some gateways have separate test servers (e.g. LinkPoint, FirstData), which you can find documented in the Testing Information section of the documentation.
Other gateways (e.g. USAePay, Skipjack) have test accounts (some completely public, and some must be individually applied for) so that you can submit
using a particular test merchant number.
Special "test" fields
Still other gateways (e.g. Authorize.Net, Innovative) use the same server for live and test transactions, but they also require you to include a
special "test" field in your submission to mark the transaction as a test transaction. To enable TestMode for these gateways you can simply set the TestMode property of the component to true.
Please contact our support team to find out if a public test account is available for your gateway.
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 (read from the physical card when a card reader is used) 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. In addition, there are additional fees that are accrued from the payment gateway on top of the usual
payment processor fees. These gateway feeds are typically a combination of setup fees, transaction fees, a percentage of the sale, and sometimes a flat
E-Payment Integrator is perfectly suited for 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 the authorization is
sent to the payment processor, an indicator is supplied to let the processor know that the charge was received via telephone
order. You should check with your payment gateway to see if provisions are available for indicating Direct Marketing
transactions. In general, however, payment gateways do not distinguish between e-Commerce and Direct Marketing, and both will
be processed as e-commerce transactions. Because of this, you can usually get a better rate by using
TSYS Integrator or
Paymentech Integrator for Direct Marketing transactions.
Retail POS (Point of Sale)
Most businesses will accept credit cards via card swipe. In the past, many companies
have leased credit card machines and obtained a dedicated phone line that is always connected to the processor (or worse, some have 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. This data, when submitted to the credit
card processor, 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.
Very few gateways support the processing of track data, so it is recommended to use
TSYS Integrator or
Paymentech Integrator for POS transactions.
Support for currencies other than US dollars is dependant on the gateway you are processing with. By default, all
of the gateways supported by E-Payment integrator are processed in US dollars. A minority of the payment
gateways allow you to process in currencies other than US dollars, so check with your payment gateway to be sure. For
those that do, currency type can be set via the AddSpecialField method of the component (check with your gateway for the
field name and value).
International Card Types
Support for international card types like Delta, Solo, Switch, etc. is dependant on the payment gateway you are
working with. You will need to check with your payment gateway to see what card types are supported before accepting cards of
these types. When setting undefined card types for supported gateways in the ICharge component, you should set the CardType
to ccUnknown, and add a "CardType" special field where the value is the card type you are supporting. For Solo and Switch cards,
you may also need an "IssueNumber" special field as well using the issue number that is found on the card.
International Merchant Accounts
Most gateways supported by the E-Payment Integrator will only support US merchant accounts, but there are a few payment
gateways that support merchants in different
nations. Currently, the following gateways support merchant accounts outside of the U.S.:
Belgium, France, Netherlands, Austria, Germany, Luxemburg, Switzerland, UK
US, UK, Canada, Europe
The ICharge component includes an AddSpecialField method that can be used to pass extra information to your gateway.
This information may be specific to that gateway only, so is not normally sent with the component methods. An example of
this is the test field that can be sent with Authorize.Net authorizations to mark them as test transactions.
To determine if it is necessary to send a special field to your gateway with your authorization request, consult the ICharge Gateway Setup and Required Properties section of the documentation.
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
Participating cardholders can authenticate
directly with their bank via a secret question and answer prior to submitting credit card information. Participating
merchants will receive an approval code from the bank and submit this code with the other credit card information during processing
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 available.
Debit cards are supported, but only if used as a credit card.
Level II functionality is supported only if the gateway supports Level II. The gateways that support level II will have extra fields that
you can add to the outgoing authorization request using the AddSpecialField method. Some gateways that currently support
Level II are Authorize.Net and PayFlowPro.
Your gateway may have special fields that can be sent to set recurring payments. For more information on this, contact your gateway and the /n software support team.
Some gateways will allow you to setup recurring payments via their online merchant interface.
AVS (Address Verification Service) is where the address information of the customer is checked for accuracy. Sometimes this information only consists
of a main address line and a zip code, but some gateways require even more such as
state, city, country, name, etc.
After the authorization is sent, the Response.AVSResult property will contain the results of the address verification which
can be used by the merchant to decide whether or not to continue with the transaction and capture the funds.
CVV2 (Card Verification Value 2), is an alphanumeric field that contains the three digit Visa "Card Verification Value" (CVV),
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 and can be used to determine if the customer is actually in possession of the credit card. If the Card.CVV2Data
property is set prior to calling the Authorize method, then when the response from the gateway comes back the Response.CVVResult
property of the ICharge component will show the result of the CVV check. Note that authorization does not necessarily
depend on a successful CVV2 match.