Considering the DataCash XML API - Beginning ASP.N- 123docz.net

You’ll be doing a lot of XML manipulation when communicating with DataCash because you’ll need to create XML documents to send to DataCash and extract data from XML responses. In this section, we’ll take a quick look at the XML required for the operations you’ll be performing and the responses you can expect.

Preauthentication Request

When you send a preauthentication request to DataCash, you need to include the following information:

• DataCash username (known as the DataCash Client)

• DataCash password

• A unique transaction reference number (explained later in this section)

• The amount of money to be debited

• The currency used for the transaction (USD, GBP, and so on)

• The type of the transaction (for preauthentication, the code pre is used)

• The credit card number

• The credit card expiry date

• The credit card issue date (if applicable to the type of credit card being used)

• The credit card issue number (if applicable to the type of credit card being used) The reference number must be a number between 6 and 12 digits long, which you choose to uniquely identify the transaction with an order. Because you can’t use a short number, you can’t just use the order ID values you’ve been using until now for orders. However, you can use this order ID as the starting point for creating a reference number, simply by adding a high number, such as 1,000,000. You can’t duplicate the reference number in any future transactions, so you can be sure that after a transaction is completed, it won’t execute again, which might otherwise result in charging the customer twice. This does mean, however, that if a credit card is rejected, you might need to create a whole new order for the customer, but that shouldn’t be a problem if required.

The XML request is formatted in the following way, with the values detailed previously shown in bold:

<?xml version="1.0" encoding="UTF-8"?>

<password>DataCash password</password>

<client>DataCash client</client>

</Authentication>

<merchantreference>Unique reference number</merchantreference>

<amount currency='Currency Type'>Cash amount</amount>

</TxnDetails>

<Card>

<pan>Credit card number</pan>

<expirydate>Credit card expiry date</expirydate>

</Card>

</CardTxn>

</Transaction>

</Request>

Response to Preauthentication Request

The response to a preauthentication request includes the following information:

• A status code number indicating what happened; 1 if the transaction was successful, or one of several other codes if something else happens. For a complete list of return codes for a DataCash server, log in to https://testserver.datacash.com/software/download.cgi with your account details and download the relevant document.

• A reason for the status, which is basically a string explaining the status in English. For a status of 1, this string is ACCEPTED.

• An authentication code used to fulfill the transaction.

• A reference code for use by DataCash.

• The time that the transaction was processed.

• The mode of the transaction, which is TEST when using the test account.

• Confirmation of the type of credit card used.

• Confirmation of the country that the credit card was issued in.

• The authorization code used by the bank (for reference only).

The XML for this is formatted as follows:

<?xml version="1.0" encoding="utf-8"?>

<status>Status code</status>

<reason>Reason</reason>

<merchantreference>Authentication code</merchantreference>

<datacash_reference>Reference number</datacash_reference>

<card_scheme>Card Type</card_scheme>

<country>Country</country>

<issuer>Card issuing bank</issuer>

<authcode>Bank authorization code</authcode>

</CardTxn>

</Response>

Fulfillment Request

For a fulfillment request, you need to send the following information:

• DataCash username (known as the DataCash Client)

• DataCash password

• The type of the transaction (for fulfillment, you use the code fulfil)

• The authentication code received earlier

• The reference number received earlier

Optionally, you can include additional information, such as a confirmation of the amount to be debited from the credit card, although this isn’t really necessary.

This is formatted as follows:

<?xml version="1.0" encoding="UTF-8"?>

<password>DataCash password</password>

<client>DataCash client</client>

</Authentication>

<reference>Reference Number</reference>

<authcode>Authentication code</authcode>

<method>fulfil</method>

</HistoricTxn>

</Transaction>

</Request>

Fulfillment Response

The response to a fulfillment request includes the following information:

• A status code number indicating what happened; 1 if the transaction was successful, or one of several other codes if something else happens. Again for a complete list of the codes, log in to https://testserver.datacash.com/software/download.cgi with your account details and download the relevant document.

• A reason for the status, which is basically a string explaining the status in English. For a status of 1, this string is FULFILLED OK.

• Two copies of the reference code for use by DataCash.

• The time that the transaction was processed.

• The mode of the transaction, which is TEST when using the test account.

The XML for this is formatted as follows:

<?xml version="1.0" encoding="utf-8"?>

<status>Status code</status>

<reason>Reason</reason>

<merchantreference>Reference Code</merchantreference>

<datacash_reference>Reference Code</datacash_reference>

</Response>

Exchanging XML Data

You could build up the XML documents shown previously piece by piece, but the .NET Frame- work allows you to do things in a much better way. The solution presented here involves XML serialization. It’s possible to configure any .NET class so that it can be serialized as an XML document, and that XML documents also can be used to instantiate classes. This involves converting all public fields and properties into XML data and is the basis for the web services functionality in .NET.

The default behavior for this is to create XML documents with elements named the same as the public fields and properties that you are serializing. For example, you might have the following class and member:

public class TestClass {

public string TestMember;

}

This is serialized as follows:

<?xml version="1.0" encoding="utf-8"?>

<TestMember>Value</TestMember>

</TestClass>

You can override this behavior using XML serialization attributes. You can force pieces of data to be formatted in elements with custom names, as attributes, as plain text, and so on.

For example, you could force the previous class to serialize as an attribute as follows:

public class TestClass {

[XmlAttribute("TestAttribute")]

public string TestMember;

}

The [XmlAttribute()] part means that the member that follows should be serialized as an attribute, and the string parameter names the attribute. This class now serializes as follows:

<?xml version="1.0" encoding="utf-8"?>

You can use several of these attributes, and you’ll see some of them in the example that follows. This example demonstrates how you can create classes that represent DataCash requests and responses, which are capable of serializing to and deserializing from an XML representation. This makes it easy to send data to DataCash and allows you to use the full power of .NET classes to provide an intelligent way of accessing data.

In the example that follows, you’ll create the classes necessary to exchange data with DataCash and try out these classes using some simple client code. Note that several classes are used to build up the XML because the structure involves several nested elements rather than a flat structure.