| Document Version | Last Updated |
|---|---|
| 1.02 | 7 August 2001 |
| Changelog | |
The documentation is in three separate levels. There is a general overview of how the DataCash system works, which applies to all of the latest releases of our API software. Then there is a software specific API overview, which details installation, configuration and use of the software. Thereafter, there is documentation on the method sets themselves, in the general format of the language in question, such as javadoc or perldoc.
This document is the general overview.
DataCash is a payment gateway which enables you to receive credit and debit card payments for your goods and services. Our merchants typically use our API software to integrate their own systems with our gateway. We have a range of API software written in a range of different languages which can be used on many platforms.
To process a transaction through DataCash, the details of this transaction need to be captured, formatted in an appropriate message format for the receiving bank, and the subsequent Bank response is then passed back to the merchant.
Most of this work is done by the DataCash servers. The capture of the details for the transaction is done by the merchant's server, and our API software helps you to do this. Thereafter, the details are sent by the API to our server, and the response is returned to you.
In August 2001, DataCash Ltd released a new range of software APIs written in Perl and Java. There are two main differences in the way that the new API software functions.
Firstly, the details of the transaction are sent by the API to the DataCash servers by the HTTPS protocol. HTTPS is recognised and endorsed, indeed the Banks and card schemes are basing their recommendations on HTTPS. It has significant cross-platform support, and the security is based on SSL, a transport layer protocol. It also has maturity as a secure protocol.
The second major change is that the details of the transaction are now sent to our servers in an XML document. XML is now a widely used format for sending complex data between systems. One such benefit of this is the versatility of transforms, so that an XML document created in BizTalk can be converted to a format acceptable by our schema prior to it being sent to us. XML is highly extensible which allows us to adopt a plug-and-play approach with the protocol. The maturity of tools that are used with XML documents is also excellent, with most languages having libraries that can be used to create, modify and read data in XML documents.
There are services that DataCash are shortly going to be able to provide its merchants that require enriched datasets to be sent to us. One such service is an enhanced anti-fraud service. The previous design of API did not allow us to send through such a wide and varied range of information in a structured manner.
The API software that DataCash provides is designed to assist merchants in collecting transaction data, constructing the XML document, and then sending this document to the DataCash servers. The software also deals with receiving the response and providing methods to access the details contained within it.
Full details on the exact method sets are available with the API software. However, the general workings of each are similar, and the general process is as follows.
The APIs have methods which allow you to set the values of elements in an XML document. The XML document needs to be constructed according to the Request schema.
When a transaction is sent to the DataCash servers, you will receive an XML document in return, which will be constructed according to our Response schema. The complexity of the response will be dependant on the services you have subscribed from DataCash and the information that is sent to us. For instance, if a credit card number is invalid, the Response document will have very few details. However, if the details were all correct and cv2/AVS details were sent as part of the transaction, the Response will be significantly more complex.
The Request and Response schemas can be downloaded from here:
| Request | request.xsd |
|---|---|
| Response | response.xsd |
The other main similarity with the latest API software that we provide is the card detail checking mechanism. We have details of almost every credit and debit card range issued, which allows us to check whether we have all necessary details before sending a transaction to the bank. These details have been built into binary files which are read by modules written for the API software to use.
The modules check the length of the credit card number and whether there is a start date or issue number required. If the details contained within the XML document is not in agreement with what we expect, the transaction can be prevented from being sent to the DataCash servers.
In addition to this, certain details about the credit card can also be located. The Issuer, Country of Issue and Scheme can all be determined from the CardInfo module.
To perform the checks, the two binary files containing the information need to be available to the modules. These binary files will be updated from time to time as new cards ranges are issued, and therefore the files need to reflect these additions.
You will find details on how to use the CardInfo modules with the specific API software, however the CardInfo*.bin files will be available for download separately, as these are not specific to any one API.
We currently have a live system and a test system. No transactions sent to the test system are sent to the banks, instead our servers send back automated responses as if the banks have been contacted. Therefore, no funds will be deducted from cards whose details are used in the process of testing.
The systems are entirely separate, and to that end they also have separate accounts and reporting facilities. The details of each are available from the DataCash XML API FAQ.