Introduction
What is 3D secure?
3D Secure is a latest initiative for fraud prevention launched by Visa and MasterCard. 3D Secure adds additional password authentication step to complete the online transactions. A detailed introduction is available at http://www.sagepay.com/developers/industry_knowledge/3d_secure.asp.
This tutorial is a guide to set up a Ruby on Rails test environment for 3D Secure payment transactions using ActiveMerchant plugin.
And why should we care?
3D Secure is becoming an industry standard and it is mandatory for processing Mastero card payments. Also, the deadline for 3-D Secure mandate (United Kingdom) for Maestro transactions is January 31st, 2010 and we want to make sure our applications are compliant by that date.
How does it work?
Fig 1: 3D Secure transaction
Setup
1. Patch ActiveMerchant plugin
To get this working, apply this patch to add 3D Secure support for SagePay gateway. The patch is taken from http://github.com/tekin/active_merchant, however it is modified for SagePayGateway instead of ProtxGateway. Alternately, you can use http://github.com/dynamic50/active_merchant to follow this tutorial.
2. Set up SagePay simulator environment
Apply for a simulator account at https://support.sagepay.com/apply/. The registration process is instant and the support team is quick in responding to your queries. Once your account is created, log on to configure the simulator for direct messages.
Clicking on the “Direct” button takes us to Direct Options and parameters admin page.
Set response for authorization POSTs to 3DAUTH as shown below. In short, we are forcing the response for all validate requests to be 3DAUTH.
http://whatismyip.com for help.
Also, select the “Simulate Direct” checkbox.
In config/environments/development.rb
ActiveMerchant::Billing::Base.mode = :test ActiveMerchant::Billing::SagePayGateway.simulate = true
Make a note that test and simulator are different environments for SagePay payment gateway.
3D Secure Payment Transaction
A typical 3D secure transaction works in four steps as shown in Fig 1. Initialize the gateway and a dummy valid credit card:
card = ActiveMerchant::Billing::CreditCard.new({:number => '4111111111111111',:first_name => 'Cody',:last_name => 'Fauser', :month => '8',:year => "#{ Time.now.year + 1 }",:verification_value => '123', :type => 'visa'})
gateway = ActiveMerchant::Billing::SagePayGateway.new({ :login => LOGIN, :password => PASSWORD,:enable_3d_secure => true })
Step 1: Authorize
res = gateway.authorize(1000, card,rder_id => )
Note: the amount is in pence and order_id can be any unique identifier for your transaction.
The response of this request gives us the PAReq, MD and ACSURL values:
<activeMerchant::Billing::Response:0x2505080 @pa_req=<pareq>, @message="Unspecified error", @fraud_review=nil, @authorization=< authorization >, @acs_url="https://test.sagepay.com/Simulator/3DAuthPage.asp", @cvv_result={"message"=>nil, "code"=>nil}, @params={"Status"=>"3DAUTH", "MD"=>< MD >, "ACSURL"=>"https://test.sagepay.com/Simulator/3DAuthPage.asp", "PAReq"=> < PAReq >, "VPSProtocol"=>"2.23", "3DSecureStatus"=>"OK"}, @three_d_secure=true, @success=false, @md=< MD >, @test=true, @avs_result={"message"=>nil, "code"=>nil, "street_match"=>nil, "postal_match"=>nil}>
@three_d_secure=true and @success=false imply that we need to complete the 3DSecure authorization first.
Step 2: 3D Authorization
To initiate the 3D Secure authorization, we should post PAReq, MD and the callback url (TermURL) to ACSURL.
We can do it using curl command as:
curl -d "PAReq=<pareq>&TermURL=http://myapp.com/callback_url" https://test.sagepay.com/Simulator/3DAuthPage.asp > temp.html
The response is a html page, captured in temp.html. Edit it and pick up the VPSTxID.
The simulator allows us to send different responses for multiple scenarios. We assume that we have entered correct password and we want to simulate a successful 3D transaction. In this case, we respond to this action by clicking the ‘OK’ button.
This can be done as:
curl -d "clickedButton=ok&VPSTxID=<vpstxID>&MD=<md>&TermURL=http://myapp.com/callback_url" https://test.sagepay.com/Simulator/3DAuthPage.asp > temp.html
Essentially, we have simulated a “correct 3d password submit” action. The gateway should return a PARes token (for the initiated PAReq value) which can be found out from temp.html.
Step 3: Complete 3D authorization
On the console, call:
gateway.three_d_complete(<pares>, <md>)
The response should be similar to:
<activeMerchant::Billing::Response:0x24952bc @pa_req=nil, @message="Success", @fraud_review=nil, @authorization=< authorization >, @acs_url=nil, @cvv_result={"message"=>nil, "code"=>"Y"}, @params={"Status"=>"OK", "VPSTxId"=>< VPSTxId >, "SecurityKey"=>"<security Key>", "StatusDetail"=>"Direct 3D-Secure transaction from Simulator.", "AVSCV2"=>"SECURITY CODE MATCH ONLY", "VPSProtocol"=>"2.23", "TxAuthNo"=>"6598", "3DSecureStatus"=>"OK", "CAVV"=>"<cavv>", "AddressResult"=>"NOTMATCHED", "PostCodeResult"=>"MATCHED", "CV2Result"=>"MATCHED"}, @three_d_secure=false, @success=true, @md=nil, @test=true, @avs_result={"message"=>nil, "code"=>nil, "street_match"=>"N", "postal_match"=>"Y"}>
@message=”Success” confirms that the 3D authorization was successful. As a last step, we need to complete the transaction by capturing this payment.
Step 4: Capture Payment
SagePay requires you to remember the order_id that you used to initiate the authorization. Get the authorization code from previous response and prefix it with the order id.
Ex: =”a6f8c776ac58dcf08;{FB448BBF-CB72-414A-B293-316004162EEB};6598;OUWEBUCWL3;three_d_complete”
gateway.capture(<amount>, <order_id> + <authorization_code>)
<activeMerchant::Billing::Response:0x23b41f4 @pa_req=nil, @message="Success", @fraud_review=nil, @authorization=< order_id + authorization >, @acs_url=nil, @cvv_result={"message"=>nil, "code"=>nil}, @params={"Status"=>"OK", "StatusDetail"=>"The transaction was RELEASEed successfully.", "VPSProtocol"=>"2.23"}, @three_d_secure=false, @success=true, @md=nil, @test=true, @avs_result={"message"=>nil, "code"=>nil, "street_match"=>nil, "postal_match"=>nil}>
The aim of this tutorial was to demonstrate a 3D secure payment transaction with details of the tokens exchanged between gateway and the client. On these lines, we can extend rails support for other gateways to handle 3D Secure authentication. Please leave your comments with suggestions or issues.
