Getting Started with Global Payments (4D Payments SDK)

Requirements: 4D Payments SDK

Contents

  1. Getting Started
  2. The Life Cycle of a Credit Card Charge
  3. Business Models
  4. Test Setup
  5. Transaction Types (Sale, Void, Refund, etc.)
  6. Debit Transactions
  7. Batch Management
  8. Transaction Search
  9. Get Support

Getting Started

4D Payments SDK provides credit card processing capabilities for applications and websites running on any platform. Use 4D Payments SDK to enable direct-to-processor payment processing with any major payment processor. 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 if you want to use a payment gateway or work directly with a processor.

  • Direct to Processor
    All credit card transactions eventually end up in the hands of 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 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 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.

    Direct to Processor
    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.

    Internet Payment Gateways
    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 the authorization for a certain dollar amount on a customer’s credit card (i.e., 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 components are used to make authorizations and hold funds during a credit card transaction.

As an alternative to the manual settlement process, in which the merchant completes a “capture” transaction that settles the already-authorized transaction, Global Payments offers an account feature called Host Auto Settle. If your Global Payments account is set up with the Host Auto Settle feature, you need take no further action after an authorization. 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. If the merchant account is not configured with the Host Auto Settle feature the batch must be settled manually using the GlobalBatchMgr 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

If you do not have a merchant account setup with a bank, you will need one before you can complete live 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.

Global Payments provides testing facilities in the form of a test merchant account. The demos included in our toolkit use a public test merchant account. You may also contact Global Payments to obtain your own test account. When you go live, you will need to obtain the correct values for your own account from your bank and from Global Payments.

The code below shows the properties required to set up the component with the public test merchant account or with your own:

//Merchant setup GlobalCharge1.UserId = "4dpayments_retail"; GlobalCharge1.Password = "Passw0rd"; GlobalCharge1.Server = "https://certapia.globalpay.com";

Credit Card Transactions (Sale, Void, Refund, etc.)

The components allow you to perform any of the following transactions:

Pre-Authorization

The GlobalCardValidator component enables you to submit card information to Global Payments to verify that the card is not expired and that the card number is correctly formatted. This can reduce invalid or declined transactions 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 transaction is not authorized during pre-authorization, but it is checked to see if it is valid. The checks that are performed are:

  • Luhn Digit Check: Validates the digits are correct according to the Luhn algorithm. The DigitCheckPassed property is populated with the result.
  • Card Type Check: Determines the type of card (Visa, MasterCard, etc) based on the card number. The CardTypeDescription property is populated.
  • Expiration Date Check: Verifies the card is not expired. The DateCheckPassed property is populated.
  • Length Check: Determines if the length is correct for the card type. The LengthCheckPassed property is populated.

The example below performs these checks using the GlobalCardValidator component:

GlobalCardValidator1.CardNumber = "5287890001234563"; GlobalCardValidator1.CardExpMonth = 1; GlobalCardValidator1.CardExpYear = 2017; GlobalCardValidator1.ValidateCard(); if (GlobalCardValidator1.DateCheckPassed && GlobalCardValidator1.DigitCheckPassed && GlobalCardValidator1.LengthCheckPassed) { Console.WriteLine("Card may be valid."); Console.WriteLine("Card type is: " + GlobalCardValidator1.CardTypeDescription); }

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. To later capture the auth-only transaction you will need to securely store the unique transaction identifier returned in the response from the server. This value is stored in the Response.PNRef property of the component. (The Response properties break down the response from the processor into its different parts and can be used for integration into other systems.) In order to settle (receive payment) for this transaction, the merchant must run a capture transaction using the original PNRef obtained during this auth-only transaction. Only then will the transaction be added to the open batch. Typically any funds blocked with a sale or auth-only transaction are reserved for approximately seven to ten days. This may vary from issuer to issuer.

You can perform an auth-only with just a few lines of code:

//AuthOnly transaction with Track 1 data GlobalCharge1.Card = new CCCard("5499990123456781=15125025432198712345", EntryDataSources.edsTrack1); GlobalCharge1.TransactionAmount = "1.00"; //Manually keyed AuthOnly transaction GlobalCharge1.Card = new CCCard("4444333322221111", 1, 2017); GlobalCharge1.TransactionAmount = "1.00"; GlobalCharge1.AuthOnly();

AVS Only

If the amount of the transaction is unknown but you would like to use the address verification service (AVS) of the processor, you can use the component to send an AVS-only transaction. This transaction validates the card and checks that the address matches what is on file with the issuer. An AVS-only transaction will not place a hold on any funds and will not reduce the cardholder’s limit to buy. Also, an AVS-only transaction will not place a transaction in the batch and no money will be transferred from the cardholder’s account to the merchant’s account. An example is below:

//Retail AVS Only transaction GlobalCharge1.CustomerAddress = "4"; //A hard-coded test value that will result in success GlobalCharge1.CustomerZip = "30329"; GlobalCharge1.Card = new CCCard("4003000123456781", 10, 12); GlobalCharge1.Card.CVVData = "123"; GlobalCharge1.AVSOnly(); Console.WriteLine(GlobalCharge1.Response.AVSResultCode);

Note that the AVS-only transaction is not supported in the e-commerce market.

Balance Inquiry (Prepaid Cards)

This method allows the merchant to determine the amount of funds remaining on a prepaid credit card. The only fields required for this transaction are the Number, ExpMonth, and ExpYear; however, you may submit the CustomerAddress and CustomerZip for Address Validation, and the CVV2Data field to check the card verification value (CVV). For example:

//Balance Inquiry transaction GlobalCharge1.Card = new CCCard("5111111111111118", 12, 2017); GlobalCharge1.BalanceInquiry(); Console.WriteLine(GlobalCharge1.Response.Balance);

Capture

Capture (post-auth capture) transactions are typically used when a merchant has previously utilized the auth-only method. A capture transaction adds the transaction to the current open batch. Please note that the TransactionAmount property can be omitted unless you intend to submit the capture for an amount different from the amount originally authorized. The PNRef value, returned in the original authorization response, is required. For example:

//Capture based on a PNRef from a previous AuthOnly GlobalCharge1.Capture("1233513541");

Credit

This transaction adds funds to the cardholder’s account. This can be performed any time and in any batch, and unlike the Refund method, is not based on a previous transaction. For example:

//Credit not based on a previous transaction. GlobalCharge1.Card = new CCCard("4444333322221111", 1, 2017); GlobalCharge1.TransactionAmount = "1.00"; // credits $1.00 GlobalCharge1.Credit();

Force

Force transactions are typically used when a customer’s card was declined, but the merchant was able to call the issuer and receive a voice authorization code. The Force method will add the transaction into the current open batch. The TransactionAmount, Card, and all other data must match exactly the information given over the phone and the ApprovalCode parameter must be set with the authorization code you received. For example:

//Force transaction using a voice approval code. GlobalCharge1.TransactionAmount = "1.00"; GlobalCharge1.Force("123456"); // value from voice auth or previous AuthOnly trans

Refund

A refund returns funds to a card based on a previously authorized and settled transaction (either a sale, capture, or force). A transaction can only be refunded if it exists in a previous batch. If the transaction is in the current open batch, use Void instead. To process a refund, call Refund with the PNRef parameter set to the PNRef returned in the response from the transaction for which you wish to issue a refund. If you do not know the PNRef from the original transaction, use Credit instead. If you leave the TransactionAmount blank, the full amount of the original transaction will be refunded. However, you may issue a partial refund for any value up to the original sale amount. For example:

//Full Refund GlobalCharge1.Refund("123456"); // "123456" is the PNRef from the original transactiony

The example shows a partial refund for an original transaction of $25.00:

//Partial Refund GlobalCharge1.TransactionAmount = "15.00"; GlobalCharge1.Refund("123456"); // "123456" is the PNRef from the original transaction

Repeat Sale

The RepeatSale transaction can be used by merchants to enable simplified reuse of cards previously used by a customer and allows recurring transactions. By using the Global Transport Gateway’s RepeatSale transaction instead of a new sale transaction, sensitive cardholder data such as the card number and expiration date do not have to be stored locally by the merchant, which reduces the likelihood of that cardholder data being compromised. Because all sensitive cardholder data is stored by Global Payments, the merchant only needs to store PNRef numbers. Note that the recurring logic (how often the transactions are processed, the length of contract, etc.) must be managed by the merchant and is not a function of the RepeatSale transaction feature of the Global Transport Gateway.

In order to perform a RepeatSale transaction, an initial sale (or partial authorization) transaction must occur first. Once the original transaction is processed, the merchant should store the PNRef number that is returned in the transaction response. The merchant should always use the PNRef number of the most recent RepeatSale transaction response for future reuse or recurring payments. An example is shown below:

GlobalCharge1.Card.Number = "4003000123456781"; GlobalCharge1.Card.ExpMonth = 12; GlobalCharge1.Card.ExpYear = 15; GlobalCharge1.TransactionAmount = "8.00"; GlobalCharge1.InvoiceNumber = "1234567890"; GlobalCharge1.RepeatSale("564474"); string pnref = GlobalCharge1.Response.PNRef; GlobalCharge1.Reset(); GlobalCharge1.UserId = "4dpayments_ecom"; GlobalCharge1.Password = "Passw0rd"; GlobalCharge1.TransactionAmount = "8.00"; GlobalCharge1.InvoiceNumber = "1234567890"; GlobalCharge1.RepeatSale(pnref);

Reverse

A credit card reversal transaction removes an unsettled, previously submitted transaction. The PNRef parameter should be set to the PNRef from the transaction response of the transaction you wish to cancel.

A “reverse” transaction differs from a void transaction in one key way: A standard credit card sale puts a hold on the cardholder’s open-to-buy funds until the batch is settled. When a void transaction is submitted, no money changes hands but a hold on the funds remains for a certain amount of time (usually around seven days, depending on the issuing bank). A reverse transaction releases the hold on the funds, and makes the funds available again immediately. For example:

//Reverse a previous transaction that is not yet settled. GlobalCharge1.Reverse("123456"); // "123456" is the PNRef from the original transaction

Sale

A sale 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 settled. For example:

//Sale with track 1 data GlobalCharge1.Card = new CCCard("5499990123456781=15125025432198712345", EntryDataSources.edsTrack1); GlobalCharge1.TransactionAmount = "1.00"; GlobalCharge1.Sale(); //Sale with manually keyed data (E-Commerce, MOTO, or Manually Keyed retail) GlobalCharge1.Card = new CCCard("4444333322221111", 1, 2017); GlobalCharge1.TransactionAmount = "1.00"; GlobalCharge1.Sale();

Tip Adjustment

To add a tip to a transaction simply call TipAdjustment with the PNRef parameter set to the PNRef of the transaction you wish to adjust, and the GratuityAmount to the amount you wish to add. For example:

//Add a tip to a previous transaction GlobalCharge1.TipAdjustment("123456","5.00"); //"123456" is the PNRef from the original transaction

Void

A void removes transactions from an open batch prior to settlement, to correct same-day transaction mistakes. A transaction can only be voided if it exists in the current open batch. To do so, call VoidTransaction with the PNRef parameter set to the PNRef of the original transaction. This method can only be used for transactions that are still in the current open batch. If the batch that contained the target transaction has already been settled, you must use the Refund or Credit methods instead. For example:

GlobalCharge1.Card = new CCCard("4444333322221111", 1, 2017); GlobalCharge1.TransactionAmount = "1.00"; GlobalCharge1.Sale(); refNumToVoid = GlobalCharge1.Response.PNRef; //... more sale transactions ... // Void a previous transaction: GlobalCharge1.VoidTransaction(refNumToVoid);

Debit Transactions

The GlobalDebit component provides a subset of the functionality of the GlobalCharge component. This component provides a simple interface for processing debit cards (and only debit cards). It works much like the GlobalCharge component, except it authorizes debit card transactions in only the Retail and Restaurant industries. Additionally, it cannot be used for e-commerce accounts.

In order to process a debit transaction you will need a PIN pad that has been injected with a key by TSYS. You will need a PIN pad to obtain the DUKPT DES/3DES Encrypted Pin and the KSN (Key Sequence Number) values. These will be passed to the EncryptedPIN and KSN properties of the component.

The GlobalDebit component allows the following transaction types:

Sale

Debit card sale transactions are instant funds transfers. There is no block placed on the debit card; funds are immediately removed and sent to the merchant. Therefore, there is no ability to capture, void, or reverse debit transactions. The transaction is automatically added to the current open batch, and will be settled after the current batch is settled. You must use the Refund method to return funds to a customer’s card. For example:

//Debit Sale with CashBack GlobalDebit1.Card = new CCCard("4003000123456781=15125025432198712345", EntryDataSources.edsTrack2); GlobalDebit1.EncryptedPIN = "7F8A30DB967DAB4D"; GlobalDebit1.KSN = "3D01000042000007"; GlobalDebit1.CashBack = "5.00"; GlobalDebit1.TransactionAmount = "10.00"; //Total including CashBack GlobalDebit1.Sale();

Note that TransactionAmount must be set to the total sale value plus the cash back amount.

Refund

Debit card transactions are instant funds transfers from the cardholder to the merchant. There is no block placed on the debit card. Therefore, there is no ability to capture, void, or reverse debit transactions. You must use the Refund method to return funds to a customer’s card. When performing a Refund, the MagneticStripe, EncryptedPIN, and KSN properties are required in addition to the PNRef parameter, which identifies the transaction you are issuing a refund for. For example:

//Full Refund GlobalDebit1.Card = new CCCard("9999999800002773=05121015432112345678", EntryDataSources.edsTrack2);); GlobalDebit1.EncryptedPIN = "623F36B53CC18393"; GlobalDebit1.KSN = "000000008F000021"; GlobalDebit1.Refund("123456"); // "123456" is the PNRef from the original transaction //Partial Refund GlobalDebit1.Card = new CCCard("9999999800002773=05121015432112345678", EntryDataSources.edsTrack2);); GlobalDebit1.EncryptedPIN = "623F36B53CC18393"; GlobalDebit1.KSN = "000000008F000021"; GlobalDebit1.TransactionAmount = "15.00"; // Partial refund for an original transaction for $25.00 GlobalDebit1.Refund("123456"); // "123456" is the PNRef from the original transaction

EBT/Benefit Transactions

The GlobalBenefit component included in the toolkit provides support for processing EBT (cash benefit card or food stamp card) transactions. The operation is similar to GlobalDebit and will not be covered in detail in this guide. For detailed information refer to the help file included with the toolkit.

Batch Management

The GlobalBatchMgr component is used to manage your Global Transport account. It can be used to check the connection to the server, verify your merchant setup, retrieve a summary of transactions in the current batch, and capture (settle) the current batch.

In many cases, a merchant will configure Host Auto Settle for their account. In this case, when performing a transaction Global Payments will automatically settle the transactions at a pre-defined time of day. This is ideal for most merchants as it does not require manually closing the batch.

GlobalBatchMgr offers functionality to check the connection to the server, return information about the merchant setup, get a summary of the current batch, and manually capture the transactions (if Host Auto Settle is not enabled). This functionality is provided through the following methods:

Method Description
BatchInquiry Returns information about the totals of different transaction types (Credit, Debit, Benefit) in the current batch.
CaptureAll Required only if Host Auto Settle is not configured. This settles all outstanding transactions in the batch.
CheckConnection Checks the status of the connection to the Global Payments server.
CheckSetup Returns name value pairs representing various configuration values for the merchant account.
GetBatchSummary Retrieves summary information about the transactions in the current batch.

The GlobalTransactionSearch component offers a way to search for past transactions given a wide variety of search criteria. To perform a search, first set your UserId, Password, and VendorNumber. All three values are required. If you are submitting test transactions and are using a test account, set the Server property to the certification URL (“https://certapia.globalpay.com”). Next set the SearchCriteria to the transactions you’re looking for, and call Search.

At the minimum, you must specify a start and end date range in the BeginDate and EndDate fields. All other search criteria fields are optional. For example:

//Search for recent successful transactions. GlobalTransactionSearch1.SearchCriteria.BeginDate = "06/15/2011"; GlobalTransactionSearch1.SearchCriteria.EndDate = "06/30/2011"; GlobalTransactionSearch1.SearchCriteria.ResponseCode = "0"; //Only return successful transactions. GlobalTransactionSearch1.Search(); for(int i = 0; i < GlobalTransactionSearch1.SearchResults.Count; i++) { Console.WriteLine(GlobalTransactionSearch1.SearchResults[i].TotalAmount); }

Get Support

You can find out more about 4D Payments SDK by visiting its product page at https://4dpayments.com/sdk/. Additional information about credit card processing in general is available in the 4D PaymentsCredit Card Processing FAQ. You will find the code examples above in the ready-to-compile demos included with 4D Payments SDK. Before you can go live, you will need to create a merchant account that supports Global Payments 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 article please contact our support team at support@4dpayments.com.