3DS Versioning

Overview

New API version v3 for 3DS Versioning Method has been introduced:

With the introduction of the 3DS 2.3 protocol, the format of the Versioning Response has changed to support the new 2.3 format received from the Schemes.

Furthermore, the versioning response has been extended to include the the possibility to return multiple Versioning Response elements in case the card is found in multiple card ranges from different Schemes.

Apart from this a new field is introduced: directoryServerID (RID). This field is a hex value encoded as a 10-character text that is a Registered Application Provider Identifier (RID) that is unique to the Payment System.

Field isCardFoundIn2xRanges indicates whether the passed card number in the ThreeDsServerVersioningRequest is found within the card ranges and enabled for 3DS 2.x. An error with a 404 error code and message "Card account number not found in card ranges from Directory Server" is no longer returned if the card is not found in the ranges (i.e. it is not enrolled for 3DS 2.x).

Error code REQUIRED_ELEMENT_MISSING("201") is returned if the cardholder account number is missing in the ThreeDsServerVersioningRequest.

Error code FORMAT_ON_ONE_OR_MORE_ELEMENTS_INVALID_ACCORDING_SPECS("203") is returned if the cardholder account number is invalid in the ThreeDsServerVersioningRequest.

For its usage use v3 as a apiVersion path parameter in the Versioning endpoint. If no version is provided, default one is used. Example: /3ds/apiVersion/versioning where apiVersion can be v3.

Please note that the old Versioning API versions (v1 and v2) will be deprecated in Q3 2022, hence timely switching to the new Versioning v3 is highly recommended.

Supported scheme configuration naming

All supported scheme configurations should be named accordingly.

  • Visa scheme ID: Visa
  • Mastercard scheme ID: Mastercard
  • American Express scheme ID: American Express
  • JCB scheme ID: JCB
  • Diners scheme ID: Diners
  • MIR scheme ID: Mir
  • Cartes Bancaires scheme ID: CB (For Cartes Bancaires, it is recommended to send the scheme ID)
  • UnionPay scheme ID: UnionPay (For UnionPay, it is recommended to send the scheme ID)

ThreeDSVersioningRequest Model

The schemeId is used for better resolving of the versioning data, when the versioning data is not present for the BIN range. Whereas the schemeId is an optional field, in the case where card ranges are found in multiple schemes, it is required because it is the only indicator to resolve the versioning data and needs to be sent in the authentication request.

ThreeDSVersioningRequest JSON sample with Cardholder Account

ThreeDSVersioningRequest JSON sample with Cardholder Account and Scheme

ThreeDSVersioningRequest JSON sample with Cardholder Account and 3DS Server Transaction ID

ThreeDSVersioningResponse Model

ThreeDSVersioningResponse JSON sample (default version)

ThreeDSVersioningResponse indicating not enrolled 3DS 2.0 cardholder account number JSON sample (default version)

ThreeDSVersioningResponse V2 Model

ThreeDSVersioningV2Response JSON sample

ThreeDSVersioningV2Response indicating not enrolled 3DS 2.0 cardholder account number JSON sample

ThreeDSVersioningResponse V3 Model

ThreeDSVersioningV3Response JSON sample

ThreeDSVersioningV3Response when card is found in multiple ranges

ThreeDSVersioningV3Response indicating not enrolled 3DS 2.0 cardholder account number JSON sample