credit card payment gateway integration for AIM (Advanced Integration Method) the basics

1.Introduction  2.Code and Explanation  3.Download Source Code  4.Comments


A basic code and explanation for payment gateway integration using advanced integration method (AIM). Below is a form. You just give some values in the below form and click submit so see the request we are sending and the response sent by the server. You have to provide a login key and api key to check for realtime and for sandbox. In the php script i have left the login key value and api key value empty so that you can fill in your clients or your sandbox values. Note that the login key and api key will be different for sandbox and realtime payment. One set of keys cannot be used interchangeably.
Personal Details
First Name
Last Name
eg. NY
Payment Details
Card Type
Cardholder Name
Card Number
Expiration [ mm / yyyy ]
CVV Number

Code and Explanation

You can also copy the html part of the code by viewing the source code of this page. Since the html code is very simple to copy i did not provide the html code here. In the zip file you can find all the needed files.
You have to fill in the customers login key and transaction key either sandbox or live. Both are different.
		$LOGINKEY = '';// x_login
		$TRANSKEY = '';//x_tran_key
And next store all the post values into respective variables by url encoding them. $amount is stored with a constant value. Actually you will supply it from your form. That is the total amount the user is going to pay to the merchant.
		$firstName =urlencode( $_POST['firstname']);
		$lastName =urlencode($_POST['lastname']);
		$creditCardType =urlencode( $_POST['cardtype']);
		$creditCardNumber = urlencode($_POST['cardnumber']);
		$expDateMonth =urlencode( $_POST['cardmonth']);		
		// Month must be padded with leading zero
		$padDateMonth = str_pad($expDateMonth, 2, '0', STR_PAD_LEFT);		
		$expDateYear =urlencode( $_POST['cardyear']);
		$cvv2Number = urlencode($_POST['cardcvv']);
		$address1 = urlencode($_POST['address']);
		$city = urlencode($_POST['city']);
		$state =urlencode( $_POST['state']);
		$zip = urlencode($_POST['zip']);
		//give the actual amount below
		$amount = "300";
		$date = $expDateMonth.$expDateYear;		
Now the following is for readability. You need to create key value pairs(Associative array) which then will be converted to a query string. This query string will be posted to the payment gateway site. The following is broken down in each lines for the understanding of the programmer. You can see in the next section that this array is converted to a query string. Here you can see the LOGINKEY and TRANSKEY are associated with the respective key. Even you can directly substitute the login key and transaction key here instead of storing it in a variable at the top. I just had done like that for the programmers convenience.

In the following you have "x_delim_char" => "|". You can set it to any char. The response from the server will have multiple values separated by the delim character. Here all the parameters will be separated by or operator. like name|number|amount|status . After getting the response you have to use the same char to split the response string into array so it will be easy for accessing individual key values.
	$post_values = array(
	 	"x_login"			=> "$LOGINKEY",
		"x_tran_key"		=> "$TRANSKEY",
	 	"x_version"			=> "3.1",
		"x_delim_data"		=> "TRUE",
		"x_delim_char"		=> "|",
		"x_relay_response"	=> "FALSE",
		//"x_market_type"		=> "2",
		"x_device_type"		=> "1",
	  	"x_type"			=> "AUTH_CAPTURE",
		"x_method"			=> "CC",
		"x_card_num"		=> $creditCardNumber,
		//"x_exp_date"		=> "0115",
		"x_exp_date"		=> $date,
	 	"x_amount"			=> $amount,
		//"x_description"		=> "Sample Transaction",
	 	"x_first_name"		=> $firstName,
		"x_last_name"		=> $lastName,
		"x_address"			=> $address1,
		"x_state"			=> $state,
		"x_response_format"	=> "1",
	 	"x_zip"				=> $zip
		// Additional fields can be added here as outlined in the AIM integration
		// guide at:

Now the above associative array which is the actual key value pairs which the payment gateway understands is converted into a query string. The query string which is to be posted to the payment gateway is stored in $post_string.

	$post_string = "";
	foreach( $post_values as $key => $value )$post_string .= "$key=" . urlencode( $value ) . "&";
	$post_string = rtrim($post_string,"& ");
Now we have to set the url to which the above query string should be posted. Here we have two urls one is for live payment and another is for text payment(sandbox). By default i have set it to test payment mode. Note that the login key and transaction key for payment is different for live url and for test url. You have to request your client to create two different key set for live and for sandbox.
	//for test mode use the followin url
	$post_url = "";
	//for live use this url
	//$post_url = ""; 
Now the query string is ready and the target url to which we should post the query string is ready. The next step is to make a connection to the payment gateway and should post the query string. The following code does that. CURL is the best way to do payment transactions. First we set the target url by calling curl init function and if success we get a resource handler. We will make use of that resource handler to do additional inclusion before sending the request. curl_setopt is used to set various parameters for the request. curl_exec function will make a request with the parameters we have set and the server response is stored in the variable $post_response. And then we close the connection. You have to check the status of the request.
	$request = curl_init($post_url); // initiate curl object
	curl_setopt($request, CURLOPT_HEADER, 0); // set to 0 to eliminate header info from response
	curl_setopt($request, CURLOPT_RETURNTRANSFER, 1); // Returns response data instead of TRUE(1)
	curl_setopt($request, CURLOPT_POSTFIELDS, $post_string); // use HTTP POST to send form data
	curl_setopt($request, CURLOPT_SSL_VERIFYPEER, FALSE); // uncomment this line if you get no gateway response.
	$post_response = curl_exec($request); // execute curl post and store results in $post_response
	// additional options may be required depending upon your server configuration
	// you can find documentation on curl options at
	curl_close ($request); // close curl object

In the above code we have sent a request and have received a response. Whether it is success or failure you will get a response string. In the following code we convert the response string into a numerically indexed array. As i said earlier we are using the separation character to split one complete string into an array so that it will be easy for us to access the needful information.

	// This line takes the response and breaks it into an array using the specified delimiting character
	$response_array = explode($post_values["x_delim_char"],$post_response);

In the following code we are checking whether the payment gateway returned success of failure. Either success or failure we get an array mentioning the reason if it is failure or the transaction details if it is success.
If the first element of the array is 1 then the payment is success. else the payment failed due to the reasons mentioned in the error string. The third element of the array will have the error string in the case of failure.

In the case of success (else part of the following code) then the payment gateway will return the transaction id. This value is important and you can save it in the database because in future if you want to track this payment details from you have to use this transaction id to fetch the details.
$response_array[0] == 1 then success else you have to see the documentation for many possible error codes.
		echo 'Payment Failure.';
		echo 'Error String: '.$response_array[3]; // This will contain the reason for the error.
		echo 'Press back button to go back to the previous page';
		$ptid = $response_array[6]; // The transaction key when success
		$ptidmd5 = $response_array[7]; // The md5 of the above transaction key
		echo "Payment Success";
And now since you got the response you can store them in your database with the user information and product information like in an order table. I use to store the user details in one table and the sold products details in another table both tables will be linked with user tables id in product tables userid column.

Download Source Code

The zip file contains the html form and the php payment script. These are the basic files you need. You can refer the advanced payment integration document for the other key value pairs for references. Click here to download payment gateway source code

That is all folks. Enjoy.

By -

Comments, Suggestions, Objections, ...