3D-Secure v2.x Requirements

Last changes: 02-22-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.

Parameter NameParameter DescriptionCustomer Data Type
customerFullNameCustomer's Full NameBilling Address Data
cityCustomer's CityBilling Address Data
countryCodeCustomer's CountryBilling Address Data
addr1Customer's Address - Line 1Billing Address Data
postCodeCustomer's Post CodeBilling Address Data
emailAddressCustomer's Email AddressBilling Address Data

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": "customer@example.com",
    "addr1": "AnyStreet",
    "houseNumber": "321",
    "city": "AnyCity",
    "countryCode": "DE",
    "postCode": "12345",
    
    "localDate": "2019-12-31",
    "localTime": "235959"
}
Parameter NameParameter DescriptionCustomer Data Type
addr2Customer's Address - Line 2Billing Address Data
stateCustomer's StateBilling Address Data
phoneCustomer's Phone NumberBilling Address Data
mobilePhoneCustomer's Mobile PhoneOther Customer Data
workPhoneCustomer's Work PhoneOther Customer Data
shipping.cityCustomer's CityShipping Address Data
shipping.countryCodeCustomer's CountryShipping Address Data
shipping.addr1Customer's Address - Line 1Shipping Address Data
shipping.addr2Customer's Address - Line 2Shipping Address Data
shipping.postCodeCustomer's Post CodeShipping Address Data
shipping.stateCustomer's StateShipping Address Data

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": "customer@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"
}