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:
I’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 😉
