3D-Secure v2.x Requirements

Last changes: 11-01-2022

3D-Secure v2.x Flows

In line with the new Payment Services Directive (PSD2) the 3D-Secure v2.x flows introduce several standardized processes and improvements over the previous 3D-Secure v1.0, as shown below.

Frictionless - Enables the account holding institution to apply an exemption to Strong Customer Authentication (SCA) based on the transaction risk analysis.
Challenge - The application of Strong Customer Authentication (SCA) to the payment flow. This can be SCA via Login + SMS Code, Credit Card + SMS Code, etc. depending on the account holding institution.
OOB (Out of Band) - The user is being routed to the account issuing institution to execute Strong Customer Authentication (SCA) via an institute (bank) specific procedure.

New API Requirements

The account holding institution needs additional data to decide which of the above flows should be applied for each transaction. Therefore this data must be provided in 1.38 Init Authorize.

There is a minimum requirement outlined in the "Mandatory API Parameters" below, as well as additional data fields described in the "Optional API Parameters" to improve the transaction risk analysis which may influence the account holding institution to select the "Frictionless" flow.

Mandatory API Parameters

Parameter Name	Parameter Description	Customer Data Type
customerFullName	Customer's Full Name	Billing Address Data
city	Customer's City	Billing Address Data
countryCode	Customer's Country	Billing Address Data
addr1	Customer's Address - Line 1	Billing Address Data
postCode	Customer's Post Code	Billing Address Data
emailAddress	Customer's Email Address	Billing Address Data

Provide "useDifferentBillingAddress": true in the 1.38 Init Authorize Call for Customer Data of the type "Billing Address" to be properly validated

Initiate Authorization Request

Path:: PUT {baseURL}/payment/initAuthorize
Header:: Content-Type: application/json
Accept-Language: en-US
X-Auth-Token: eyJhbGciOiJSUzI1NiI{abbreviated}RW5kVG9rZW4=

{
    "partnerReference": "DEV-SVR001-DE-3DSv2-MANDATORY-DATA-EXAMPLE",
    
    "programAccno": "1234567890",
    "accno": "MERCHANT-DE-1111",
    "accnoType": "00",
    
    "paymentOptionCode": "VISA",
    "presentationAmount": 5.99,
    "presentationCurrCode": "EUR",
    "presentationUsage": "4x Widgets. Merch: TechSoft GmbH.",
    
    "useDifferentBillingAddress":true,
    "customerFullName": "Jacob Smith",
    "emailAddress": "user@example.com",
    "addr1": "AnyStreet",
    "houseNumber": "321",
    "city": "AnyCity",
    "countryCode": "DE",
    "postCode": "12345",
    
    "localDate": "2019-12-31",
    "localTime": "235959"
}

If the value of "countryCode" is "US" (United States of America) or "CA" (Canada) the "state" parameter becomes required. The value of "state" must be a valid State Code. (ex. "countryCode": "US", "state": "NY",)

Optional API Parameters

Parameter Name	Parameter Description	Customer Data Type
addr2	Customer's Address - Line 2	Billing Address Data
state	Customer's State	Billing Address Data
phone	Customer's Phone Number	Billing Address Data
mobilePhone	Customer's Mobile Phone	Other Customer Data
workPhone	Customer's Work Phone	Other Customer Data
shipping.city	Customer's City	Shipping Address Data
shipping.countryCode	Customer's Country	Shipping Address Data
shipping.addr1	Customer's Address - Line 1	Shipping Address Data
shipping.addr2	Customer's Address - Line 2	Shipping Address Data
shipping.postCode	Customer's Post Code	Shipping Address Data
shipping.state	Customer's State	Shipping Address Data

Provide "useDifferentBillingAddress": true in the 1.38 Init Authorize Call for Customer Data of the type "Billing Address" to be properly validated

"Other Customer Data" and "Shipping Address" must be provided under the "criteria" array as "name-value" pairs in the 1.38 Init Authorize Call

Initiate Authorization Request

Path:: PUT {baseURL}/payment/initAuthorize
Header:: Content-Type: application/json
Accept-Language: en-US
X-Auth-Token: eyJhbGciOiJSUzI1NiI{abbreviated}RW5kVG9rZW4=

{
    "partnerReference": "DEV-SVR001-DE-3DSv2-OPTIONAL-DATA-EXAMPLE",
    
    "programAccno": "1234567890",
    "accno": "MERCHANT-DE-1111",
    "accnoType": "00",
    
    "paymentOptionCode": "MSTRCRD",
    "presentationAmount": 5.99,
    "presentationCurrCode": "EUR",
    "presentationUsage": "4x Widgets. Merch: TechSoft GmbH.",
    
    "useDifferentBillingAddress":true,
    "customerFullName": "Jacob Smith",
    "emailAddress": "user@example.com",
    "phone": "+123 456 789 000",
    "addr1": "Some Street Name",
    "addr2": "Some Building",
    "houseNumber": "321",
    "city": "New York City",
    "countryCode": "US",
    "state": "NY",
    "postCode":"12345",
    
    "criteria":
    [
        { "name": "workPhone", "value": "+101 101 101 101" },
        { "name": "mobilePhone", "value": "+202 202 202 202" },
        { "name": "shipping.city", "value": "Ottawa" },
        { "name": "shipping.countryCode", "value": "CA" },
        { "name": "shipping.addr1", "value": "Other Street Name" },
        { "name": "shipping.addr2", "value": "Other Building" },
        { "name": "shipping.postCode", "value": "10101" },
        { "name": "shipping.state", "value": "ON" }
    ],
    
    "localDate": "2019-12-31",
    "localTime": "235959"
}

The above examples show the Guest Payment flow, but can similarly be applied for a Customer Initiated Transaction using a "Cards" Stored Payment Option

For the best customer journey and compatibility during the 3D-Secure v2.x verification make sure you have integrated the latest SDK version available

Previous

Next