3DS Versioning


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. Example: /3ds/apiVersion/versioning where apiVersion can be v3.

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

ThreeDSVersioningResponse V3 Model

ThreeDSVersioningResponse V3 JSON Samples