3D Secure

3D Secure is an XML-based protocol designed to be an additional security layer for online credit and debit card transactions. It adds an authentication step for online payments, directly integrated to the card brands and bank servers. That means, whenever the card brands or a bank approve a sale from happening through 3DSecure, the liability and risk is shifted from the merchant to the bank. Given these circumstances, it prevents chargebacks from happening since the card brands and banks will actually be responsible for the transaction approval.

While most of the US based cards are enrolled to the 3DS, there are cards are not enrolled to it, and consequently, this service is only possible when the credit card and issuing bank participate on the program.

Frictionless mode 3DS

Frictionless mode is a trade-off: you opt for better user experience while having a lower success ratio on 3DS. If compared to Strict mode, Frictionless mode is less secure, since for all the cases when the issuing bank and credit card bank ask for additional information, the process will fail. From a technical perspective, you improve user’s experience by not sending them to a different website, since all the process happens within a hidden iframe on your website.

From our data, using this method reduces churn. In terms of success ratio, what we’ve seen is that frictionless 3DS works 30-70% of the times based off your customer base and business variables.

Authorization

Authorization process for our 3DS API consists in generating a hex-digested SHA256 signature, using four main variables:

• Your API Key;
• The fully qualified URL you’re trying to reach on the API;
• JSON dumped data you’re posting for that request, with keys ordered alphabetically;
• Your API Secret.
  
  

Let’s say you’re trying to reach the endpoint /hello on a http://example.com base url and you want to send the following data:

{
  "name": "John Doe",
  "card": "4111111111111111",
  "state": "California",
  "city": "San Francisco"
}

The first thing that you would have to do is sorting the json keys alphabetically:

{
  "card": "4111111111111111",
  "city": "San Francisco",
  "name": "John Doe",
  "state": "California"
}

Then, strip all the empty spaces from that string:

{"card":"4111111111111111","city":"San Francisco","name":"John Doe","state":"California"}

And then, signing it like this:

API_KEY='my-api-key'
URL='http://example.com/hello'
DATA='{"card":"4111111111111111","city":"San Francisco","name":"John Doe","state":"California"}'
SECRET='no-one-knows'

# It would look like this:
# my-api-keyhttp://example.com/hello{"card":"4111111111111111","city":"San Francisco","name":"John Doe","state":"California"}no-one-knows
SIGNATURE=$API_KEY$URL$DATA$SECRET
echo $SIGNATURE

# Digest/sign it!
# Should look like this: e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855
echo -n $SIGNATURE | openssl dgst -sha256

That signature and your API Key should be passed on all requests in the following request headers:

Check card enrollment

At the moment, we only support 3DS for VISA and MasterCard cards. Still, not all of the cards and issuing banks participate to the 3DS program. So, in order to know if a card is participating or not, you should make the first request which is to get enrollment status for a specific credit card.

HTTP Request

POST https://mpi.3dsintegrator.com/index.php/enrolled-status

Request Fields

Sample request

curl -v -X POST -H 'Content-Type: application/json' \
  -H 'x-mpi-api-key: YOUR_API_KEY' \
  -H 'x-mpi-signature: 1b742fab984f86b141991917c71c99b81109078e4874ce1c9fb925a038af0386' \
  -d '{"pan":"4111111111111111"}' \
  "https://mpi.3dsintegrator.com/index.php/enrolled-status"

The above command returns JSON structured like this:

{"enrollment_status":"N"}

Responses

Based off your business nature and your own preferences you can block a transaction from happening or just let it proceed without 3DS protection. If you want to proceed without 3DS protection, just send over the transaction data to your gateway of choice; otherwise, if you want to block a transaction from happening, you can just send the customer back to the credit card details screen and ask him to try another card. At this point, our implementation is very permissive. It’s up to the merchants to choose what makes sense to them, on their business context. We usually recommend the permissive approach as getting too strict would result in loss of sales.

Payment Authentication Request

Whenever you get a enrollment_status = Y from the previous step, you’re ready to start the Payment Authentication Request. This step basically consists in exchanging the credit card data, and unique ids to your application with the API to get URLs and a token which will run the 3DSecure redirects under your mode of choice. A very important fragment of data that you will be passing at this request is also the return_url. This is the endpoint that you will receive on the next steps, a POST containing the final response for the 3DS process.

HTTP Request

POST https://mpi.3dsintegrator.com/index.php/auth-request

Request Fields

Sample request

curl -v -X POST -H 'Content-Type: application/json' \
  -H 'x-mpi-api-key: YOUR_API_KEY' \
  -H 'x-mpi-signature: 16851d38cdc413e3481fedc17b03fb080eaf45a1ab20a4e6b9c7c2bb93a72799' \
  -d '{"amount":2,"card_exp_month":"12","card_exp_year":"20","message_id":"0001","pan":"4111111111111111","return_url":"https://localhost/3ds/callback","transaction_id":"0001"}' \
  "https://mpi.3dsintegrator.com/index.php/auth-request"

The above command returns JSON structured like this:

{
  "AcsUrl": "https://mpi.3dsintegrator.com/demoacs/",
  "PaReq": "eJx1kduOgkAMhl/FmL2mHJWQ2oRFE7nQGOV+M4FGSJaDA4i==",
  "TermUrl": "https://localhost/3ds/callback",
  "MD": "0001"
}

Responses

After having the PaReq token, you have to make a choice in regards to which 3DS flavor you will be using: strict or frictionless. For strict, your user will be forwarded to VISA or MasterCard confirmation page. For frictionless, the process will happen inside your own system, inside an iframe, with a supporting endpoint, but you will have a lower approval rate.

Payment Authentication Response

Once you have the PaRes token, you are then ready to finish the 3D Secure authentication and make a decision of wether you will let this transaction pass or not. At this point, you will be doing a request to one last endpoint, with your PaRes data and the card authentication details provided on the Payment Authorization Request step, so the card brands and issuing banks can gather the information they need to provide a verdict and prevent that transaction from charging back.

HTTP Request

POST https://mpi.3dsintegrator.com/index.php/auth-response

Request Fields

Sample request

curl -v -X POST -H 'Content-Type: application/json' \
  -H 'x-mpi-api-key: YOUR_API_KEY' \
  -H 'x-mpi-signature: c2cc490e0d1c34f4498f14159230b69af396ff56d6509bdcbba26cbf43179f5e' \
  -d '{"amount":2,"card_exp_month":"12","card_exp_year":"2020","message_id":"0001","pan":"4111111111111111","pares":"PARES","return_url":"https://localhost/3ds/callback","transaction_id":"0001"}' \
  "https://mpi.3dsintegrator.com/index.php/auth-response"

The above command returns JSON structured like this:

{
  "pares":"eJzNWdnO4siSf...[REDACTED for readability purposes]...HlhAAAAAAA=",
  "success":true,
  "id":" 0001",
  "status":"Y",
  "time":"20170929 09:35:08",
  "cavv":"AAACACZ5YQAAABlwJHlhAAAAAAA=",
  "xid":"ICAgICAgICAgICAgICAgIDAwMDE=",
  "cavv_algorithm":"2",
  "eci":"05",
  "error":""
}

Responses

Based off the response you get above, you know if the liability of this transaction has been shifted to the issuing card or bank. In order to understand if that happened, you need to take under consideration the fields status and eci even though our API responds with a success field. the success field just means that the request was successful, not that the liability was shifted.

Statuses

Liability

As stated before, the business decisions on processing a transaction that had a failed 3DS attempt or liability not shifted or not is totally yours. Our 3DS process was built in a way that you, the merchant, can choose what makes more sense to your business. 3DS protection is only one of the products we offer to fight chargebacks, so if you want full protection, we recommend taking a look also on our Fraud Portal, Alerts API, Chargeback Representment and our Kount checks in order to have more data to drive you on a decision of blocking a transaction or not. In these cases, the more data you have, the more power you have to make an assertive decision.

Javascript SDK

This SDK is the simplest way to integrate risk based authentication to your online shop cart.

Installation

This is the front-end implementation of the SDK. Below is the instructions for leveling up your form to use 3D Secure.

1. Add the javascript

Include the following code on the billing page (where you get the credit card information) before closing the tag </body>.

<script src="https://js.paycertify.com/3ds.js"></script>

2. Initialize the ThreeDS library

The following code will start the library with the checkout form including the credit card data (first parameter) and the server side integration url (second parameter). You can also add some options to customize the integration.

<script>
var threeDS = new PayCertify.ThreeDS('payment-form', 'http://example.com/3ds/check_enrollment', { timeout: 5000 })
    threeDS.init();
</script>

You can use the following options to make 3DS integration fits better your checkout form:

3. Describe your inputs

To work properly, you should describe your inputs from checkout form to be sent to the server. You should add to some inputs the attribute data-threeds with the type of information the input contains. As you see on the following table:

You can use as the following example:

<form class="" action="index.html" method="post" id="payment-form">
  <!-- your checkout fields ... -->
  <input type="text" name="name" />
  <input type="text" name="address" />
  <!-- 3DS fields ... -->
  <input type="hidden" name="transaction_id" data-threeds="id" />
  <input type="text" name="card_number" data-threeds="cc-num" />
  <input type="text" name="card_expiration_month" data-threeds="cc-month" />
  <input type="text" name="card_expiration_year" data-threeds="cc-year" />
  <input type="text" name="transaction_amount" data-threeds="transaction-amount" />
</form>

4. Execute 3DS integration on server-side

On your server side, you should have an endpoint waiting for the 3DS information to check card enrollment. The Javascript SDK will be waiting for a JSON in the following format:

{
  "AcsUrl": "https://mpi.3dsintegrator.com/demoacs/",
  "PaReq": "eJx1kduOgkAMhl/FmL2mHJWQ2oRFE7nQGOV+M4FGSJaDA4i==",
  "TermUrl": "https://example.com/3ds/callback",
  "MD": "0001"
}

Then, you should receive the callback with the 3DS response (TermUrl from JSON response) in order to get the 3DS Authorization. The Javascript will be waiting for an JSON response as following:

{
  "pares":"eJzNWdnO4siSf...[REDACTED for readability purposes]...HlhAAAAAAA=",
  "cavv":"AAACACZ5YQAAABlwJHlhAAAAAAA=",
  "xid":"ICAgICAgICAgICAgICAgIDAwMDE=",
  "cavv_algorithm":"2",
  "eci":"05",
  "error":""
}

5. Sending the form

After all these steps, 3DS data was now added to your form and it will continue the natural form submitting flow to your checkout route. The following fields were added to your form and can be used to forward 3DS Data to your gateway.

Forwarding 3DS data

After you get the Payment Authentication Response, you should forward specific parameters to our gateway so the transaction can finally be protected.