3D-Secure v2.x Requirements

3D-Secure v2.x Flows

In line with the new Payment Services Directive (PSD2) the 3DS 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 1.38 Init Authorize 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	Data Type
partnerReference	Partner service call identifier.	Transaction Data
programAccno	Program account number.	Transaction Data
accno	User or merchant account number.	Transaction Data
accnoType	Account number type. See Account Number Type in the Lookups.	Transaction Data
presentationAmount	The amount which is authorized for payment to the account.	Transaction Data
presentationCurrCode	The 3-letter currency code associated with the transaction.	Transaction Data
presentationUsage	Information relevant to the payment.	Transaction Data
useDifferentBillingAddress	Defines whether the stored address or a custom billing address is used. If true, the fields 'customerFullName', 'addr1', 'city', 'countryCode', 'postCode' are required. If false, the account owner address is used.	Billing Address Data
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
criteria	Collection of additional request parameters passed to the payment provider.	Other Customer Data
- name	Parameter name for Other Customer Data.	Other Customer Data
- value	Parameter name for Other Customer Data.	Other Customer Data
shippingAddress	Defines the shipping address. If the object exists, the fields 'addr1', 'city', 'countryCode', 'postCode' are required.	Shipping Address Data
- addr1	Shipping address line 1.	Shipping Address Data
- city	City name.	Shipping Address Data
- countryCode	Country ISO2 or ISO3 code.	Shipping Address Data
- postCode	Postal code.	Shipping Address Data
localDate	The current date of the caller.	Transaction Data
localTime	The current time of the caller.	Transaction Data

important

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

important

"Other Customer Data" must be provided under the "criteria" array as "name-value" pairs in the 1.38 Init Authorize Call. "Shipping Address" also needs to contain the fields 'addr1', 'city', 'countryCode', 'postCode', if this object exists.

Initiate Authorization Request

Path:

PUT {baseURL}/payment/initAuthorize

Header:

Content-Type: application/json
Accept-Language: en-US
X-Auth-Token: eyJhbGciOiJSUzI1NiI{abbreviated}RW5kVG9rZW4=

{
   "partnerReference": "1234567890",
   "programAccno": "123456",
   "accno": "XXX-123456",
   "accnoType": "00",
   "dealReference": "K0o3HA6kEE6P8Il7SaIM1",
   "storedPaymentOptionReference": "8ac7a49f66aaa1f50166be603cf15385",
   "userAccno": "XXX-654321",
   "userAccnoType": "00",
   "paymentOptionCode": "MSTRCRD",
   "presentationAmount": 100,
   "presentationCurrCode": "EUR",
   "presentationUsage": "Deposit: 100 EUR",
   "useDifferentBillingAddress": true,
   "customerFullName": "Jacob Smith",
   "emailAddress": "user@example.com",
   "addr1": "AnyStreet",
   "houseNumber": "321",
   "city": "Los Angeles",
   "countryCode": "US",
   "state": "CA",
   "postCode": "12345",
   "criteria": [
      {
         "name": "affiliate",
         "value": "ExternalShopXY"
      },
      {
         "name": "age",
         "value": "30-40"
      }
   ],
   "localDate": "2014-03-12",
   "localTime": "163835"
}

important

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 (example: "countryCode": "US", "state": "NY").

info

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

important

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