DataCash Perl API Overview

Document
Version
Last Updated
1.01 28 August 2001
Changelog

1. Material Provided By This Distribution

1.1 Software

This distribution does not provide a standalone application for carrying out credit card authorisation and settlement. It provides a toolkit for writing such programs. If you are not a Perl programmer, then you need to find one who can help you to use this software.

1.2 Documentation

In addition to this overview document, there is perldoc contained within the Perl modules themselves, which give specific detail on the methods and constructors.

2. Material Required By This Distribution

2.1 Perl 5

This API is intended for use with Perl 5. It has been created and tested on version 5.005_03.

3. Using the DataCash Perl API

3.1 Installation

3.1.1 Unix / Linux

The Perl modules need to be compiled on the machine that will be running the Perl scripts, which almost certainly means your web server. Because some modules depend on the presence of others, you need to compile and install some modules before others.

It should be noted however that your installation of Perl may already come with some of these modules installed. Here is a suggested order for installing the modules:

No Module Available From
1 Crypt::SSLeay CPAN
2 LWP CPAN
3 XML::Hash DataCash
4 DataCash::XMLPerlAPI DataCash

The procedure for installing a module is as follows:

  1. Download the gzipped tar file
  2. Unpack the file somewhere (doesn't matter where; the files will automatically be copied into the right place when you install them) using tar xzf filename, or (if your version of tar doesn't support the z flag) gunzip filename then tar xf filename
  3. cd into the directory that has been created
  4. Type perl Makefile.PL. A small script will run that sets up the module for installation
  5. Type make. The module will be compiled and set up for installation.
  6. Type make install to install it with your other Perl modules.

You will want to repeat this process for each module on the list above.

The module Crypt::SSLeay requires you to have OpenSSL installed on to your system, however full details of this are available with the tarball itself.

3.1.2 Windows

The package for Windows comtains files which should be used by PPM. Unzip the archive and set a local PPM repository to the PPM directory within the unzipped directory (the directory with the .ppd files in it).

To install the packages, ensure you are connected to the Internet, and install the DataCash-XMLPerlAPI package, which will in turn install the XML-Hash and Crypt-SSLeay packages as they are dependencies.

3.2 Configuration

Prior to creating your XML document, you first need to create a configuration file, as without this your transaction cannot be sent to DataCash. This file should be saved in a place your script has access to read, the exact location of this document is specified when you create the Perl objects in your script.

An example configuration file is:

  <Configuration>
    <logfile>./datacash.log</logfile>
    <logging>5</logging>
    <Obscure>
      <element>Transaction.CardTxn.Card.pan</element>
      <element>Authentication.password</element>
      <element>Transaction.CardTxn.Card.Cv2Avs.cv2</element>
    </Obscure>
    <host>https://testserver.datacash.com/Transaction</host>
    <port>443</port>
    <timeout>120</timeout>
    <setstrict>true</setstrict>
    <proxy>http://some.proxy.server:10000</proxy>
    <cacert_location>./root-certs.pem</cacert_location>
  </Configuration>
    

The most important variable to set is the host. This is where the transaction will be sent. Possible values for this option are available in the DataCash Overview document.

If the cacert_location configuration option is set, then the API will use the certificate file indicated to verify the SSL certificate of the transaction server. It is highly recommended that the certificate verification functionality is used. If information is required on how to acquire the appropriate root certificates, please check the DataCash Knowledge Base FAQ.

Details of the other configuration options are available from the perldoc of DataCash::Config.

3.3 Creating a Request

In basic terms, the procedure to perform an authorisation using the Perl API is to create an XML document, send it to DataCash and then receive the response, which will also be in the form of an XML document.

You create a DataCash::XMLDocument object like this:

  my $request = new DataCash::XMLDocument(configfile =>
                                          "/home/user/datacash.cfg");
    

You do not have to specify the configfile parameter, however doing so will ensure that the use of this object is logged to your logfile, if you have specified this option in your configuration. Thereafter, you populate the XML document by setting the values and attributes of the elements in the document.

There are two different ways to populate your XML document with the transaction details.

3.3.1 Accessor Methods

As an example, here is one way to create a very basic XML document that can be sent to the DataCash server. Note that the values here are hard-coded to keep the example simple.

   $request->authentication(client   => "12345678",
                            password => "mypassword");

   $request->carddetails(pan => "4444333322221111",
	                 expirydate => "03/09");

   $request->amount(amount   => "313.37",
	            currency => "IEP");

   $request->method("auth");
   $request->reference("123456789012");
    

This code does a number of things, using some of the special accessor methods in DataCash::XMLDocument. Firstly, it puts in your client (sometimes known as vTID) and password details into the document. Then, the PAN and expiry date are added. The amount and currency are added next. All of these methods take a hash as parameters, so therefore if the card has a start date or issue number, this can be included in the carddetails() method.

Next, the method of the transaction is added, which should be one of the allowed transaction types. Finally, a unique reference should be assigned to the transaction.

These methods all insert details into the XML document. The methods know where each of the specific elements live in the XML document according to our schema.

These are only a selection of the accessor methods available to you. For a full list of the methods, plus the parameters that they can take, please refer to the perldoc of DataCash::XMLDocument after you have installed the module to your system.

3.3.2 Directly Accessing Elements

You do not have to use these accessor methods if you do not wish to. Instead, you can use the standard set() method, which takes up to 3 parameters. The first parameter is a string which indicates the name of the element and the path to it in the XML document. The second parameter is the value of the element, and the third option (which is optional) is a hash containing the name(s) and value(s) of attributes. Therefore, to set the authentication details into the document using the set() method, you could do this:

  $request->set("Authentication.client", "12345678");
  $request->set("Authentication.password", "mypassword");
  $request->set("Transaction.TxnDetails.amount", "313.37", currency => "IEP");   
    

Note that the root element, which in a DataCash::XMLDocument document will be Request, should not be specified.

You can populate the entire document using the set() method if you wish, but it is probably simpler to use some if not all of the accessor methods we have provided. The choice is yours, as the XML document will be exactly the same whichever method you decide.

3.4 The XML Document

Once the XML document has been created, it should look something like this:


<?xml version="1.0" encoding="UTF-8"?>
<Request>
  <Authentication>
    <password>mypassword</password>
    <client>12345678</client>
  </Authentication>
  <Transaction>
    <TxnDetails>
      <merchantreference>123456789012</merchantreference>
      <amount currency='IEP'>313.37</amount>
    </TxnDetails>
    <CardTxn>
      <method>auth</method>
      <Card>
        <pan>4444333322221111</pan>
        <expirydate>03/09</expirydate>
      </Card>
    </CardTxn>
  </Transaction>
  <UserAgent>
    <architecture version='2.2.15pre14'>i386-linux</architecture>
    <language version='5.00503'>Perl</language>
    <Libraries bundle='lib-DataCash-perl' version='0.1a'>
      <lib version='0.9'>DataCash::XMLDocument</lib>
      <lib version='0.35'>XML::Hash</lib>
      <lib version='0.1'>DataCash::CardInfo</lib>
    </Libraries>
  </UserAgent>
</Request>

    

The UserAgent complex element is automatically added by the API to help with support issues, you do not need to do anything for these details to be added.

If, during initial setup you wish to output an XML document that you have created to check its contents, simply use one of the XML::Hash methods, as DataCash::XMLDocument simply extends this module:

  $request->writexml("Request");
    

The only parameter is the root element, therefore if you were to output the Response from DataCash, you would simply call:

  $response->writexml("Response");
    

Please note:
You should not keep a record of the XML Request document as it may contain information that you are not legally allowed to retain, such as the cv2 number. You should therefore only use this method on the Request document during testing.

3.5 Sending the Transaction

To send the transaction, and get the XML document that DataCash sends back to you, you need to create a DataCash::XMLSSLAgent object which is used to send the transaction and receive the response from the DataCash servers. Note, the constructor for the DataCash::XMLSSLAgent object must contain the conigfile parameter, otherwise the DataCash::XMLSSLAgent object will not know where to send the transaction.

  my $agent = new DataCash::XMLSSLAgent(configfile =>
                                        "/home/user/datacash.cfg");
  my $response = $agent->send($request);
    

This method blocks until a response is received, or the transaction times out. You can specify the timeout value in the Config.cfg file, see the perldoc with DataCash::Config for more details.

The object you get back will be another DataCash::XMLDocument object which you should then process to check the success or otherwise of the transaction, as well as obtain the authorisation code, DataCash reference etc. Depending upon the services DataCash provide to you, as well as the success or failure of the transaction, the response document could be either very small with only a couple of elements, or it could be highly complex. Refer to the Response schema, which is available from the DataCash general overview document, for details of information that you might receive.

For example, to obtain the status, reason, datacash_reference and authcode fields, you simply do this:

  my $status   = $response->get("status");
  my $reason   = $response->get("reason");
  my $dcref    = $response->get("datacash_reference");
  my $authcode = $response->get("CardTxn.authcode");
    

4. CardInfo Module

The other main module of note is the DataCash::CardInfo module. This performs validity checking on the credit card details, as well as providing information on the card in question.

To use this module, you need to create an instance of the module and then set it within the DataCash::XMLDocument object:

  my $ci = new DataCash::CardInfo(datadir => "/home/user/data/");
  my $cardinfocheck = $request->setcardinfo($ci);
    

After this, you can query the issuer, country of issue and scheme of the card by calling:

  print "Scheme: " . $ci->scheme . "\n";
  print "Country: " . $ci->country . "\n";
  print "Issuer: " . $ci->issuer . "\n\n";
    

Once you have set the DataCash::CardInfo module within the DataCash::XMLDocument object, the details of the credit card will also be checked for validity. This is done when the setcardinfo() method is called. The returned value, in the example called $cardinfocheck will either be undef if the details are valid, or it will contain a DataCash::XMLDocument object with details of what the problem is. Specifically, the status and reason elements will contain details of the error that was returned.

In addition, if you have set the setstrict configuration parameter to true, a transaction that fails the validity checking process will not be sent to the DataCash servers, even if you create a DataCash::XMLSSLAgent object and try to run the send() method. Instead, you will receive the same DataCash::XMLDocument object as is returned from the setcardinfo() method, which will contain the details of the problem with the card.

5. Security Implications

There are four data fields that must be kept secret for every transaction. These are the customer's credit card number, cv2 number, and the merchant's password and encryption key. If these pieces of information leak, anybody with a copy of the DataCash API could pretend to be the merchant.

For this reason, this is not logged on the client side during a transaction. The log file does not in itself hold sufficient information to build valid XML requests.

Do not reveal this information to anybody, especially over the phone, even if it is somebody claiming to be an employee that needs it before they can get on with their job.