Developer

Implement credit card processing with TrustCommerce

Implementing online credit card transaction processing is no simple matter, even with an off-the-shelf solution to help you out. This article walks you around the pitfalls of credit card processing with the TrustCommerce API for Windows and Linux.


Credit card payment processing is a vital part of online commerce transactions, and developers must be able to reliably implement off-the-shelf processing solutions. In a previous article, we discussed the basics of online credit card processing. Now, we'll focus on the particulars of credit card processing through a specific gateway, TrustCommerce.

TrustCommerce is a good place to start because:
  • It offers two well-documented interfaces for credit card processing.
  • It supports both Linux and Windows platforms.
  • It's fairly aggressive in supporting the open source community.

In the interest of full disclosure, you should know that I'm a TrustCommerce reseller, although TrustCommerce had no input in this article.

Getting started
The first thing you'll need is a TrustCommerce account, and setting up one is a simple procedure. Before you start, you should know or have available the following information:
  • How many transactions per month you're expecting
  • The dollar amount for a typical transaction
  • Your merchant bank information
  • A Vital tear sheet (supplied by your bank)

To establish a TrustCommerce account, go to the TrustCommerce sign-up page and complete the form. You'll receive an e-mail with a number of forms to fill out and fax back to TrustCommerce. TrustCommerce will then ask you for the information discussed above and review the Vital tear sheet. Once everything is in order, TrustCommerce will issue you an account number and password.

Features
The TrustCommerce (TCLink) API provides access to all the main transactions you'll need. In addition, it supports electronic checks and micropayments. Here's a list of recognized transactions:
  • Preauth
  • Sale
  • Postauth
  • Credits
  • Chargeback
  • Reoccurring billing
  • ACH (electronic checks)
  • TCS Wallet (micropayments)

Installation on Windows
To download the API, you must first log in to the TrustCommerce site using your account number and password. On the TrustCommerce downloads page, locate the Win32, 3.3.3 entry and download this file:
TCLink-3.3.3-COM.zip

Unzip the downloaded file and follow the instructions in the readme file to install the API. Next, copy ssleay32.dll, libeay32.dll, and TCLinkCOM.dll to the Windows System32 folder. Then, register the COM object by typing one of the three options listed below in the command line (selected based on the location of your System32 folder):
C:\> cd winnt\system32
C:\WINNT\SYSTEM32> regsvr32 TCLinkCOM.dll
C:\WINDOWS\ SYSTEM32> regsvr32 TCLinkCOM.dll

If everything works, you'll see a popup window that looks something like Figure A. You won't need to register the COM object again.

Figure A


If registering the COM object doesn't work, here are some things to check:
  • Make sure that you're running PHP 4.1 or higher.
  • Verify that you've got all the DLL files in the correct folders.

When the COM object is registered, you can run the test scripts that come with the package to make sure you can successfully process transactions.

Installation on Linux
If you're going to run the API on a Linux system, you'll need to locate the UNIX, 3.3.1 entry on the TrustCommerce downloads page and download this file:
tclink-3.3.1-php.tar.gz

Unzip the downloaded file and follow the instructions in the readme file to build the module and run the sample script tctest.php using these commands:
gunzip tclink-3.3.1-php.tar
tar –xf tclink-3.3.1-php.tar
cd tclink-3.3.1-php.tar
./build.sh
php tctest.php

To make the module available to a Web site, update your Php.ini file and move the file /module/tclink.so to your modules folder to make the module available globally, or move the file into the root of your Web so you can load it using dl(./pathto/tclink.so).

Note that it's possible to successfully build the TCLink module and still have problems. You may receive the following message when you run php tctest.php:
<b>Warning</b>: dl() [<a
href='http://www.php.net/function.dl'>function.dl</a>]: tclink: Unable
to initialize module Module compiled with module API=20001222,
debug=0, thread-safety=0
PHP compiled with module API=20020429, debug=0, thread-safety=0
These options need to match in <b>/home/www/tclink-3.3.1-php/tctest.php</b> on line <b>16</b><br /> FAILED!
Aborting this test script, please check to make sure the module is properly built.

If this message appears, you need to rebuild the TCLink module after syncing your PHP development library and PHP binary versions; then recompile and reinstall the TCLink PHP module. If PHP was installed via RPMs, there should be both a PHP RPM and a PHP-devel RPM installed. Type rpm –qa|grep php to see what's actually installed via RPM. The PHP and PHP-devel packages should both have the same versions; otherwise, you'll get the error shown above. If PHP was built from source, you'll have to check with the person who built it to find out what versions were used. If you're using shared hosting, this might be a problem for you.

Using TCLink on Windows
At this point, you've got the COM object registered and the libraries installed. So let's make sure we can do a transaction. The following code creates a new COM object, sends data to it, and then sends the data to TrustCommerce. The result of the request is available by calling GetResponse().

The code below shows a preauth request. We can set the action to any of the following: preauth, sale, postauth, credit, store, unstore, walletsale, or chargeback. Each of these actions has different required and optional parameters that must be sent for the transaction to be successful. Refer to the documentation for a complete list of all the required and optional parameters. (It's about 20 pages of data—too large to include in this article.)
<?php
$tclink = new COM("TCLinkCOM.TClink");
$tclink->PushNameValue("custid=1111111");
$tclink->PushNameValue("password=xxxxxxxx");
$tclink->PushNameValue("action=preauth");
$tclink->PushNameValue("amount=100");
$tclink->PushNameValue("cc=4111111111111111");
$tclink->PushNameValue("exp=0404");
$tclink->Submit();
echo '<html><body> Transaction status:';
echo $tclink->GetResponse("status");
echo '</body></html>';
?>

After running the code, you should see the results shown in Figure B.

Figure B


An important note: Although the code shown above works, the sample PHP code that is included with the COM package (contained in the file TCTest.php) is not valid PHP code. Here's a small sample of the code that doesn't work:
tclink.PushNameValue("custid=XXXX")
tclink.PushNameValue("password=PPPP")

Looks like VB to me, not PHP.

If you're using the COM object, you can use the following methods:
PushNameValue(),
Submit(),
GetResponse(),

Using TCLink on Linux
Assuming that you've got the tclink module loaded and available globally, you can run the following code to get (roughly) the same result as that shown above, with all the parameters printed out, instead of just the status:
<?php
$params['custid'] = '11111111';
$params['password'] = ' xxxxxxxx ';
$params['action'] = 'preauth';
$params['media'] = 'cc';
$params['cc'] = '4111111111111111';
$params['exp'] = '0104';
$params['amount'] = '100';
// Send the hash to TrustCommerce for processing
$result = tclink_send($params);
echo '<html><body> Transaction status:';
// Print out all parameters returned
while (list($key, $val) = each($result))
{
echo $key .'='. $val .'<br>';
}
echo '</body></html>';
?>

If you're using the PHP module, you can use the following methods:
Send(),
GetVersion(),

All the data you can access through the methods available to the COM object is stored in $result. It's up to you to pull it out and use it the way that works best for you.

The request
As mentioned above, the TrustCommerce API supports several types of requests. The code included in this article shows the minimum code for performing a preauth request. You can change the request type by changing the action from preauth to, for example, sale, or any other eligible transaction you want to conduct.

The response
After making a request, you can receive one of the five status responses shown in Table A. Obviously, the one you want is the approved or accepted transaction. You'll need to trap for each type of response. You can refer to the documentation for a full discussion of decline, baddata, and error.

Table A
Response Description
approved The transaction was successfully authorized.
accepted The transaction has been successfully accepted into the system.
decline The transaction was declined.
baddata Invalid parameters passed.
error System error when processing the transaction.

To find out which status you received, you'll need to employ code similar to this:
$response = $tclink->GetResponse("status");

In this case, $tclink is the name of the connection to the TCLink API, GetResponse is the main method you'll be using, and $response contains the value of the status, such as approved or decline. You have to specify which piece of data you want to get. In the case of an approved or accepted transaction, don't forget to retrieve the transaction ID:
$transid = $tclink->GetResponse("transid");

The documentation contains a complete list of all the information you'll need. A word of caution: The documentation can be misleading. It's not PHP-specific. The code samples in the documentation are pseudocode and aren't suitable to run as is.

Ready for action
As you can see, using the TrustCommerce interface isn't complicated. The most complex aspect of employing TrustCommerce is building the code around the credit card processing request and the code for dealing with the response conditions. Regardless of the processor you end up using, you're going to have to build the code for handling the request and the response. What I like best about the TrustCommerce API is that both the COM object and the PHP module take care of the connection to the TrustCommerce servers. You don't have to use Curl or HTTP POST.

Editor's Picks

Free Newsletters, In your Inbox