3DS Card Processing

This section will be of interest to those wanting to submit 3-D Secure authenticated credit card transactions. Readers should be familiar with using the API in general and Card Payments specifically.

Raven supports 3-D Secure (3DS) for real-time authorizations. 3-D Secure requires the customer to identify themselves, thus ensuring they are authorized to use the card. 3-D Secure works the same for both Visa and MasterCard. Visa refers to it as Verified by Visa and MasterCard refers to it as SecureCode. A transaction using Verified by Visa (fVbV) or SecureCode will initiate a redirect to the website of the card issuing bank to authorize the transaction and will also require that the customer authenticate themselves. Issuers can use any kind of authentication method, although a PIN-based method is typically used. Merchants are encouraged to use 3-D Secure to achieve higher coverage against fraud. When a merchant does not use 3-D Secure they are liable for fraudulent transactions even if the transaction was properly authorized.

3-D Secure can only be used with card transactions of type ‘cc_debit’ or ‘cc_preauth’.

3-D Secure is a multi-step interaction involving the following fields. The column ‘Req/Rsp’ indicates if the field forms part of the request to RAVEN (Req)or part of the response from RAVEN (Rsp). Except as noted, RAVEN will echo all request fields in the response. The column O/C/M indicates if a field is optional, conditional or mandatory.

Field	Type	Max. Size	Req/Rsp	O/C/M	Remarks
3DSVerify	B		Req	O
3DSMerchantURL	T	1024	Req	C¹	The URL of the merchant’s website
3DSDeviceCategoryCode	One Of		Req	C¹	Indicates the type of device used to perform transaction: mobile desktop
3DSBrowserAcceptHeader	T	4096	Req	C¹	The MIME types accepted by this device, as defined in the accept header.
3DSBrowserUserAgentHeader	T	4096	Req	C¹	The user agent string.
3DSPAReq	T		Res	O	The Payer Authentication Request (PAReq) that needs to be submitted to the ACS
3DSACSURL	T		Res	O	The URL of the Issuing Bank’s ACS, to which the cardholder needs to be re-directed
3DSPARes	T	4096	Req	C²	The Payer Authentication Response (PARes) that was received from the ACS
TrackingNumber	N	10	Req	C²	The tracking number that was received from the Raven for the original request

¹ These fields are mandatory when 3DSVerify is set to ‘true’.

² This field is mandatory when re-submitting authorization request as described in Step 5 below

3-D Secure Interaction

Step 1

Authorization request is submitted to RAVEN with the following fields set (see the table above for additional details):

3DSVerify – set to true, telling RAVEN to invoke 3DS
3DSMerchantURL – URL of the merchant’s website
3DSDeviceCategoryCode – mobile or desktop
3DSBrowserAcceptheader – the MIME types accepted
3DSBrowserUserAgentHeader – User agent

RAVEN checks to see if the card is enrolled in its respective 3-D Secure scheme.

If the cardholder is not enrolled, flow jumps to Step 6 and authorization proceeds in the normal fashion.

Step 2

If the cardholder is enrolled, Raven does not proceed with authorization, but instead responds to the merchant with the URL of an issuing bank’s Access Control Server (ACS) in the 3DSACSURL field as well as a payer authentication request (PAReq) in the 3DSPAReq field.

Step 3

PAReq now needs to be submitted to the ACS through the cardholder’s browser/device using an <iframe> HTML element. Cardholder will in turn be presented with their issuing bank’s interface for enrollment or password validation.

This request must come from the cardholder’s computer, not from the merchant’s server. This form must contain the following elements:

Element	Name	Content
Target	acsframe	Value of 3DSACSURL from RAVEN’s response in Step 2
Hidden field	PaReq	Value of 3DSPAReq from RAVEN’s response in Step 2
Hidden field	TermUrl	URL to direct customer to after the interaction with ACS
Hidden field	MD	Merchant data field which contains a unique transaction reference. This must allow the merchant to find the original request in their system.

Here’s an example code that could be used to present ACS frame to the customer:

<form name="acsform" target="acsframe" action="{Value of 3DSACSURL from Raven's response}"> <input type="hidden" name="PaReq" value="{Value of 3DSPAReq from Raven's response}"/> <input type="hidden" name="TermUrl" value="{URL to redirect customer after interaction with ACS}"/> <input type="hidden" name="MD" value="{Merchant's unique transaction reference}"/> <iframe name="acsframe" width="750" height="600"/> <script type="text/javascript"> document.acsform.submit(); </script> </form>
Please note that the above JavaScript code, or something similar, is essential to the way 3-D Secure works. The customer must be redirected from their own browser window to the location specified in the 3DSACSURL field.

Step 4

After the customer is authenticated by their bank, the ACS displays a page that causes the browser to automatically POST the following fields to the TermUrl supplied in Step 3:

Name	Content
PARes	Payor authorization response generated by the ACS
MD	Merchant data field which contains a unique transaction reference. This must allow the merchant to find the original request in their system.

Step 5

The merchant’s server must then use the MD field to fetch its record of the transaction and resubmit the authorization request to RAVEN with the 3DSPARes field set to the value of the PARes received from the ACS, and the TrackingNumber field set to the value of TrackingNumber received from RAVEN in Step 2. Note that a separate URL must be used to submit this follow-up transaction:

https://raven.deepcovelabs.com/realtime/complete

RAVEN verifies the ACS signature on the PARes, parses the response and continues to Step 6.

Step 6

RAVEN transmits the authorization request to the acquiring bank and responds with the result of authorization just as in the non 3-D Secure case.

Step 7

The merchant’s server responds appropriately, depending on the outcome of the authorization as in the non 3-D Secure case.