Implementing 3D Secure

This document describes how to enable 3D secure.

Enrollment Request

If you decide you want to enable 3D Secure on your transaction, the first step to take is to ensure that the operation
is supported for a specific card. This is done by sending an ‘Enrollment Request’.

An Enrollment Request by sending an http POST request to <api_base>/v1/3d/enroll with at least the following parameters:

  • account – The account id that was provided to you. Make sure you use the account with the correct currency.
  • amount – The amount is charged without a decimal place e.g. $1.5 = 150.
  • card – The card token that was submitted to you using the payment form.
  • description – An optional description.
  • xid – A number consisting of 20 digits. This has to be unique for each particular request

Example:

{
    "account": "54884a22e1e6573d1d1ee001", 
    "amount": 1250, 
    "card": "56cc88eb6b5c560672612df0", 
    "description": "Test transaction",   
    "xid": 12345678901234567890
}

This request will return a pareq and an url if the card is 3D enrolled.

Payer Authentication

The next step is sending the customer to the page where she can verify her identity. Unfortunatly, because this requires a POST request, you cannot simply redirect the customer using a HTTP redirect.

The recommended way to solve this is to present the user with a form that submits automatically. Here is an example:

<html>
    <head>
      <meta HTTP-EQUIV="Content-Type" content="text/html;charset=UTF-8">
      <meta HTTP-EQUIV="Cache-Control" CONTENT="no cache">
      <meta HTTP-EQUIV="Pragma" CONTENT="no cache">
      <meta HTTP-EQUIV="Expires" CONTENT="0">
    </head>
    <body OnLoad="AutoSubmitForm();">
      <p>Your are being redirected to a secure environment...</p>
      <form name="downloadForm" action="**URL**" method="POST">
          <input type="hidden" name="PaReq" value="**pareq**">
          <input type="hidden" name="TermUrl" value="**http://example.com/foo?mytag=abc">
          <input type="hidden" name="MD" value="**Example Description**">
          <script type="text/javascript">
              function AutoSubmitForm() { document.downloadForm.submit(); }
          </script>
          <input type="submit" name="continue" value="Continue">
      </form>
    </body>
</html>

There are four values that need to be filled in:

  • form action – This needs to be the ‘url’ parameter you got back from your enrollment request.
  • PaReq – This needs to be the ‘pareq’ parameter you got back from your enrollment request.
  • TermUrl – The url to which the customer is sent after the 3D secure credentials where inserted succesfully.
  • MD – Merchant Descriptor. A reference that can be used to track the request. This is POSTed unmodified to the url
    that was specified as TermUrl.

After the customer succesfully entered the 3D secure credentials, the 3D secure servers will make an http POST request to the url you
specified at TermUrl in the form. This will contain the following values:

  • MD – The unmodified Merchant Descriptor that you will have specified in your form
  • PaRes – The Payer Authorization Result. A base64-encoded string that is used in the Authorization Request.
Note: Although the PaReq and PaRes values are base64 encoded, you will not have to decode them

Authorization Request

An Authorization Request is made by posting your account id and the unmodified pares
to <api_base>/v1/3d/authorization.

{
    "account": "54884a22e1e6573d1d1ee001", 
    "pares": "eJytWFmTosq2fjfC/9BR59...g=="
}

If all is well, you will receive

{
    "code": 0,
    "status": "Y",
    "cavv2": "AAABCAiZZGOQAAAANJlkAAAAAAA=", 
    "eci": "05"
}

The cavv2 and eci values can be used with the Create Transaction operation.