3D Secure Auth (3DS Version 2)

Overview

3D Secure enables the consumers to enter a password to confirm their identity with the card issuer. If accepted, the consumer can then complete their order and once received by the merchant, the merchant has more confidence that the transaction is genuine and not fraud.

The 3D Secure protocol was developed by Visa to improve the security of Internet payments. The protocol is offered with the service name Verified by Visa. MasterCard has also adapted a similar protocol called MasterCard SecureCode. Both are designed to allow authentication of cardholders by their Issuers at participating merchants.

This section is only required when you initially request content using our Sale API as our Hosted Payments Page API handles the 3D Secure for you. If the card being used is 3D Secure, the response will return 3D Secure data that must be used while catering for 3D Secure. This information will be used in numerous steps to ensure completion of the 3D Secure process, the 3D Secure catering process is explained in-depth below.

3D Secure Process

The process of 3D Secure is real simple and straight forward. Below demonstrates the steps required in order to successfully cater for 3D Secure.

  1. Sale request returns with 0000 inside the <R1> field which indicates you must cater for 3D Secure as failure will decline the transaction.
  2. Using data returned in Sale response, you must now construct a HTML Form containing the mentioned information and have the form automatically submit on page load.
  3. This form will submit the data and load the required 3D Secure page where the consumer must enter their unique secure code and submit in order to authenticate themselves.
  4. The form will then redirect the consumer to your TermURL where the merchant will have their 3D Secure Confirm API setup to confirm that the consumer has passed authentication.
  5. The response from the 3D Secure Confirm API within your TermURL will respond with the usual error code / description result that would normally determine a successful or declined transaction. The result may also be sent to your notification handler if setup to do so. Please read the Sale documentation about the potential error code & descriptions that are available.

Catering 3D Secure

When a card is 3D secure, you must load a form inside an iFrame which will be the 3D Secure handler. You must construct the form with the required values outlined below which must be automatically submitted to the authenticator URL inserted in the form's action attribute.

You must construct the form, populated with the values received in the Sale Response.

Sample 3D Secure Form: 
<!-- Fill Values From The Sale Response -->
<!DOCTYPE html>
<html>
    <head>
        <meta charset="UTF-8">
        <title></title>
    </head>
    
    <body onload="document.frmLaunch.submit();">
        <form name="stepUpForm" method="post" action="https://staging.ecomm365.com/SecureCustomerAuthentication/API/StepUP">
            <input type="hidden" name="ReturnUrl" value="{ merchant's Handler URL }" />
            <input type="hidden" name="Payload" value="{ value from field R4 in sales response }" />
            <input type="hidden" name="CardinalTransactionId" value="{ value from field R7 in sales response }" />
            <input type="hidden" name="ReferenceID" value="{ value from field R6 in sales response }" />
            <input type="hidden" name="MD" value="{ value from field R5 in sales response }" />
            <input type="hidden" name="ACSUrl" value="{ value from field R3 in sales response }" />
            <input type="hidden" name="VendorId" value="{ merchant's VID }" />
        </form>
    </body>
</html>

If the entered card is 3D Secure and the sale request is successful, the <R1> field inside the XML document will contain 0000 as the error code. The following information will also be made available:

  • ReturnURL: The Merchant’s Handler URL
  • VendorId: The merchant’s VID
  • ACSUrl: R3 from the Sale response
  • Payload: R4 from the Sale response
  • MD: R5 from the Sale response
  • ReferenceID: R6 from the Sale response
  • CardinalTransactionId: R7 from the Sale response

The PaRes will be returned to the TermURL page. The PaRes value returned should then be passed into the <R1> field of the 3D Secure Confirm request.

Expected 3D Secure Response

As stated above, if your <R1> within the sale response is 0000 and contains the other 3D Secure parameters listed above, you must then cater for 3D Secure. Below demonstrates a sale response that indicates the card is 3D Secure. 

<!-- Sample XML Document If The Card Is 3D Secure -->
<?xml version="1.0"?>
<R>
  <R1>0000</r1>
  <R2>Successful</r2>
  <R3>https://3DSecureSite.com/Page.aspx</R3>
  <R4>eNpVUttSwjAQfc9XMDw7pGkLArNmBkVGdMBSvIynnV0lSNOStgz8vUnLRd/2nL3k7NnAy8ogjpcoK4McZlgU4htbKrlph+ywSxYTX+6D3tviWT+tPrw2h2gU45bDplwhMs1Zx+v4QE+Q2BFGroQuOQi5vZ3OOfODsNu77gM9EgRSNNPxn0SDCWiRIo8M5kIlrYnSQkslNq0lmp2SCLTOE5BZpUtz4P3QA3oCBCqz4auyzIeU5s2Mr9OIoplQdGSWAnWFBOhFaVS5qLAG7FXC5+NJN0njOF4/rnE88982k+jzp8zeX0Y3QF0FgUSUyH2P9b2B320xNgyDYbcHtOYJiNSp4vevMfOuPKvySBDI3VOjBjHPpf4ydrfKGNTywAfOmDMigPs802hrrNvn2G5x0X734DyXpbM2CMKBz5zlNa7blXWJ9VnTr2rLqOuhx5PS4/Vt9O9X/AIlllLC</R4>
  <R5>0003938b-f26d-45a5-98c6-l99c08e81230</R5>
  <R6>152D500P-8559-4FFF-B412-FFD255C09C56</R6>
  <R7>hrETn5Lu6UxoZry2VUJ1</R7>
</R>