3D Secure and Strong Customer Authentication (SCA)

3D Secure and Strong Customer Authentication (SCA)

Strong Customer Authentication (SCA) came into force in 2019 as part of the PSD2 regulation in Europe. In order to meet SCA requirements, you'll be required to authenticate your customers via 3D Secure to make online payments. Merchants who do not meet the requirements are at risk of having transactions rejected.

Take a closer look at our F.A.Q for more information on how PDS2 impacts merchants and customers.

The 3D Secure verification process requires the cardholder to pass an identity check. If you're using one of our shopping carts or our hosted pages solution, there's nothing to worry about as we'll handle everything for you. However, if you have a direct integration into one of our APIs, the implementation of an initial authentication step using our MPI services will be required.

The process is described in the flowchart below.

1. A POST request is sent to the MPI service provided by which handles the user authentication.

2. After authentication, the server will send the results in the form of a redirect to the MPI Receipt URL webhook configured in your terminal.

3. If the authentication is successful, add the MPIREF code received from the response into the threeDSecure section of the payment request.

Creating MPI Request

To simplify 3D Secure for API integrations, provides a simple MPI redirect.

To be able to process 3D Secure transactions, this feature must be configured in your terminal. Please contact our support team if you need 3DS to be activated in your account.

Request

TYPE	SANDBOX URL
MPI Request

Filter:

FIELD	REQUIRED	DESCRIPTION
TERMINALID	Y	^{string [ 1 .. 50 ] characters} The terminal number assigned by .
CARDNUMBER	Y	^{string [ 12 .. 19 ] characters} The payment card number.
CARDHOLDERNAME	Y	^{string [ 1 .. 50 ] characters} The cardholder's name as it appears on the card.
EMAIL	N	^{string [ 1 .. 128 ] characters} The cardholder email address.
CARDEXPIRY	Y	^{string MMYY} Expiry date of the card.
CARDTYPE	Y	Card type used for the transaction. For more details on this, visit Special Fields and Parameters - Card Types.
AMOUNT	Y	^{number <double> > 0} The total amount to be authorized including surcharge.
CURRENCY	Y	^{string 3-char ISO 4217 code} The currency code of the transaction.
ORDERID	Y	^{string [ 1 .. 24 ] characters} A unique identifier for the order assigned by the merchant.
CVV	N	^{string [ 3 .. 4 ] characters} The card's security code.
DATETIME	Y	^{string <date-time> DD-MM-YYYY:HH:MM:SS:SSS} Request date and time.
CARDHOLDER_CHALLENGE	N	^{string <enum> REQUIRED, OPTIONAL} Inform whether the cardholder challenge is required or not.
HASH ^{See notes: ND001}	Y	^{string <SHA-512> [ 1 .. 128 ] characters} A HASH code formed by part of the request fields.

Request notes

ND001 - Hash generation

See how to generate a hash string at Special Fields and Parameters. For this specific feature, you should the following format:

TERMINALID:ORDERID:CARDNUMBER:CARDEXPIRY:CARDTYPE:AMOUNT:DATETIME:SECRET

ND002 - Data Encoding for Requests

All data sent to us should be correctly encoded using UTF-8 as the character encoding.

Request sample

The HTML example below shows how to build a form to request Strong Customer Authentication (SCA) from .

<html>
  <body>
    <form id="FormID" action="" method="post">
      <label>Terminal ID</label> <input type="text" name="TERMINALID" />
      <label>Terminal Secret</label> <input type="text" name="SECRET" />
 
      <label>Order ID</label> <input type="text" name="ORDERID" />
      <label>Currency</label> <input type="text" name="CURRENCY" value="EUR" />
      <label>Amount</label> <input type="text" name="AMOUNT" />
      <label>DateTime</label> <input type="text" name="DATETIME" value="26-03-2022:10:43:01:673" />
 
      <label>Cardholder Name</label> <input type="text" name="CARDHOLDERNAME" />
      <label>Email</label> <input type="text" name="EMAIL" />
      <label>Card Number</label> <input type="text" name="CARDNUMBER" />
      <label>Expiry Date</label> <input type="text" name="CARDEXPIRY" />
      <label>CVV</label> <input type="text" name="CVV" />
 
      <label>CardType</label> <input type="text" name="CARDTYPE" />
 
      <label>Hash</label> <input type="text" name="HASH" /><br />
      <input id="SubmitID" type="submit" value="Check 3D Secure" />
    </form>
 
    <script src="https://code.jquery.com/jquery-3.2.1.min.js"></script>
    <script src="https://cdnjs.cloudflare.com/ajax/libs/blueimp-md5/2.18.0/js/md5.min.js"></script>
    <script>
      // Generating HASH
      function calcHash() {
        var hash = md5($("input[name='TERMINALID']").val() + $("input[name='ORDERID']").val() + $("input[name='CARDNUMBER']").val() + $("input[name='CARDEXPIRY']").val() + $("input[name='CARDTYPE']").val() + $("input[name='AMOUNT']").val() + $("input[name='DATETIME']").val() + $("input[name='SECRET']").val());
        $("input[name='HASH']").val(hash);
      }
 
      $("input[type='text']").each(function (index) {
        $(this).on("keyup", calcHash);
      });
 
      calcHash();
    </script>
  </body>
</html>

Remember to change the TERMINALID and SECRET for valid values. Ready to try? Sign up for a sandbox account.

Handling MPI Response

Once the 3D Secure check is complete, the following parameters will be forwarded to the MPI Receipt URL configured in your terminal

Response

The response body fields will be:

Filter:

FIELD	DESCRIPTION
RESULT	^{string <enum>} `A`: Approved. `D`: Declined.
MPIREF	^{string 20 characters} MPI reference. If present, this value should be included in the payment request.
ORDERID	^{string [ 1 .. 24 ] characters} Echoed back from the request.
STATUS	^{string <enum>} `A`: An attempt at authentication was performed. `N`: Authentication attempt not performed. `U`: Unable to authenticate. `Y`: Authentication attempted and succeeded.
ECI	^{string 2 characters} `05`: Full 3D Secure authentication. `06`: Issuer and/or cardholder are not enrolled for 3D Secure. `07`: 3D Secure authentication attempt failed - numerous possible reasons (Visa only).
DATETIME	^{string <date-time> DD-MM-YYYY:HH:MM:SS:SSS} Response date and time.
HASH ^{See notes: ND001}	^{string <SHA-512> [ 1 .. 128 ] characters} A HASH code formed by part of the response fields.

Response notes

ND001 - Hash validation

A hash string is also included in the response, so that you can implement a verification logic to make sure it was sent by . See how to decode and validate a hash string at Special Fields and Parameters.

For this specific feature, you should expect the following format:

RESULT:MPIREF:ORDERID:DATETIME:SECRET

Response sample

A GET request will be sent to your webhook containing the response fields in the form of query parameters:

https://MPI_WEBHOOK_URL?RESULT=A&STATUS=A&ECI=06&MPIREF=d01656cf0ec3e62e3754&ORDERID=25&DATETIME=06-10-2020%3A13%3A19%3A10%3A239&HASH=3ea402c12f7a8cb0afac31cf0429a167

Payment Request with 3D Secure

Now that you successfully acquired the MPIREF code, you just need to include it in your payment request within the threeDSecure section. Check out the sample below:

TYPE	SANDBOX URL
Payment Request

{
    "channel": "WEB",
    "terminal": "4479001",
    "order": {
        "orderId": "25",
        "currency": "EUR",
        "totalAmount": "6.45"
    },
    "customerAccount": {
        "payloadType": "KEYED",
        "cardholderName": "Joe Bloggs",
        "cardDetails": {
            "cardNumber": "5480161234567897",
            "expiryDate": "1222",
            "cvv": "999"
        }
    },
    "threeDSecure": {
        "serviceProvider": "GATEWAY",
        "mpiReference": "d01656cf0ec3e62e3754"
    }
}