CommSecure: Credit Card Processing

CommSecure is a credit card transaction broker; they process credit card transactions and clear funds into your bank account based upon the data that you send to them by referring web clients.

The protocol for doing this is described by CommSecure in their document entitled web-protocols (and if CS want to give me permission, I will put a PDF copy of it here). The protocol is a three way handshake:

1. Client is presented a form on your web site, the parameters of this form include the amount to be changed and other fields, and this form is submitted to the CommSecure web site, and not yours.
2. CommSecure then have a program that does an HTTP(S) enquiry to your web site with some of the parameters you have just sent the client off with; it is your responsability to then tell this probe to Accept or Decline the transaction.
3. CommSecure then get the details of Credit Cards, perform the transaction, and then once again contact you to inform you of the outcome of this transaction. The user is then referred back to us.

The advantage of this model of Credit Card Processing are:

• You do not have to worry about credit card details and doing the transaction yourself; all this data is given to CommSecure. Heck, you can put up an image on your web site saying "no credit card details kept on site", kind of like a physical shop havig a sign saying "no cash left on premises"!
• All funds are normally processed immediately, except when credit card processing to the banks is not availale for CommSecure to process.
• It's *really* *easy*

Given the interactions, we can see three parts to a complete transaction:

1. A Request for a payment
2. A Validation of payment by CommSecure
3. A Confirmation of the end of the transaction (either success or failure)

We model these into objects, and save them to the database. The common thread between each of these is the RefNum attribute; a transaction ID. Each of these objects are saved to our database.

We also have one object that encompasses all of these invidual objects; the parent objkect can be through of as a transaction; it in turn has a Request, a Validation, and a Clearance notification if it is a complete transaction.

We note the following:

• For each transaction there can be only one request object
• The Request must happen in time before the Validation
• The Validation must happen in time before the Confirmation
• A request is said to be invalid if:
  • it is validated and has no request;
  • it is confirmed and there is no validation or request;
  • the time ordering of the request, validate and confirm is incorrect
  • the amount being confirmed does not match the amount requested
  • the amount being confirmed does not match the amount validated
  • the signature on the confirmation is invalid

The Code

This implementation is in Perl. It is implemented as Object Orientated Perl. It requires the following other perl modules be installed:

• DBI
• CGI
• Math::BigInt

It requires the following software be installed:

• Perl (I recommend 5.8)
• A web server using CGI (eg Apache)
• A database supported by DBI (eg MySQL)

There are four modules:

• CommSecure.pm
• CommSecure/Request.pm
• CommSecure/Validate.pm
• CommSecure/Cleared.pm

These libraries should either be installed on your machine in a directory like /usr/local/lib/site_perl/: make a subdirectory called "CommSecure" and put the last three in here, and the first one in the main directory. Alternatively, place them in any where and in your scripts use the use lib qw(dir); statement to add this local directory to the library search path (still witht he same directory structure.

Testing

To test your application, you are going to want to send you users somewhere and have them issue the validation and confirmations; and of course, you want to be able to handle valid and invalid data.

The script below uses LWP::Simple and CGI to simulate the CommSecure service. From your script you can direct clients to it, and it will show them that they have been sent there with as params, and then give them the option of validating the transactions (or change the values and then validate), and then they can issue the confirmation.

The implications of this test program should be pretty obvious: if you are using this service, you must be able to distinguish real transactions from intruders; this is why you should, and this code does, verify the signatures and use the CommSecure public key.

You can get the dummy CommSecure test program here; remember to rename it to ".cgi" from ".pl" after you have downlaoded it, have ".cgi" as an executable script, and have the LWP modules installed.

There are several situation that we must take into account:

• What if we never get a validate within a reasonable time frame (eg, 1 hour/day)
• What if we get multiple Validates for the same RefNum: just accept them all, as some may be from intruders, and some may be from CommSecure; we dont know which address(es) CommSecure do or may use for performing these transactions; whats more, CommSecure themseleves may be forced to do multiple validates (eg, credit card network was down (unavailable) to them initally, and then becomes availale again.
• We may get bogus confirmations, or multiple valid confirmations (double charged). The bogus ones are easy; they wont have a valid signature that is based on the CommSecure public key!
• We may get validations or confirmation for RefNums we havent asked for.
• The amounts being validated and confirmed may not match.

Reporting

Try using the CommSecure->summary_html method; it will give you back some HTML formatted data showing you the current state of the transactions you are processing. A simple script that puts in the HTML head and tail will give you an online instant admin interface tot he current state of the transactions being performed.

Cleared and Validate scripts

On top of this, you will want to be able to have a validate and cleared script for CommSecure to be able to communicate with you:

• validate.pl
• cleared.pl

Rename these to .cgi like above.

Database Tables

There are three tables required: Requests, Validates, and Payments. The exact requirements can be found in the CommSecure modules manual; see perldoc CommSecure.

Licence

This code is released under the LGPL. See gnu.org for more information. You can take this and use it in any program, but if you make modifications to it, you have to also make these modifications publicly available. If the modifications are good, I reserve the right to integrate them here: as can anyone else.

I appreciate a thank you note as well; if you use this, and find it reasonable, please send me an email.

Thanks

I'd like to thank the following people for helping me get this done:

• Anthony Towns
• Mark Sutter
• Anand Kumria
• Bernard Blackham (crypto verification on Cleared.pm)

Issues to look out for

There are several points that should be noted when using these modules, to help you track down what is happening and improve your security.

First off, when testing against the real commsecure, grab their IP address and apply an ACL against your cleared and validate scripts. This is just an extra surity against malicious attacks.

Next, watch out for any transactions that get verified by CommSecure, but for which you never hear a result. The transaction may have successfully cleared, but if you dont hear a result, you wont know if you can issue a receipt.