Implementing DataCash 3D Secure with ASP.net

This is an article I’ve been meaning to write for a while now…

Mainly, to help others out, who are struggling with the near non-existent documentation provided by Datacash, when trying to plug 3D Secure into my ASP.net application.

I’m sure you’re already familiar with what 3D Secure is, so I won’t go in to too much detail, nor will I go into much detail with regards to the process.

The purpose of this article is to get you familiar with how to send the details to the DataCash MPI, receive a response, and display and use the 3D Secure window in an iFrame (or framed window for that matter)

Please note:
This code is for tutorial purposes only. It’s dirty, crude, buggy, and not refactored in any way shape or form.
I simplified the code down to bare bones, in order to better explain each element.
Obviously, it comes without warranty… it should work as expected, but has no logging, error trapping or any of that good stuff… and when dealing with online payments, you really should take more care!

Code

Update – 8th September, 2011:

GitHubI’ve now hosted the code on GitHub

You will need to edit the web.config to add your own VTID and Password

Payment Page

This is the functionality that processes payment – for example, allows the customer to enter their credit card details etc…

The mark-up is fairly straight forward.

Two things to note are the body, and the form tag:

<body id="myBody" runat="server">

Note that the body tag is runat server

<form id="MainForm" runat="server">

Note that  the name is “MainForm” – we will need this later.

Since in this tutorial, I’m showing how to use an iFrame, I have this bit of code, below the payBtn:

<asp:Panel ID="ACSFramePanel" runat="server" Visible="false">
    Please verify.....<br />
    <br />
    <iframe src="" name="ACSFrame" width="450" height="400" frameborder="0" />
</asp:Panel>

Line 4 of the above is basically where the 3D Secure frame will appear.

I wrapped it in a Panel, so that we can hide it, while the customer enters their card details etc…

Now, let’s look at some of the code-behind:

private Config config;
private Agent agent;

//this would be our order id / reference in production
private string ourReference = Guid.NewGuid().ToString("n").Substring(0, 8);

protected void Page_Load(object sender, EventArgs e)
{
    config = new Config(AppDomain.CurrentDomain.BaseDirectory + "datacash.conf"); // would probably need to come from web.config
    agent = new Agent(config);
}

In the above code, Config and Agent are both DataCash objects.

In the Page_Load event, we basically set these two objects up.

config is set from an xml file (located in the project root) called datacash.conf – this can of course be located anywhere you like (and called anything you like)

agent is then set using the defined config object.

The config file looks like this:

<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>

  <!--this would be for the live server-->
  <!--<host>https://mars.transaction.datacash.com/Transaction</host>-->

  <host>https://testserver.datacash.com/Transaction</host>
  <port>443</port>
  <timeout>90</timeout>
  <setstrict>true</setstrict>
</Configuration>

Of course, this doesn’t have to be done in Page_Load – in “the real world” this would all be part of a payment helper class. But for demo purposes, it’s fine in the Page_Load – just means we have to repeat ourselves on other pages…

Next, we assume the user fills out the form, and presses the Pay button.

Sending the request to DataCash

protected void payBtn_Click(object sender, EventArgs e)
{
    //so they don't press the button twice.
    payBtn.Enabled = false;

    //get browser info (for 3d secure stuff)
    var browser = Request.Browser.Browser;

    var request = buildAuthDataCashDocument(
        ourReference,
        cardNumber.Text,
        expiryMonth.Text,
        expiryYear.Text,
        startMonth.Text,
        startYear.Text,
        issueNumber.Text,
        secCode.Text,
        billingAddress1.Text,
        billingAddress2.Text,
        billingAddress3.Text,
        billingAddress4.Text,
        billingAddressPostCode.Text,
        browser);

    //send the request document to the agent.
    //todo: could implement some kind of error trapping / retry here
    var authResponse = agent.send(request);

    //get the datacash transaction reference (just in case we need to try authorizing the payment without 3D Secure)
    var datacashRef = authResponse.get("Response.datacash_reference");

    //get the response code
    var responseCode = authResponse.get("Response.status");

This code basically generates a XML document with the payment authorisation request, and submits it to DataCash.

I refactored buildAuthDataCashDocument as it was pretty large, and made the code a bit too dirty, even for this demo!

Couple of bits of note within buildAuthDataCashDocument are:

request.set("Request.Authentication.client", ConfigurationManager.AppSettings["DataCashVtid"]);
request.set("Request.Authentication.password", ConfigurationManager.AppSettings["DataCashPassword"]);

This basically sets the VTID and Password from config (in our case, web.config) which looks like:

<appSettings>
   <add key="DataCashVtid" value="99******"/>
   <add key="DataCashPassword" value="bK*******"/>
</appSettings>

Also, within buildAuthDataCashDocument is:

request.set("Request.Transaction.TxnDetails.ThreeDSecure.verify", "yes");
request.set("Request.Transaction.TxnDetails.ThreeDSecure.merchant_url", "www.crocus.co.uk"); //or whatever brand??
request.set("Request.Transaction.TxnDetails.ThreeDSecure.purchase_desc", "Items from Crocus"); //or some other short sumary
request.set("Request.Transaction.TxnDetails.ThreeDSecure.purchase_datetime", DateTime.Now.ToString("yyyyMMdd HH:mm:ss"));

This is important, for 3D Secure – Fairly self explanatory.

After building our request Document, we need to send it to DataCash, and get another Document back – as a response.

To do that, it’s as simple as:

var authResponse = agent.send(request);

This sets authResponse to the response Document.

We can then use the .get() method on authResponse to retrieve elements from it.

We are most interested in Response.datacash_reference and Response.status

The datacash_reference is unique to each and every transaction processed, so it is useful for later things like refunds, reporting etc…

Response.status is the DataCash status code for this transaction.

It’s from this, that we determine how to proceed.

switch (responseCode)
{
    //handle 3DS error responses....`
    //Basically, if it's one of these, the transaction is screwed, and shouldn't proceed....
    case "151": 		//	3DS Invalid Transaction type
    case "152": 		//	3DS Manual Authorization not supported
    case "153": 		//	3DS verify element missing
    case "154": 		//	3DS Invalid verify value
    case "155": 		//	3DS field missing
    case "156": 		//	3DS Invalid Browser.device_category
    case "157": 		//	3DS Merchant not enabled
    case "159": 		//	3DS No VERes from DS
    case "160": 		//	3DS Invalid VERes from DS
    case "161": 		//	3DS call auth centre

        //log the error here
        break; //- throw them out of transaction process. Should redirec

    case "56": //speed limit - too many transactions on that card number in short space of time
        break;

    //3ds payer verification required....
    case "60":
    case "150":
        show3DSIframe(authResponse);
        Response.Clear();
        break;
}

I won’t go in to too much detail, as the comments kind of speak for themselves…

Basically, if you get a 60 or 150 then the transaction requires you to show the 3D Secure window.

Showing the 3D Secure iFrame

I’ll spend a bit of time on show3DSIframe, as this is the part that caused me the most hassle – How to actually display the ACS in an iFrame, especially in ASP.net

private void show3DSIframe(Document doc)
{
    ACSFramePanel.Visible = true;

    //this is the data cash reference number for this transaction
    var dataCashReference = doc.get("Response.datacash_reference");

    //this is the url of the ACS - the page generated by the bank, that contains the
    //boxes where the customer enters information etc...
    var acsUrl = doc.get("Response.CardTxn.ThreeDSecure.acs_url");

    //this is a long message / code that is generated for the transaction
    var pareq = doc.get("Response.CardTxn.ThreeDSecure.pareq_message");

Ok, so in the markup from Part 1, you may remember I wrapped the iFrame in a Panel, called ACSFRamePanel. Now, we need to set the visibility to true.

These first few lines are self explanatory – we need to get the dataCashReference, acsUrl (the URL of the 3D Secure page – this is usually returned by the customers issuing bank) and the pareq – this is a long string, that’s a bit like a password for the transaction.

These elements are retrieved from the passed in DataCash Document.

We then need to create our Term URL – This is basically a URL that the 3D Secure window POSTs back to:

var termUrlPrefix = Request.ServerVariables["HTTPS"] == "ON" ? "https://" : "http://";

//termUrl is where the ACS page posts back to.
var termUrl = string.Format("{0}{1}",
    termUrlPrefix,
    Request.Url.Authority + "/3DSResponse.aspx");

In our demo case, it’s just on our local host machine – this could however, for example, be something like www.myUrl.com/checkout/3DSresponse.aspx

This next part is the important part.

This set’s the required hidden fields (PaReq and TermUrl) on our form.

We then register another hidden form – “MD” – This is our order number / reference for this transaction – so we can retrieve it from our database, and update the status when we come out the other side of 3D Secure.

The next line generates a little bit of JavaScript that basically causes this form to submit itself to the acs url.

The result of this, is then output to the target (parameter 3 in our string.format) – ACSFrame.

Remember we called our form “MainForm” 🙂

Then, myBody.Attributes.Add inserts the resulting JavaScript to the onLoad function of our body tag.

Remember we made runat server earlier

//ClientScript.RegisterHiddenField adds a hidden field to the form...
ClientScript.RegisterHiddenField("PaReq", pareq);
ClientScript.RegisterHiddenField("TermUrl", termUrl);

//this is the data cash reference, and our reference -
//so we can update the order on the other side of the verification (paid, failed etc...)
ClientScript.RegisterHiddenField("MD", dataCashReference + "|" + ourReference);

var js = string.Format("javascript: document.{0}.action='{1}'; document.{2}.target=\"{3}\"; document.{4}.submit();",
    MainForm.ID,
    acsUrl,
    MainForm.ID,
    "ACSFrame",
    MainForm.ID
);

//since the body tag of this page is called myBody, and is runat=server, we can access
//it here, and inject our javascript.
myBody.Attributes.Add("onLoad", js);

And there we have it – the 3D Secure window is displayed in an iFrame

I’ll edit this post with a link to 3DSResponse.aspx when I finish that article…

Hope this helps! Feel free to 😉

btn_donate_SM

7 responses to “Implementing DataCash 3D Secure with ASP.net”

  1. Kalyan avatar
    Kalyan

    This is very useful article which explains neatly how to use DataCash payment service, and waiting for 3DSResponse.aspx post.

    Have a nice day

  2. Dave MacRae avatar

    Alex,

    Good tutorial.

    A couple of minor points:

    “merchant_url” should be a fully qualified, secure, URL. Visa recommend that this is the URL of your customer service page.

    termUrlPrefix should always be HTTPS.

    Regards

    Dave
    Senior Product Manager – DataCash

  3. Kalyan avatar
    Kalyan

    It is possible to get the Transaction DLL source code.

    1. Alex avatar

      unfortunately not, as this is part of the DataCash SDK. There is nothing stopping you using Reflector on this assembly though…

  4. Matt Frith avatar
    Matt Frith

    This is great – exactly what I requested from Datacash.

    I’m having problems working out where the PaRes code comes from as your code is inserting PaReq which is returned from the authorisation request.

    Your code states:

    var pares = Request.Form[“pares”];

    but I can’t see where you are displaying pares in the 3DS.aspx iframe.

    1. Alex Brown avatar

      Sorry.. i’m not sure –
      It’s many years since I wrote that article / used datacash

      Did you check out the example project on github?

      https://github.com/alexjamesbrown/Datacash-3DSecure/blob/master/DataCash3DSecure/3DSResponse.aspx.cs#L18

      3DSResponse.aspx is what i configured datacash to postback to from here

      https://github.com/alexjamesbrown/Datacash-3DSecure/blob/master/DataCash3DSecure/PaymentPage.aspx.cs#L109-L112

  5. Sandy Thomson avatar
    Sandy Thomson

    Hi Alex,
    Cheers for putting this guide together, it looks pretty good.

    Just one thing I noticed though, I believe an error 60 is the response code for invalid XML. I don’t think the 3-D Secure transaction can be completed if you receive an error 60.

    Cheers,

    Sandy Thomson
    Software Engineer – DataCash

Leave a Reply

Your email address will not be published. Required fields are marked *