Document Version | Last Updated |
---|---|
1.01 | 28 August 2001 |
Changelog |
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.
In addition to this overview document, there is perldoc contained within the Perl modules themselves, which give specific detail on the methods and constructors.
This API is intended for use with Perl 5. It has been created and tested on version 5.005_03.
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:
tar xzf filename
, or (if your
version of tar doesn't support the z flag) gunzip filename
then tar xf filename
cd
into the directory that has been created
perl Makefile.PL
. A small script will run
that sets up the module for installation
make
. The module will be compiled and set
up for installation.
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.
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.
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
.
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.
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.
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.
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.
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");
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.
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.