Skip to Navigation | Skip to Content

3DS Card Processing

This section will be of interest to those wanting to submit 3-D Secure authenticated credit card authorizations 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 (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.

3-D Secure Interaction

3-D Secure verification requires a three step interaction:

  1. Your server must first contact Raven indicating 3-D Secure is requested and providing several 3-D Secure parameters. Raven will then check with the issuing back to determine if 3-D Secure is available. If so Raven will return with a URL to which your customer should be directed to authenticate themselves. If 3DS is not available Raven will perform a approval request to which the 3-D Secure guarantees will not apply.
  2. You must direct your customer to the URL of the issuing banks Access Control System (ACS) where the customer can authenticate themselves.
  3. The issuing back will return an authentication response to you, you must then contact Raven with the authentication response from the issuing back. Raven will verify the response and if it is valid 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. Again if the 3DS system is not available and the response cannot be verified Raven will perform an approval request to which teh 3-D sEcure guarantees do not apply.

Only if the 3DSResponseCode returned by Raven  is Passed has the transaction been completed 3-D Secure authentication and only in that case 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

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 3DS may be invoked. This requires the card be  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.

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

Raven then returns a normal Raven response. If 3-D Secure processing can proceed the payment will have a status of 3DSecurePending and the 3DSResponseCode will have a value of Approved. 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 various 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 C1 The URL of the merchant’s website.
3DSDeviceCategoryCode OneOf Req C1 Indicates the type of device used to perform the transaction:

  • mobile
  • desktop
3DSBrowserAcceptHeader T 4096 Req C1 The MIME types accepted by this device, as defined in the accept header.
3DSBrowserUserAgentHeader T 4096 Req C1 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 C1 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 C2 The Payer Authentication Response (PARes) that was received from the ACS.
TrackingNumber N 10 Req C2 The tracking number that was received from RAVEN for the original request.

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

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

Step 2

If 3-D Secure may be invoked, payment status code ThreedPending the PAReq must be submitted to the Access Control System 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 use POST method and 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 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}">

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

 

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

Once the ACS has returned control to you, 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 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 1. RAVEN will verify the ACS signature on the PARes and parses the response. If the response is not valid the 3DSResponse code will be set to Failed and the payment will be declined . If it is valid it 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.

This his 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.

Card Payments