Skip to main content

3D Secure

3DS2 (3D Secure version 2) is a multi-factor authentication protocol aimed at improving the user experience for authentication with more frictionless flows across different devices. The protocol is for card not present e-commerce transactions only.

PSD2 is a European regulation designed to improve customer authentication and to make payments in Europe more secure. PSD2 introduces SCA (Strong Customer Authentication) as a definition of how payments must be authenticated in Europe, and 3DS2 is one of the solutions available to achieve SCA.

info

More information on 3D Secure 2 can be found at https://www.emvco.com/emv-technologies/3d-secure/

This section describes how to implement requests where 3D Secure processing is to be performed by the Payen platform. Alternatively you may wish to pre authenticate using your own third party 3DS service provider and supply the 3DS data to the platform. If this is the case see 3D Secure By Third Party Provider.

The platform can be configured to perform 3D Secure authentication. When an attempted payment authorisation (see section Authorisation) is made the Payen Platform will determine if the passed payment details require 3D Secure authentication. If they do, a response of PENDING along with the appropriate “3D Secure required” reason code will be returned. In addition, the threeDSecureStatus in the paymentAttempt will be PENDING and all appropriate additional 3D Secure fields will be set. See Payment Response for details of these fields.

With 3D Secure version 2 the merchant will need to provide more details about the card holder’s browser on the Auth request. The details should be sent in the emvco3ds element as described in Authorisation section.

If the merchant’s account requires 3D Secure authentication, then all transactions sent to that account must have a valid emvco3ds element, as described in Authorisation section. If the merchant’s account has not been configured to perform 3D Secure authentication, then the emvco3ds element can be omitted. If, however, it is present, it will be ignored.

In addition to the information required in the emvco3ds element, it is also recommended that the card holder’s browser IPAddress is provided in paymentInfo.ipAddress element.

Authorisation Request (3D Secure Required)​

Authorisation Request (3D Secure Required)
{
   "version": 2,
   "deferredCapture": false,
   "transaction": {
      "amount": 3000,
      "currency": 826,
      "merchantRef": "rJK1jKuuuzr9zMiPLn6e",
      "transactionType": "ECOMMERCE"
   },
   "paymentMethodType": "CARD",
   "merchant": {
      "merchantId": 1000002,
      "accountId": 2000053
   },
   "card": {
      "cardNumber": "4111111111111111",
      "securityCode": "123",
      "expiryDate": "062022"
   },
   "customer": {
      "customerId": "new1",
      "email": "[email protected]",
      "firstName": "Test",
      "surname": "Client",
      "dateOfBirth": "03041970",
      "address": {
         "houseNameNumber": "123",
         "addressLine1": "The Street",
         "city": "Guildford",
         "province": "Surrey",
         "postcode": "GU2 2YD",
         "country": "GBR"
      },
      "mobileNumber": "01234123123"
   },
   "paymentInfo": {
      "ipAddress": "127.10.230.132"
   },
   "emvco3ds": {
      "browserDetails": {
         "acceptHeader": "text/html,application/xhtml+xml,application/xml;q=0.9,image/avif,image/webp,image/apng,*/*;q=0.8,application/signed-exchange;v=b3;q=0.9",
         "javaScriptEnabled": true,
         "javaEnabled": true,
         "language": "en",
         "screenHeight": 600,
         "screenWidth": 800,
         "timeDifference": "+300",
         "userAgent": "Mozilla/5.0 (X11; Linux x86_64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/86.0.4240.111 Safari/537.36",
         "colorDepth": 48,
         "challengeWindowSize": "01"
      }
   }
}

Authorisation Response (3D Secure Required)​

Authorisation Response - 3D Secure Required
{
   "version": 2,
   "type": "AUTH_CAP",
   "customerId": 1000,
   "merchant": {
      "merchantId": 1000003,
      "accountId": 2000034
   },
   "transaction": {
      "amount": 1000,
      "currency": "GBP",
      "merchantRef": "2sqKtxVOzXKRJFWttcLz",
      "gatewayRef": "3a1028c8-7ecd-413a-9a0e-7eadf62b425a",
      "transactionType": "ECOMMERCE"
   },
   "status": {
      "code": "PENDING",
      "message": "3-D Secure required",
      "reasons": {
         "reason": 502
      },
      "timestamp": "2014-05-20T09:13:17.000Z"
   },
   "paymentHistory": {
      "paymentAttempt": {
         "order": 1,
         "timestamp": "2014-05-20T09:13:17.000Z",
         "code": "PENDING",
         "amount": 1000,
         "currency": "GBP",
         "paymentMethodType": "CARD",
         "token": "49b13712421a43388a9424b0b0c68077",
         "cardResponse": {
            "startDate": "112011",
            "expiryDate": "112014",
            "cardHolderName": "test",
            "cardBin": "401200",
            "cardLastFour": "1112",
            "cvv": "NO_INFORMATION",
            "avsAddress": "NO_INFORMATION",
            "avsPostcode": "NO_INFORMATION",
            "threeDSecureStatus": "PENDING",
            "threeDSecureAcsUrl": "https://dropit.3dsecure.net:9443/PIT/ACS",
            "threeDSecureMd": "TURBd01EQXdNREF3TURBd01EQXdNREF3TURVPSwxMSwxNCw1LDEwMDAsR0JQMTAuMDAsOTk5Otk5LDk4NzY1NDMyMTExLDgyNiwyLDgyNixUZXN0TWVyY2hhbnQsaHR0cDovL3d3dy5tZXJjaGFudHVybC5jb20sMjAxNDA1MjAgMTA6MTM6MjIsSGlGVEV1RwtHalc3L29LU0c1d3JDdz09LDQwMTIwMOyKuTE2MzgzNDA1ZmEtMDBiMy00MWMzLWJhMTgtNTE2MjdiMzFkZmZjMTExMg==",
            "threeDSecurePaReq": "eJxtUdtu6kAM/BXEB8S7gXCTscStgCoqVDjqc7RYJW2TwCZp6N/Xm0s5lRopkmd2dtYe4/FsmZcHNoVlwh1nWfjKneg07QZdwv3sma+En2yzKE1Ie8rzEVoocmvOYZIThuY63z7RuPoQGogx2+2SxqPhIoj3fK01Qk1hEsZMR87y1gOhotCkRZLbLxr5A4QWYGE/6JznlwlAWZZe3FwS2jNpjODOEe797AtXZeJ3i060W87Kv/9/UwSnwFOYM/lK91Xgq45WE92b+DJrxWMYu0ZoPd9r5SklA9YEXtw7sxpo5U7+Z1BstZyYdpoWId8uacKikBd+aoR714uNy9TkEtUmejiuitX7+u1lCOnjYR2UdlFOpfFG4NwiCUn3Xb4NQHAW0CxQkqkWK9WvhX8DY1Op0g=="
         }
      }
   }
}

Redirect to 3D Secure​

On receiving a PENDING “3D Secure required” response from the Payen Platform the merchant is required to redirect the customer for 3D Secure authentication. This must be done in a browser by submitting a form with the appropriate parameters, see table below. The form action must be the value of the returned threeDSecureAcsUrl field from the payment authorisation response.

ParameterDescriptionRequired
MDThis is the threeDSecureMd field returned in the payment authorisation response.Yes
PaReqThis is the threeDSecurePaReq field returned in the payment authorisation response.Yes
TermUrlThis is the merchant URL that the 3D secure process will return on.Yes
info

TermUrl is restricted to a maximum length of 255 characters. The use of 3DS Version 1 MPI field names (MD, PaReq etc.) is to support existing and legacy integrations and to provide backward compatibility.

The form can either be submitted automatically using JavaScript (recommended) or contain a submit input that the user must click.

3D Secure Form Redirect
<form action="https://dropit.3dsecure.net:9443/PIT/ACS" method="POST">
    <input type="hidden" name="MD"
        value="TURBd01EQXdNREF3TURBd01EQXdNREF3TURVPSwxMSwxNCw1LDEwMDAsR0JQMTAuMDAsOTk5Otk5LDk4N
        zY1NDMyMTExLDgyNiwyLDgyNixUZXN0TWVyY2hhbnQsaHR0cDovL3d3dy5tZXJjaGFudHVybC5jb20sMjAxNDA1M
        jAgMTA6MTM6MjIsSGlGVEV1RwtHalc3L29LU0c1d3JDdz09LDQwMTIwMOyKuTE2MzgzNDA1ZmEtMDBiMy00MWMzL
        WJhMTgtNTE2MjdiMzFkZmZjMTExMg==" />
    <input type="hidden" name="PaReq"
        value="eJxtUdtu6kAM/BXEB8S7gXCTscStgCoqVDjqc7RYJW2TwCZp6N/Xm0s5lRopkmd2dtYe4/FsmZcH
        NoVlwh1nWfjKneg07QZdwv3sma+En2yzKE1Ie8rzEVoocmvOYZIThuY63z7RuPoQGogx2+2SxqPh
        Ioj3fK01Qk1hEsZMR87y1gOhotCkRZLbLxr5A4QWYGE/6JznlwlAWZZe3FwS2jNpjODOEe797AtX
        ZeJ3i060W87Kv/9/UwSnwFOYM/lK91Xgq45WE92b+DJrxWMYu0ZoPd9r5SklA9YEXtw7sxpo5U7+
        Z1BstZyYdpoWId8uacKikBd+aoR714uNy9TkEtUmejiuitX7+u1lCOnjYR2UdlFOpfFG4NwiCUn3
        Xb4NQHAW0CxQkqkWK9WvhX8DY1Op0g==" />
    <input type="hidden" name="TermUrl" value="http://www.merchant.url/returnFrom3D" />
</form>

All the values required in the form can be extracted from the authorisation response.

  • The action on the form is extracted from field threeDSecureAcsUrl
  • The MD value is extracted from field threeDSecureMd
  • The PaReq value is extracted from field threeDSecurePaReq
  • The term URL should be set to the URL you want to receive the response at
info

The response will contain values for "md" and "paRes" which need to be provided in the 3D Secure Complete message described below

3D Secure Complete​

Once the merchant has received the return from 3D Secure a further request must be made to the Payen Platform with the parameters received from the 3D Secure authentication attempt. It should be noted that without this request being made the transaction will not be completed, no customer funds have been ring-fenced prior to this stage. There is a timeout of 30 minutes from the time that the initial authorisation request was made, if the 3D Secure complete request is made after this period it will be REJECTED.

3D Secure Complete
{
   "version": 2,
   "merchant": {
      "merchantId": 1000003,
      "accountId": 2000034
   },
   "transaction": {
      "merchantRef": "2sqKtxVOzXKRJFWttcLz"
   },
   "threeDSecure": {
      "md": "TURBd01EQXdNREF3TURBd01EQXdNREF3TURVPSwxMSwxNCw1LDEwMDAsR0JQMTAuMDAsOTk5Otk5LDk4NzY1NDMyMTExLDgyNiwyLDgyNixUZXN0TWVyY2hhbnQsaHR0cDovL3d3dy5tZXJjaGFudHVybC5jb20sMjAxNDA1MjAgMTA6MTM6MjIsSGlGVEV1RwtHalc3L29LU0c1d3JDdz09LDQwMTIwMOyKuTE2MzgzNDA1ZmEtMDBiMy00MWMzLWJhMTgtNTE2MjdiMzFkZmZjMTExMg==",
      "paRes": "eJzFV2mzokoS/Ssd9300ulkElQ6uL4odlB0U/IaILLKILIX++ofa9/Z9PxcmemZiYogwpE5UzuWpPFmV0H8Orf6ljy5NWpWvL9g39OVLVIbVIS3j1xfXEb4uXv5c0k5yiSLOjsLuEi1pNWqaII6+pIfXF/JlSRvAiprHCCNnC2JKUrMR/eF0Ofr8htPI23C0voRJULZLOghr…"
   }
}

For details of the message elements 3D Secure Complete

3D Secure By Third Party Provider​

If the merchant performs 3ds authentication with some other third party service, then the authentication details returned by your provider should be sent with the authorisation request.

The data required to be sent to the platform is specified in the merchant managed 3DS section (emvco3ds.externalReferences) as part of the authorisation request. All the fields in ExternalReferences are mandatory and the authorisation request will be rejected if any are missing.

We only accept values, where authentication has taken place and have a valid authentication value.

The following is an example of the request for an authorisation where the merchant provides third party 3ds details:

Authorisation Request (Merchant Authenticated)
{
   "version": 2,
   "transaction": {
      "transactionType": "ECOMMERCE",
      "merchantRef": "QCY59hK6izpwkOKDWkzh",
      "amount": 100,
      "currency": 826
   },
   "paymentMethodType": "CARD",
   "merchant": {
      "merchantId": 1000003,
      "accountId": 2000034
   },
   "card": {
      "cardNumber": "4000120000001154",
      "securityCode": "123",
      "expiryDate": "122026"
   },
   "customer": {
      "customerId": "12345",
      "email": "[email protected]",
      "firstName": "Test",
      "surname": "Client",
      "dateOfBirth": "03042000",
      "address": {
         "addressLine1": "123 Street",
         "addressLine2": "",
         "city": "Guildford",
         "province": "Surrey",
         "postcode": "GU2 2YG",
         "country": "GBR"
      },
      "mobileNumber": "01234123123"
   },
   "paymentInfo": {
      "country": "GBR"
   },
   "emvco3ds": {
      "externalReferences": {
         "threeDSServerTransID": "cd16814e-1329-42c8-add8-f219de39ddf4",
         "dsTransID": "9996814e-1329-42c8-add8-f219de39ddf4",
         "eci": "05",
         "authenticationValue": "IL9JGE38NDeKYL6omxKsppy5lsE=",
         "version": "2.2.0"
      }
   }
}