3D Secure and Strong Customer Authentication (SCA)

Table of Contents

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 configured in your terminal.

3. If the authentication is successful, add the mpiReference 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
processingTerminalId Y string [ 4 .. 50 ] characters
Unique identifier that gateway assigned to the terminal.
singleUseToken Y string [ 128 ] characters
Unique token that the gateway assigned to the payment details.
email Y string [ 1 .. 128 ] characters
The cardholder email address.
amount Y number <double> > 0
The total amount to be authorized including surcharge. The value is in the currency’s lowest denomination, for example, cents.
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.
cardholderChallenge N string <enum> REQUIRED, OPTIONAL
Inform whether the cardholder challenge is required or not.

Request notes

ND001 - Data Encoding for Requests

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

Request sample

?processingTerminalId=4479001&amount=100&currency=EUR&orderId=25&email=joe%40adomain.com&singleUseToken=1a8731f50b02e287ac0529fbce352317c089d4adc1178c1867d65114078791d3c3e13962cbab6b574769dfe9ad5397a5aa67a529ceb0b7be17751f076bbe0e4d


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.
mpiReference 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).

Response sample

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

https://MPI_RECEIPT_URL?result=A&status=A&eci=06&mpiReference=d01656cf0ec3e62e3754&orderId=25

Payment Request with 3D Secure

Now that you successfully acquired the mpiReference 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",
    "processingTerminalId": "4479001",
    "order": {
        "orderId": "25",
        "currency": "EUR",
        "totalAmount": "100"
    },
    "paymentMethod": {
        "type": "singleUseToken",
        "token": "1a8731f50b02e287ac0529fbce352317c089d4adc1178c1867d65114078791d3c3e13962cbab6b574769dfe9ad5397a5aa67a529ceb0b7be17751f076bbe0e4d"
    },
    "threeDSecure": {
        "serviceProvider": "gateway",
        "mpiReference": "d01656cf0ec3e62e3754"
    }
}
Copyright © 2024 | Powered by DokuWiki