3-D Secure v1

What is 3-D Secure?

3-D Secure is a security protocol framework developed by EMVCo. EMVCo is owned by the major card schemes - Visa, MasterCard, American Express, Discover, JCB and Union Pay - designed to reduce the risk of fraudulent Card Not Present (CNP) payment transactions on the Internet.

To authenticate cardholders, individuals must log onto their own bank's website (ACS) before each online transaction. This pushes transaction liability away from you - the merchant - and towards the cardholder.

It's there to make sure your customer is actually who they say they are by performing an online check.

Configuration

If you wish to avail the 3-D Secure solution and incorporate the process into your transactional processing, please contact the Support Team. Once configured, you will receive a confirmation email.

When to Use 3-D Secure

When a customer uses 3-D Secure to successfully authenticate a payment, the card issuer assumes full responsibility. As such, you’re covered by a liability shift against fraudulent payments that have been authenticated with 3-D Secure.

Although 3-D Secure protects you from fraud, it requires your customers to complete additional steps during the payment process that could impact their checkout experience. For example, if a customer does not know their 3D Secure information, they might not be able to complete the payment.

When considering the use of 3-D Secure, you might find the right balance is to use it only in situations where there is an increased risk of fraud, if the customer’s card would be declined without it, or alternately when you take recurring payments you can use 3-D Secure as the original payment source for recurring payments.

The Flow

The 3-D Secure process involves a number of steps which we’ve summarised below. We’re presuming here that you only wish to accept transactions that provide dispute protection.

1. Verify if the cardholders card is enrolled in 3-D Secure (Enquire). If the card is enrolled, depending on your account configuration, we then send the transaction to the acquiring bank for authorisation. Authorisation is just a fancy payment term which means the transaction is now going to the banking network to collect your money - exciting, right?
2. If the card is enrolled, you will have to redirect the cardholder to their bank's Access Control Server (ACS) to enter their password.
3. Once this is completed, you take the response values from the ACS and send them to us to be verified, decoded and then sent onto your acquiring bank for authorisation.

Enquire

Request

The first stage in the 3-D Secure process is verifying whether the card is enrolled or not. To do this, the card data is sent to Acquired.com in the AUTH_ONLY or AUTH_CAPTURE transaction request. Depending on the card type, we will query the appropriate Enrolment Server and return the outcome.

When we say enrolled, we just perform a check against the card to see if the cardholder has been registered for 3-D Secure. Don't worry, this is rare, after three online transactions have been processed against the card, issuers force the customer to be enrolled.

Please see below an example of the bit of JSON you should add to your Authorisation request:

"tds": {
    "action": "ENQUIRE"
},

Parameters

When using 3-D Secure, there are certain mandatory fields which must be passed in the request. These are special parameters. They let us know that you want to use 3-D Secure - sort of like texting your friends when you're outside their house instead of ringing the doorbell.

The table below describes the required parameters to be used in the ENQUIRE transaction request. These values are to be processed in addition to the standard transaction parameters as detailed within the API guide when the transaction_type=AUTH_ONLY or AUTH_CAPTURE.

Response

If your customer is not yet enrolled for 3-D Secure, we'll send it straight on for authorisation (there is still a liability shift) and respond in the normal way. If they are enrolled (most likely scenario), we will return a 501 response code so you can get started on the next step.

Heres an example of the additional tds object returned for an Authorisation request where your customer is enrolled.

"tds":{
    "pareq":"eJxVkd1SgzAQhe99CoZ7m5+mCXS26dQ6js6o49jqPYSloAJtAG3f3qRSq1ztx+6e3ZyF+b76CD7Rt......",
    "url":"https://www.securesuite.com/bank/tdsecure/opt_in_dispatcher.jsp?partner=bank.visa&VAA=B",
    "enrolled":"Y"
},

Parameters

The table below describes the additional parameters returned in the Authorisation response. These values are returned in addition to those returned in a normal API response.

Enrolled Parameter

Remember the enrolled piece above, here we give you a description of the possible values returned when you ENQUIRE whether or not your customer is enrolled.

• "enrolled":"Y" - The card is enrolled for 3-D Secure. Proceed to the Authentication.
• "enrolled":"N" - We have on your behalf, either blocked the transaction from progessing or sent the transaction to authorisation. Check the response code parameter, this will give you all the info you require.
• "enrolled":"U / Blank" - We have been unable to verify the enrollment, transaction must then be declined.

Authentication

Request

The second stage of the 3-D Secure process is Authentication. If you've reached this stage, it means your customer is enrolled with the relevant card scheme. Within the ENQUIRE response, you would have received two key values:

1. url: the URL address of the issuing bank's ACS page. Should be set as form action in a POST to the ACS.
2. pareq: stands for Payer Authentication Request. This value is required to initiate the authentication.

Once you have these values, your customer can now be redirected to the ACS URL to enter in their password. This can be achieved with a full page redirect or by loading the ACS page within an i-Frame.

Please see below a simple redirect script as an example - because we are that kind.

<!DOCTYPE html>
    <html>
    <head>
        <title>3-D Secure – ACS Redirect</title>
        <script type=”text/javascript”>
            function OnLoadEvent() {
                document.form.submit();
            }
            </script>
    </head>
    <body onload=”OnLoadEvent()”>
        <form action=”https://qaacs.acquired.com/” method=”POST”>
            <input type=”hidden” name=”PaReq” value=”eJxVkd1SgzAQhe99CoZ7m5+mCXS26dQ6js6o49jqPYSloAJtAG3f3qRSq1ztx+6e3ZyF+b76CD7Rt......”>
            <input type=”hidden” name=”TermUrl” value=”https://www.yourwebsite.com/termurl”>
            <input type=”hidden” name=”MD” value=”434irjfewiofk………”>
            <noscript>
                <input type=”submit”/>
            </noscript>
        </form>
    </body>
    </html>

The PaReq, MD and TermUrl fields must be sent to the ACS in order to initiate the authentication. The URL parameter should be used as the value for the form action.

Parameters

Response

Once your customer has complete the authentication, the ACS will perform a form POST to the TermUrl you specified within the request.

Parameters

Settlement

The final step for a 3-D Secure transaction. Congratulations, you have made it.

The issuing banks ACS has already returned the PaRes value which contained the encoded confirmation of the customer's authentication status. This value can now be sent to Acquired.com in the SETTLEMENT request. Don't worry, we decode the PaRes value to determine if the authentication is genuine. If it passes our check, we pass this on to your acquiring bank for authorisation.

Please see below an example of the SETTLEMENT request:

{
    "timestamp":"20170612200254",
    "company_id":"133 ",
    "company_mid_id":"",
    "company_pass":"password",
    "request_hash":"km78ks767db39gne012e1960s...",
    "transaction":{
        "merchant_order_id":"20170612200234",
        "transaction_type":"AUTH_ONLY",
        "original_transaction_id":"1234567",
        "amount":"100",
        "currency_code_iso3":"GBP"
    },
    "tds":{
        "action":"SETTLEMENT",
        "pares":"3290uif32ijf…………"
    }
}

Parameters

The table below describes the required parameters to be used in the SETTLEMENT transaction request. These values are to be processed in addition to the standard authorisation parameters as detailed within the API guide for AUTH_ONLY or AUTH_CAPTURE.

Settlement Request Hash

To process the SETTLEMENT request, you will need to generate a request hash. We generate one, you generate one, and if they match when we receive your transaction then everyone knows it’s legit.

Only the following parameters need to be included in your request hash calculation (in this exact order): timestamp + transaction_type + company_id + merchant_order_id + company_hashcode.

Here’s how to calculate the correct value:

• First concatenate the above request parameters with your company_hashcode.
• Then SHA256 encrypt the resulting string.

Here's an example:

timestamp . transaction_type . company_id . merchant_order_id . company_hashcode
                       //20220707181641AUTH_CAPTURE615ORD0167345dFQkmElx
                             

Response

We will send back some additional parameters in the Authorisation response to let you know to outcomes of the authentication, please see below:

"tds":{
    "status":"Y",
    "eci":"5"
},

Parameters

The table below describes the parameters returned in the SETTLEMENT response message. These values are returned in addition to those within the API / HPP guide.

Parameter	Format	Length	Description
tds	object
status	string	1	This is where you find the outcome of the authentication. The possible values you will find are: Y: Cardholder has been successfully authenticated. A: Cardholder is enrolled and the bank has acknowledged the attempted authentication. N: Cardholder did not authenticate successfully (the password entered was incorrect). If you choose to authorise this transaction, you will be liable for a dispute. U: Cardholder’s authentication is currently unavailable.
eci	int	1	The e-commerce indicator.