Authorize.Net Payment Gateway-..:: Programmer Kingdom ::..

We will explore every aspect of processing a transaction in detail and write code that will allow us to seamlessly integrate the Authorize.Net payment gateway into our application.

Integrate the Authorize.Net Payment Gateway with PHP

Introduction

Authorize.Net^® is unquestionably the most popular payment gateway in use today. In fact, it is synonymous with ecommerce and is often confused as a payment processor. Its vast popularity with shopping carts, it is integrated with every major and minor shopping cart available, make it a natural choice for merchants wishing to begin processing sales online.

But what if you are implementing a custom shopping cart solution? You will need to integrate Authorize.Net's payment gateway into your application yourself. Fortunately this task is less daunting then it sounds. Below we will explore every aspect of processing a transaction in detail and write code that will allow us to seamlessly integrate the Authorize.Net payment gateway into our application.

Goals

As with any project you undertake, a clear set of goals should be outlined. The goals we have set forth for our project is to write PHP code that:

Getting Started

Before we get to the technical nitty gritty of integrating the Authorize.Net payment gateway into an ecommerce application, we have to make sure we have everything we need. Some technical requirements will need to be met if we wish for the code we will write to function properly. We should acquire some useful tools and documentation that will help us understand the inner workings of the Authorize.Net API. We also need to make sure we, as developers, have the technical know-how to handle a task of this magnitude.

Technical Requirements

Before we write a line of code we will need to make sure our server meets the minimum technical specifications for our code to work. You can easily check if your server is properly configured by using PHP's phpinfo() function.

Authorize.Net

Since this article is about integrating the Authorize.Net payment gateway into an ecommerce application, it stands to reason that we would have some basic requirements concerning it. Authorize.Net provides developers a set of tools to assist with the integration of their software. Utilizing these tools will make our job easier and less prone to error.

Assumptions

The scope of this article, integrating the Authorize.Net payment gateway, provides us with a narrow topic on which to focus (which is a good thing). To keep this article focused on the topic at hand we will not delve into basic programming skills and techniques. Assumptions that are made in this article include:

Planning the Transaction

Before we start to tackle processing the credit card payment programmatically, we should have an understanding of how the customer data flows from the beginning of the process (they submit the form) to the end of the process (they are informed of the success of their transaction). This will not only give us a better understanding of how an online payment works, but will also allow us to plan for contingencies like a processing error or declined transaction. Below we will follow customer data from submission through completion.

Building our Class

Now that we have an understanding of how a transaction will flow we can build our class around it. We should read through the Advanced Integration Method Integration Guide PDF

before we begin so we understand what Authorize.Net will be expecting from us.

Naming the Class

Naturally any good class name will indicate what the objects that class will create represents. For our class we will use the nickname for Authorize.Net in the credit card processing industry: Authnet.

Class Properties

Immediately after declaring our class we will need to declare the properties we will need for storing our objects properties. All of our properties will be private as we do not want our scripts to be accessing any of these values without going through a method. The first two properties we will declare are our Authorize.Net login and transaction key:

The login is used to login into the merchant's control panel as well as identifying the merchant to Authorize.Net's API. The transaction key is a random sequence of characters that acts like a password for API transactions. It is a security measure that prevents the merchant from putting their true account password into their scripts in an effort to help keep them safe.

Speaking of safe, that is the very reason we will hardcode this information into our class as opposed to making them parameters of the constructor. By placing this information directly in our class we can keep it out of our webpage's code. If the server experiences an error and were to suddenly display our source code, this sensitive information would not be available to the general public. It also allows us to place this class outside of our web root so it cannot be displayed by a web browser.

The Authorize.Net login will be provided by Authorize.Net upon the accounts creation. You can get your transaction key by following these steps:

The next three properties will determine if our transaction was successful (approved), declined, or an error occurred. You'll notice that $approved and $declined are both set to false while $error is set to true. This is because it is better to assume there is an error and either try again or abort the process then to assume a sale was approved only to find out later it wasn't (and the merchant already shipped their order).

The main function of the Authorize.Net API is to pass data back and forth to complete a transaction. The next two properties store the data we will be passing to Authorize.Net and the data we will be receiving respectively. The $params parameter is an array that will hold the parameters that we be passing to the Authorize.Net API. The $results parameter is an array that will hold the parameters that we be receiving from the Authorize.Net API (after a little bit of processing that is).

Since we cannot send arrays to the Authorize.Net API nor can we receive them, we will need a place to store our parameters in a format that Authorize.Net is expecting as well as a place to receive their response. The $fields parameter will store our properly formatted parameters for us (this will be done in a method described later in this article) . The $response parameter will store the raw data of the return response from the Authorize.Net API.

Finally, this last parameter probably can be done without, but for the sake of easier testing I have decided to include it in our class. This member will simply store a boolean value to determine whether we are currently testing our integration or processing live sales. Authorize.Net offers a special URL that is to be used for testing an integration of their API. Setting this member to TRUE will cause our Authnet object to use that URL for all transactions until we set it to false. (We will see this in action in our _construct method).

Constructor

New in PHP 5 is the __construct() function for creating an instance of an class. This function creates the object and can assign properties to it by assigning values to properties of the class. Inside our constructor we will be assigning values to properties that we will not be changing during the course of using our object. Let's look at what our __construct() function will look like and then break it down:

We've made our constructor function public so our application can access it to create an object. We also have one default parameter. This parameter is optional as we have provided a default value for it if one is not supplied during the creation of a new object.

You can see the parameter for the constructor is assigned to the parameter $test. If we pass a value of TRUE as the parameter during the creation of our object we will tell that object to use the test URL for the Authorize.Net API. The if/else statement below it chooses the appropriate URL to use for our test transactions.

The next portion of our constructor makes use the $params array we declared earlier in our class. It assigns values to some parameters the Authorize.Net API will be expecting.

These five values collectively tell Authorize.Net how we intend to use their API. Since they have little value to our overall understanding of how to use their API we will avoid going into them in great detail. You can read more about what each of these parameters do in their implementation guide.

The next two parameters tell Authorize.Net what kind of transaction we are running. The 'x_method' parameter tells Authorize.Net that this will be a credit card transaction (you can process eCheck transactions if the gateway has been established with that functionality). The 'x_type' parameter tells Authorize.Net that we wish to authorize and capture this transaction.

Authorizing but not charging a credit card

When credit cards are processed it actually is a two stage process. The first stage acquires and authorization number from the card issuing bank. The funds for that transaction are frozen and associated with that authorization number. The second stage if the actual capture of that sale where the funds are deducted from the customer's balance. The vast majority of Internet transactions perform both stages at once. But this is not always the case. It is possible that a merchant may want to freeze the funds on a credit card but not actually charge the customer until they ship the order. This is called an 'authorization only' transaction. In these cases the merchant is provided with the authorization number and uses this authorization number at a future date to claim those funds.

These last two parameters are our login and transaction key for the API. Obviously without these our access to the API will be denied.

Methods

Now that we have established what the properties for our class will be we will need to create some methods that will allow us to interact with them as well as to do the work our class is designed for.

The transaction() method assigns values to some of the properties that we did not have values for when we first created our object. These properties contain the necessary information to process the customer's credit card. This includes the credit card number, expiration date, and amount of the transaction.

We also have three optional parameters that are not required to process our transaction but under certain circumstances will be good to have. Certain types of credit cards require additional parameters to be sent to the processing bank during a transaction. For example, business cards require an invoice number (also called a purchase order number) and the tax amount for the sale to be submitted with each transaction. If they are not, that sale will downgrade to a much higher processing rate for the merchant.

Tip: There is no way to check to see if a credit card is a business card without physically viewing the card (even then you cannot always tell). If keeping merchant accounts fees to a minimum is important to the merchant, always submit an invoice number and tax amount with every transaction. It will never hurt the transactions that do not require this information and will prevent the ones that do from downgrading to a higher rate.

The CVV2 number is a security measure designed to help reduce fraud in card not present transactions. Some credit card issuing banks will decline a transaction if the CVV2 number is incorrect. Authorize.Net can even be set to automatically decline any transaction that fails a CVV2 check. Even though this field is optional in our class, there is no reason not to send this information with every transaction.

This method is the meat and potatoes of our class. It sends the transaction information and receives the response from the Authorize.Net API. It takes one parameter, $retries which has a default value of 3. This is the number of attempts that we will make to contact Authorize.Net and process a transaction. Earlier we had mentioned that this was one possible solution to dealing with errors when communicating with the Authorize.Net API. Here we have decided that three attempts are enough. If it does not connect after three attempts, it probably isn't going to work in a reasonable amount of time and we should fall back to another solution (like inviting the customer to call in their order).

Our next line of code: $this->prepareParameters() calls a private method that as the name would suggest prepares our parameters to be sent to the Authorize.Net API. We'll cover this method shortly.

To connect to the Authorize.Net API we have chosen to the built in CURL library. It makes interacting with remote servers easy. This line $ch = curl_init($this->url) initializes a new session and return a CURL handle for use with the other CURL functions.

Before we contact the Authorize.Net API we need to keep track of how many attempts we make before we give up. We do this by with this line: $count = 0.

These four lines of code do the hard work for communicating with the Authorize.Net API. The first line tells CURL to include header information in its output. The second line tells CURL to store the response as a string instead of outputting it to the browser. The third line provides CURL with the string to send to the Authorize.Net API which for us is our parameter string created by $this->prepareParameters(). The fourth line sends the request to the API and receives and stores the response.

To know whether our transaction was successful or not, and more, we need to parse the results. Our private method parseResults() does this for us. We will cover this method below.

Now that we have our results we need to determine whether our transaction was successful, declined, or experienced an error. Using the getResultResponseFull() method (covered later) we can find the status of our transaction. If the transaction is "Approved" or "Declined" we set our status properies approriately. We will use the break statement to end our while loop since we do not need to connect to the API any longer. If the transaction is neither "Approved" nor "Declined" we can assume an error occurred. In this case we will increment our counter and try again.

Before we can send our transaction information to Authorize.Net we need to make sure that information is in a format they are expecting. prepareParameters() takes the values in this array and separates each key/value pair with a pipe. It then spearates each set of parameters with an ampersand (&). We store the results in $this->fields to be sent when we process the transaction.

When we receive the response from the Authorize.Net API we will need to convert it into a format that we find easy to use (just like we had to format our parameters to their specifications). Fortunately this is as easy as splitting a pipe-delimited string. In our constructor we told the Authorize.Net API that we will be using a pipe ("|") as our delimiting character ($this->params['x_delim_char'] = "|") so we know we need to split the values by looking for it. We store the results in the $this->results array for later accessing.

The Authorize.Net API can accept over 80 parameters when submitting a transaction. Only a few are required but many are handy to use for various reasons ranging from enhanced security to better record keeping. Our array $this->params stores these fields for us. We can add fields to this array using the setParameter() method. The first parameter of this function is the name of the parameter you wish to send. You can refer to the Advanced Integration Method Integration Guide PDF

to see what parameters are available for use. The second parameter to our method is the value you wish to set.

When a transaction is processed and Authorize.Net returns the results of that transaction, it sends 73 fields back containing various pieces of information about the transaction. These 73 fields are all contained in the $this->results array created by the parseResults() method. The first field contains a numerical indicator of the results of our transaction. Our method getResultResponse() returns that number directly to our script. If you choose to use this method you will receive one of the following numbers:

To make displaying this easier, and also making our script possibly easier to read, we can use getResultResponseFull() to output a human-readable result of our transaction. We simply put the human-readable results into an array and use the response code as our array key.

These three methods are just accessor methods that allow our scripts to access private properties of our class. In these three cases they allow a script do determine the status of a transaction. The names of the methods will make it very clear in your script what you are trying to accomplish (checking the status of the transaction) and will promote readability which makes maintaining your script much easier.

Just like we have created accessor methods for the results of the transaction, we can create accessor methods to access the other 72 fields returned by the Authorize.Net API. The four chosen for this article are important enough to be listed here are:

Before We Process the Transaction

Although at the beginning of this article we stated that we will assume that you know how to validate data submitted by the customer. This much is still true. However, you may not necessarily know how to validate credit card specific information as you have never encountered it before. Below we provide techniques for validating the essential elements of a credit card.

Credit Card Number

Credit card numbers are never longer then 16 digits. The INPUT form field used to collect this data should have a MAXLENGTH of 16 (maxlength='16') set to prevent users from entering more digits then is allowed for any credit card issuer.

So how do we wrap this all together into something coherent that can be practically applied to a website? We will take the credit card number and look at the first number of the credit card number. We will then validate it based on whether it is a 3, 4, 5, or 6. If it isn’t any of the four we’ll just tell the user to try again.

$cc_number = trim($_POST['cc_number']); $first_number = substr($cc_number, 0, 1);
switch ($first_number)

else { // error } break; case 5: if (preg_match('/^5\d{3}[ \-]?\d{4}[ \-]?\d{4}[ \-]?\d{4}$/', $cc_number))

{ // Discover Card number is correct. Process the credit card. } else { // error } break; default: // error }

Verifying that a credit card has the correct number of digits and starts with the correct number is a good start to verifying a credit card number. But it is still fairly easy to work around. Any 16-digit number starting with a 4, 5, or 6 will pass this check. To help eliminate erroneous credit card numbers from being submitted there is one more check that can be performed. All of the major credit card institutions use a checksum to validate their credit cards. Each digit of the credit card is multiplied by 1 or 2. The last digit of the multiplication is added for each number in the credit card. If the resulting number is divisible by 10 it is a valid credit card number.

How can you tell if a credit card is legitimate?

After reading how to validate a credit card number you may think if a credit card passes validation that it is a legitimate credit card. This is not the case. Obviously a credit card in an improper format is not legitimate. But a credit card number may be in proper format and still be illegitimate.

So, how do you verify a credit card number is legitimate? The only way is to verify the legitimacy of a credit card is to authorize a sale. This requires using the payment gateway to send a transaction to the processing bank. The best way to do this is to do an AUTH ONLY transaction. This is similar to a sale transaction but does not charge the customer. It only freezes the funds on the customer’s credit card for a short period of time (no more then 30 days) and they are completely unaware of it as it does not appear on their statement. This makes it ideal for verifying their credit card is legitimate.

So, to verify a credit card is legitimate without actually charging, do an AUTH ONLY transaction for $1.00 and see if it is approved. If it is, the credit card is legitimate.

Expiration Date

The expiration date is not very difficult to validate compared to the credit card number and CVV2 number (see below). You really only have two issues to be concerned about:

The expiration date is a four digit number
Authorize.Net expects you to submit a four digit number as the expiration date for the credit card. The format they are expecting is MMYY. If the month is a single digit number (e.g. 1-9 for January through September) you must prefix it with a zero. The year is the last two numbers of the year. So, if the credit card expires in the year 2010 then you would drop the '20' and keep the '10'. So, a credit card that expires in August 2010 would have an expiration date of '0810'.

An easy way to do this is to use two SELECT menus in your HTML. One for the month, one for the year the card is set to expire. That way you can have the form send you the date in the format you prefer and all you need to do is concatenate the two values:
<select name="expire_month"> <option value="01">January</option> <option value="02">February</option> <option value="03">March</option> <option value="04">April</option> <option value="05">May</option> <option value="06">June</option> <option value="07">July</option> <option value="08">August</option> <option value="09">September</option> <option value="10">October</option> <option value="11">November</option> <option value="12">December</option> </select>
<select name="expire_year"> <?php // Set the year to be the current year up to ten years from now for ($i = date("Y"); $i < date("Y") + 10; $i++) { echo "<option value=\"" . date("y") . "\">" . date("Y") . "</option>"; } ?> </select>
$expiration_date = $_POST['expire_month'] . $_POST['expire_year'];
The expiration date is not a date in the past
Naturally an expiration date should be a future date. Any date from the past should automatically flag the credit card as being invalid. The current month is considered a future date as a date is not considered expired until the full month is over. That means if a credit card has an expiration date of September 2010, its implied expiration date is September 30, 2010 at 23:59:59. We will compare the current year with the expiration date's year. If it is sooner then this year, the date is invalid. If the year is the same as this year we will check the month to see if it has passed as well. If it hasn't, we have a valid expiration date.
$current_month = date("m"); $current_year = date("y"); if ($_POST['expire_year'] < $current_year) { // Invalid date } else { // Check if the same year, // if so, make sure month is current or later if ($_POST['expire_year'] == $current_year) { if ($_POST['expire_month'] < $current_month) { // Invalid date } else { // Valid date } } }

CVV2

CVV2 is a credit card security measure aimed at reducing fraud for card not present transactions. It is a three or four digit number that is only present on the credit card. Theoretically, this is used to verify that the credit card being used in a purchase in the in the possession of the purchaser at the time of the transaction making the sale more secure.

This code can be found in varying places on a credit card and is called different names by each of the major credit card companies:

Visa
Visa places their three digit code, which they call “Card Validation Code” (CVC2) on the back of the credit card in the signature panel. Usually at the very top-right most corner.
MasterCard
MasterCard places their three digit code, which they call “Card Verification Value” (CVV2) on the back of the credit card in the signature panel. Usually at the very top-right most corner.
American Express
American Express places their four digit number, which they call “Card Identification Number” (CID) on the front of the credit card, usually toward the end of the credit card number.
Discover Card
Discover Card places their three digit number, called “Cardmember ID”, on the back of the credit card in the signature panel. Usually at the very top-right most corner.

When accepting credit cards through a website, collecting the CVV2 number is essential. In the ecommerce world it is an important indicator as to the potential for fraud for a transaction. But as we've seen above, a CVV2 value may be three or four digits depending on which credit card a customer is using. So how do we validate it? By checking to see which credit card the customer is using and then looking for the correct amount of digits. We’ll find out which credit card the customer is using by looking at the first number of the credit card. We’ll specifically look for American Express cards as they are the odd balls and have a four digits CVV2 number. Visa, MasterCard, and Discover Card each have a three digit CVV2 number.

We’ll take the first digit of the credit card number and then check to see if it is a three. If it is a three, check to see if the CVV2 code is four digits long. Otherwise, check to see if the CVV2 code is three digits long. Here's some simple PHP code that does this:

// The credit card number $cc_number = $_POST['cc_number'];
// The CVV2 number $cvv2 = $_POST['cc_cvv'];
// Extract the first number of the credit card $first_number = substr($cc_number, 0, 1);
// If the first number is a '3 it's an American Express Card

// And we need to verify the CVV2 number is four digits long

// otherwise check to see if it is three digits long

if ($first_number == 3)

{ if (!preg_match("/^\d{4}$/", $cvv2))

{

// It's an American Express card but its

// CVV2 code is not four digits long. } }

else { if (!preg_match("/^\d{3}$/", $cvv2))

{

// It's not three digits long.

}

Using our Class

Now that we have a clear understanding of how the Authorize.Net API works, how we can use it, and how a transaction occurs, we can tie it all together into a cohesive unit.

Processing the Transaction

Thanks to our class handling almost all of the work integrating it into a script is very simple to do. Let's look at a basic framework that uses our class and then break it down:

$payment = new Authnet(true); $payment->transaction($creditcard, $expiration, $total); $payment->process(); if ($payment -> isApproved()) { // Display a printable receipt } else if ($payment -> isDeclined()) { $reason = $payment -> getResponseText(); // As for another form of payment } else { // Ask the merchant to call us }

The first line of code $payment = new Authnet(true) creates an instance our Authnet object and initializes all of the properties in the constructor. $payment->transaction($creditcard, $expiration, $total) assigns the credit card number, expiration date, and amount of the transaction we wish to process. $payment->process() sends the transaction to Authorize.Net for processing and returns the results to our object. All we need to do from here is find out if the transaction was approved, declined, or resulted in an error. A simple if/else statement handles this nicely.

You'll notice that if our transaction is declined we use the getResponseText() method to find out why. This will be handy to let our customer know why their card was declined.

And that's it! Believe it or not that's all it takes to process a credit card transaction through Authorize.Net's API. But there are a couple of shortcomings to our code:

We do not do AVS
We do not verify the CVV2 number

Fortunately, ensuring that both of these are done is very easy to do with our class:

$payment = new Authnet(true); $payment->transaction($creditcard, $expiration, $total, $cvv); $payment->setParameter("x_address", $business_address); $payment->setParameter("x_zip", $business_zipcode); $payment->process();

To make sure that we verify the CVV2 number we simply as it as the fourth parameter to our transaction() method. Performing AVS is slightly more involved but still very simple to do. We use the setParameter() method to add the street address and zip code to our list of parameters we will send to Authorize.Net. Now we have helped to reduce our risk of fraud and we only added two lines to our code!

Inducing a Declined Transaction

The test account offered by Authorize.Net will automatically approve all transactions by default. While this is important for testing your application's response to approved transaction, it doesn't help us test our application's handling of declined transactions or errors. Fortunately forcing Authorize.Net to decline a transaction is easy to. Authorize.Net allows a merchant to have transactions be declined even if they were originally approved by the processing bank if AVS does not meet the merchant's criteria for an acceptable response. We can take advantage of this to force our transactions to decline by creating a situation where AVS will fail to meet our own criteria.

To change our test account's AVS settings follow these steps:

Log into your test account
Click on "Settings" (under "Account")
Click on "Address Verification Service" (under "Basic Fraud Settings")
Check the checkbox that says, "Reject if... Address information is not provided for AVS check (B)"
Press the "Submit" button

Now to have a transaction declined we need only to submit a transaction without the street address and zip code (as we did in our first example of using our class). Without these two pieces of information our test account will automatically decline the transaction.

Inducing an Error

Just as we need to create the circumstances for our test transactions to be declined, we will need to do that same to produce an error. Fortunately this is just as easy to accomplish and we can do it by munging our own code. Simply changing the URL we use for contacting the Authorize.Net API we can cause our transaction to fail. In the example below we simply change the test URL to be oops.Authorize.Net:

if ($this->test == true)

{ $this->url = "https://oops.authorize.net/gateway/transact.dll"; }

Conclusion

We have covered a lot of ground in this article. We started by analyzing the transaction process from start to finish and identifying all possible branches to the transaction flow. From there we built upon the knowledge we gained from reading the Authorize.Net Advanced Integration Method Integration Guide PDF to construct a class to encapsulate our interaction with the Authorize.Net API. After validating unique transaction data we used our new class to easily process a transaction utilizing the Authorize.Net gateway.