3DS Card Processing

This section will be of interest to those wanting to submit 3-D Secure authenticated credit card authorization requests; payment types cc_debit and cc_preauth only. Readers should be familiar with using the API in general and Card Payments specifically.

RAVEN supports 3-D Secure (3DS) for real-time authorizations. 3DS 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 (VbV) 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.

3-D Secure Interaction

3-D Secure verification requires a three step interaction between your server, Raven, and a cardholder’s issuing bank:

Initiation – Your server must first submit a payment request to Raven, indicating 3-D Secure is required and providing several 3-D Secure parameters (see table below). Raven will then check with the issuing bank to determine if 3-D Secure is available. If 3DS is not available, Raven will automatically perform an approval request to which the 3-D Secure guarantees will not apply.
Authentication – If 3-D Secure is available, Raven will return with the URL of the issuing bank’s Access Control System (ACS), to which your customer must be directed to authenticate themselves, as well as a payment authentication request (PAReq) that must be passed to the ACS.
Approval – Assuming 3-D Secure was available, the issuing bank will return a payment authentication response (PARes) to your server which must then be passed on to Raven, along with details of the original request. Raven will verify the authentication response. If it is valid, Raven will indicate 3DS has Passed and perform an approval request. If the authentication response is not valid, Raven will indicate 3DS has Failed and respond with Declined for the approval. If at this late stage the 3DS system has become unavailable and the response cannot be verified, Raven will once again automatically perform an approval request to which the 3-D Secure guarantees do not apply.

Please note: If your business cannot accept any payments without a 3DS guarantee, then only if the 3DSResponseCode returned by Raven is Passed do the 3-D Secure guarantees apply. For any other value of the 3DSResponseCode, no 3-D Secure authentication has taken place and no liability shift has occurred. If you do not want to proceed without a 3-D Secure guarantee, you must ensure transactions without a 3DSResponseCode of Passed are not settled.

Steps in detail – Step 1: Initiation

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

3DSVerify – set to true, telling RAVEN to invoke 3DS
3DSMerchantURL – merchant’s website URL to which control should be passed in step 2
3DSDeviceCategoryCode – mobile or desktop
3DSBrowserAcceptheader – the MIME types accepted
3DSBrowserUserAgentHeader – User agent

RAVEN checks to see if 3DS may be invoked. This requires that the card is either enrolled or that it may be enrolled on the fly, that the 3DS system is available and that your merchant ID is participating in 3DS (configured by Raven).

If 3-D Secure may not be invoked, Raven will immediately make an approval request just as if no 3DS processing had been requested. The 3DSResponse code will indicate the reason why 3-D Secure could not be invoked.
If 3DS is available, RAVEN does not proceed with authorization, but instead populates the payment response with the URL of the issuing bank’s Access Control Server (ACS) in the 3DSACSURL field, as well as a payer authentication request (PAReq) in the 3DSPAReq field.

Raven then returns a normal Raven response. If 3-D Secure processing can proceed, the payment will have a status of Pending3DS and the 3DSResponseCode will have a value of Attempted. The response values will include the 3DSACSURL and the the 3DSPAReq fields with the values needed for step 2. If 3-D Secure processing is not possible, the payment will have a status of Approved or one of the standard payment processing status’s indicating a declined transaction.

3DS Specific Request and Response 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	Flag indicating whether or not 3DS should be attempted for this transaction.
3DSMerchantURL	T	1024	Req	C¹	The merchant’s website URL to which control should be passed in step 2.
3DSDeviceCategoryCode	OneOf		Req	C¹	Indicates the type of device used to perform the 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.
3DSResponseCode	OneOf		Res	C¹	Indicates the outcome of the 3DS authorization not_attempted – initial status, also status of all payments where 3DS is not requested. attempted – interim status after returning the ACS URL. passed – user was authenticated and the 3DS guarantees apply. failed – the user was not authenticated by the ACS. The payment will be marked as declined. unavailable – 3DS could not be invoked, no 3DS guarantee applies. merchant_not_participating - 3DS could not be invoked, no 3DS guarantee applies. scheme_not_participating - 3DS could not be invoked, no 3DS guarantee applies. abandoned – any 3DS payment not completed within 24 hours will be voided and marked as abandoned. No approval attempt will have taken place.
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 RAVEN for the original request.

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

² These fields are mandatory when re-submitting an authorization request as described in Step 3 below.

Step 2: Authentication

If 3-D Secure may be invoked (payment status code Pending3DS), the payment authentication request (PAReq) returned by Raven in step 1 must be submitted to the Access Control System through the cardholder’s browser/device using an <iframe> HTML element. The 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 use POST method and contain the following elements:

Element	Name	Content
Target	acsframe	Value of 3DSACSURL from RAVEN’s response in Step 1.
Hidden field	PaReq	Value of 3DSPAReq from RAVEN’s response in Step 1.
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 of code that could be used to present the ACS frame to the customer:

<form name="acsform" method="post" target="acsframe" action="{Value of 3DSACSURL from Raven's response}">

document.acsform.submit();

</script>

</form>

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. 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 URL you supplied in the TermURL hidden field.

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 3: Approval

Once the ACS has returned control to your server, you must then use the reference number you supplied to the ACS in the MD field and that was echoed back by the ACS in the MD field to fetch your record of the original transaction and resubmit the authorization request to RAVEN. The resubmitted authorization request must have 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 1.

In processing the resubmitted authorization request, RAVEN will verify the ACS signature on the PARes and parse the response. If the response is not valid, the 3DSResponse code will be set to Failed and the payment will be declined . If the response is valid, the 3DSResponseCode will be set to Passed. If the 3DS system is not available the 3DSRespsonse code will be set to Unavailable.

In both the case of 3DSResposneCode Passed and Unavailable, an approval request will be made, the result of which will be returned just as in the non 3-D Secure case, using the response field named ‘Status’.

This follow-up transaction must be submitted to:
https://raven.deepcovelabs.com/realtime/complete
This request type is used to submit a follow-up payment request to RAVEN after customer-completed authentication with ACS.

Field Names	Type	Max. Size	Req/Rsp	O/C/M	Remarks
RAPIVersion	N	10	Req	M	Must be 2.
UserName	AN	50	Req	M	UserName, as assigned.
Timestamp	Timestamp	50	Req	M	Time at which the message was sent.
RequestID	AN	50	Req	M	Any value unique for the UserName. A username may never submit the same RequestID twice. This can be implemented using a UUI, GUID or even the machine name followed by a microsecond timestamp.
PaymentRoutingNumber	N	6	Req	M	The six digit payment routing number assigned to you.
PaymentType	T	25	Req	M	Please see this page.
Amount	N	10	Req	M	Please see this page.
CurrencyCode	A	3	Req	M	Please see this page.
Signature	N	40	Req	M	SHA1 HMAC of the following values concatenated: UserName TimeStamp RequestID PaymentType Amount CurrencyCode
TrackingNumber	N	10	Req	M	The tracking number that was received from RAVEN for the original request.
3DSPARes	T	4096	Req	M	The Payer Authentication Response (PARes) that was received from the ACS. Note: this value must be URL-encoded to be transferred correctly.
RequestResult	AN		Rsp	M	Will be OK in normal cases, other wise will be an error code as described in the table of HTTP status codes below.

Clean-up

Any payments that remain in status ThreedPending for over 24 hours will be marked as Void and the 3DSResponseCode will be set to abandoned.