Getting Started with E-Payment Integrator

Requirements: 4D E-Payment Integrator


  1. Getting Started
  2. The Life Cycle of a Credit Card Charge
  3. Business Models
  4. Test Setup
  5. Transactions Types (Charge, Settle, Credit, Etc.)
  6. International Support
  7. Additional Functionality
  8. Get Support

Getting Started

You can use E-Payment Integrator to create applications and websites that feature online payment processing through any of the major payment gateways. The guide below details each step of credit card processing and shows how to use the components of E-Payment Integrator 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 processed through a credit card processing network such as Global Payments, TSYS Acquiring Solutions, Paymentech NetConnect, or First Data Merchant Services. Processing transactions directly through the payment processor is generally less expensive than communicating through a payment gateway, and you maintain tighter control over all aspects of the transactions. 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 gateway handles all of the communication with the processor and offers a variety of additional services such as transaction logging, reporting, security and fraud prevention, credit and void capabilities, and the 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. Authorization includes checks that obtain authorization for a certain dollar amount and ensure 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 involves transferring the previously authorized funds from the cardholder’s bank account to the merchant’s bank account.

Most often, e-commerce companies that are processing charges through a payment gateway perform all authorizations at the time of the submission of the credit card, and then the gateway automatically performs one “settlement” at the end of the business day, during which each previous sale or capture is settled. To provide compatibility with the major payment processors, batch authorization is enabled by default for the component.

Business Models

The components of E-Payment Integrator and Direct Payment Integrator 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.

Every credit card transaction has fees based on the level of risk associated with funding a transaction, in addition to the base percentage charged from the card issuer. These extra fees are called interchange fees, and they exist partially to encourage merchants to take security measures to reduce fraudulent charges. The 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. In addition, there are additional fees that are accrued from the payment gateway on top of the usual payment processor fees. These gateway fees are typically a combination of setup fees, transaction fees, a percentage of the sale, and sometimes a flat monthly fee.


You can use both E-Payment Integrator and Direct Payment Integrator 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. This is because the chances of fraud in e-commerce transactions are much higher than in transactions when the card is present. The card number and expiration date supply the minimum authentication for the transaction, but typically the address information and the card verification value can also be supplied to further verify the cardholder. Additionally, 3-D Secure technology can be used to reduce the risk of fraud. Integrate 3-D Secure Online Payment Processing provides an overview of 3-D Secure and how to deploy it using the MPI component of E-Payment Integrator – 3-D Secure.

Direct Marketing (Moto/Phone)

Additional authorization information identifies direct marketing transactions from other card-not-present transactions. When the authorization is sent to the payment processor, an indicator can be supplied to let the processor know that the charge was received via telephone order. You will need to check with your payment gateway 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, merchants may get a better rate by using Direct Payment Integrator for direct marketing transactions.

Retail POS (Point of Sale)

Businesses can simply install a card reader and software on a PC and process transactions over a secure Internet connection. The Retail component of E-Payment Integrator enables you to process card-present transactions through a gateway. To use it, set the MagneticStripe property to the track data, read from the magnetic stripe. Very few gateways support the processing of track data, so it is recommended to use Direct Payment Integrator for POS transactions.

Test Setup

Before you can start processing transactions through a gateway, you will need to set the information required by E-Payment Integrator to validate cards and to authenticate the merchant and cardholders to the gateway.

  1. You may need to register for a test account with a gateway if you do not yet have one. Some gateways (e.g., USAePay and Skipjack) provide public test accounts. You can find more detailed information about all supported gateways here.
  2. Set the GatewayURL or the Gateway property to the test server location. You can find the URL of the test server used by the gateway in the Testing Information section of the Help documentation. While some gateways (e.g., LinkPoint and First Data) have separate test servers, some gateways (e.g., Authorize.Net and Innovative) use the same server for live and test transactions and require you to include a special field that marks test transactions.
  3. Set the TestMode property of the component to true. ICharge1.MerchantLogin = txtGatewayLogin.Text; ICharge1.MerchantPassword = txtGatewayPassword.Text; ICharge1.GatewayURL = ""; ICharge1.TestMode = true;

    Alternatively, you can use the AddSpecialField method of the component to send extra information that is specific to the 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:

    ICharge1.AddSpecialField("x_test_request", "true"); ICharge1.Sale();

Transaction Types (Charge, Settle, Credit, Etc.)

E-Payment Integrator provides uniform interface for processing credit cards. You can use the ICharge and Retail components of E-Payment Integrator to authorize and settle the transaction types below through a payment gateway – in the examples below, the Authorize.Net gateway.


You can use the CardValidator component, available in all /n software products that support payment processing, to help eliminate invalid submissions to the gateway by pre-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 connect to the Internet, but merely runs mathematical checks on 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.CardNumber = "4444333322221111"; CardValidator1.CardExpMonth = 12; CardValidator1.CardExpYear = 2099; CardValidator1.ValidateCard(); //Check the results below if(CardValidator1.DigitCheckPassed && CardValidator1.DateCheckPassed){ ... }


The most commonly used transaction type is a sale. They are automatically settled by the gateway at the end of the business day. 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:

ICharge1.Customer.Address = "1234 Nowhere Ln"; ICharge1.Customer.Zip = "90210"; ICharge1.Card.CVV2Data = "123"; ICharge1.Card.ExpMonth = 2; ICharge1.Card.ExpYear = 2012; ICharge1.Card.Number = "4000200011112222"; ICharge1.TransactionAmount = "1.00"; ICharge1.Sale();

The code above sets the Customer.Address and Customer.Zip properties to provide authentication for an address verification service (AVS) implemented by the gateway. This is not always required (it depends on the gateway and your account with that gateway). Another optional security measure is the card verification value.

If your customer is purchasing physical goods and those goods cannot be immediately shipped (for example, due to being on back order), you should instead submit an auth-only transaction and then follow that with a capture after the goods have shipped.

Auth Only

An auth-only transaction performs the first of the two transactions that are necessary to process a transaction: authorization and capture. All transactions authorized in this way will not be captured until a capture transaction is performed on them. An auth-only transaction followed by a capture is the same as a single sale transaction. In order to perform an auth-only transaction, call the AuthOnly method.


A capture should only be performed on a previous auth-only transaction. When this second transaction is sent, the gateway will then capture it with the others during the settlement process. You can accomplish this by calling the Capture method and passing as arguments the dollar amount and the transaction Id of the previous auth-only transaction.


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, which will not subsequently be captured. Unlike a void, a credit almost always operates on a transaction that has already been captured.

You will need to check with your gateway (usually through its merchant Web interface) whether or not a particular transaction has been settled in order to know whether you need to perform a credit or a void.

The Credit method of the ICharge component can be used to easily perform credit operations. All that is needed is the transaction Id of the authorization transaction. The ResponseTransactionId property contains the reference number for the last transaction. The code example below will revoke the previous transaction:

ICharge1.Credit(ICharge1.Response.TransactionId, "1.00");

Note that several gateways do not require a previous transaction. In this case, only one credit transaction is required to transfer funds. If you do not have a previous transaction but you would 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 (e.g., CardNumber, CardExpMonth, CardExpYear).


As explained above, 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. The VoidTransaction method requires only a transaction Id. The code example below voids the last transaction that was sent to the server:



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 will need to re-submit the initial authorization as a force transaction with this authorization number included. Call the Force method to approve these transactions. The Force method takes one parameter for the voice authorization code, obtained over the phone:


AVS Only

An AVS-only transaction checks only AVS data such as CustomerAddress and CustomerZip, and returns the result in the ResponseAVSResult property. No funds are authorized in an AVS-only transaction.


International Support

By default, the components of E-Payment Integrator support U.S. currencies, card types, and accounts; however, you can use the same components to process transactions through any supported payment gateway, enabling you to use the same interface to support international merchants and customers.

International Currencies

Some gateways support currencies other than U.S. dollars. The currency type can be set via the AddSpecialField method of the component. You will need to check with your gateway for the field name and value.

International Card Types

Some payment gateways support international card types like Delta, Solo, Switch, etc. To accept payment from one of these cards, set the CardType property to “ccUnknown”, and add a “CardType” special field with a value of the card type you are supporting. For Solo and Switch cards, you may need to set an additional IssueNumber special field; set the value of this field to the issue number that is found on the card.

International Merchant Accounts

Currently, the following gateways support merchant accounts outside of the U.S.:

  • PSIGate: U.S., Canada
  • Moneris: Canada
  • Ogone: Belgium, France, Netherlands, Austria, Germany, Luxemburg, Switzerland, U.K.
  • Protx: U.K.
  • Optimal: U.S., U.K., Canada, Europe

Additional Functionality

You can use the ICharge and Retail components to provide additional authentication and verification for each type of transaction. Other components enable capabilities such as processing electronic checks, setting up recurring payments, and charging Level II and III corporate purchasing cards.

3-D Secure

3-D Secure technology provides incentives for e-commerce transactions by allowing merchants to reduce the costs associated with online fraud – often reflected by higher fees – and to offer more secure shopping for customers. E-commerce merchants can easily implement 3-D Secure using the /n software 3-D Secure Merchant Plug-in Interface (MPI). The tutorial available in Integrate 3-D Secure Online Payment Processing provides an overview of how to deploy 3-D Secure using the MPI component of E-Payment Integrator – 3-D Secure.


This information may consist of a main address line and a ZIP code, but some gateways require the state, city, country, name, etc. After the authorization is sent, the ResponseAVSResult property of the component 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.


The CVV2 value is an optional field that provides an extra level of identity verification and can be used to determine if the customer is actually in possession of the credit card. This field contains the three-digit Visa card verification value (CVV), MasterCard card verification code (CVC), or four-digit American Express card identification number (CID), which appears on the card signature line on the back of the credit card (or on the front of an AMEX card).

If the Card.CVV2Data property of the component is set to this value prior to authorization, then after the response from the gateway returns the ResponseCVVResult property of the component will show the result of the CVV check. Note that authorization does not necessarily depend on a successful CVV2 match.

Electronic Checks

You can use E-Payment Integrator components to integrate electronic check processing capabilities into your payment processing system:

  • The ECheck component enables you to process electronic check (ACH) transactions through Internet payment gateways without needing to redirect customers to a third-party site.
  • You can use the ACHConverter component to easily parse electronic checks (ACH records) into XML for simple viewing and editing, and then back into the ACH format for processing through the ACH network.
  • The Check21 component provides utilities for creating scanned images of paper checks using the X9.37 standard and sending scanned paper checks to an FTPS server.


Debit cards are supported in the Retail component. They are only supported in the ICharge component if used as a credit card.

Level II

If your gateway supports Level II, you can use the Level2 component to create aggregates of corporate purchasing card data, which can then be passed to the ICharge and Retail components.

Level III

If your gateway supports Level III, you can use the Level3 component to create aggregates of corporate purchasing card data, which can then be passed to the ICharge and Retail components.

Recurring Payments

Your gateway may have special fields that can be sent to set up recurring payments. Some gateways will allow you to make recurring payments via their online merchant interface. You can use the RecurringBillings component to simplify this process.

Get Support

You can find more details about E-Payment Integrator here. Additional information is available in the 4D Payments Knowledge Base. Supported gateways are listed in the Help documentation for E-Payment Integrator. Please contact the support team about adding support for a new gateway. You will find the code examples above in the ready-to-compile demos included with E-Payment Integrator. Before you can go live, you will need to create a merchant account with your bank. If you do not already have a merchant account, contact our support team, and they can help you with this.

We appreciate your feedback. If you have any questions, comments, or suggestions about this entry please contact our support team at