3DS Versioning

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

ThreeDsServerVersioningResponse extended with Boolean field isCardFoundIn2xRanges indicating 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 v2 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 v2.

ThreeDSVersioningRequest Model

18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
public class ThreeDSServerVersioningRequest {
  /**
   * Universally unique transaction identifier to identify a single transaction. If the value does not exist or it is
   * not a valid UUID, the 3DS Server will generate a new transaction ID. This value has 36 characters in a format
   * defined in IETF RFC 4122.
   */
  private String threeDSServerTransID;
  /**
   * The cardholder account number. Mandatory field.
   */
  private String cardholderAccountNumber;
  /**
   * The id of the scheme. Optional field. If not sent, the id of the scheme will be resolved from the cardholder
   * account number.
   */
  private String schemeId;
}

The schemeId is used for better resolving of the versioning data, when the versioning data is not present for the BIN range. If the schemeId is present in the request and there are ranges found in multiple schemes, the schemeId would be used for proper resolving of the versioning data.

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: UPOP (For UnionPay, it is recommended to send the scheme ID)

ThreeDSVersioningRequest JSON samples

ThreeDSVersioningRequest JSON sample with Cardholder Account
1
2
3
{
  "cardholderAccountNumber": "8944988785642183"
}
ThreeDSVersioningRequest JSON sample with Cardholder Account and Scheme
1
2
3
4
{
  "cardholderAccountNumber": "8944988785642183",
  "schemeId": "Visa"
}
ThreeDSVersioningRequest JSON sample with Cardholder Account and 3DS Server Transaction ID
1
2
3
4
{
  "cardholderAccountNumber": "8944988785642183",
  "threeDSServerTransID": "12345678-1234-5678-abcd-eFABCDEF0123"
}

ThreeDSVersioningResponse Model

28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
public class ThreeDSServerVersioningResponse {
  /**
   * Constant defining the name of the field in the 3DS Method form containing the encoded 3DS Method Data.
   */
  public static final String THREE_DS_METHOD_DATA_FORM_FIELD_NAME = "threeDSMethodData";
 
  /**
   * Universally unique transaction identifier assigned by the 3DS Server to identify a single transaction.
   */
  private String threeDSServerTransID;
  /**
   * The earliest (i.e. oldest) active protocol version that is supported by the ACS, retrieved from the card range
   * data repository.
   */
  private ProtocolVersionEnum acsStartProtocolVersion;
  /**
   * The most recent active protocol version that is supported for the ACS URL, retrieved from the card range
   * data repository.
   */
  private ProtocolVersionEnum acsEndProtocolVersion;
  /**
   * The earliest (i.e. oldest) active protocol version that is supported by the DS, retrieved from the card range
   * data repository, or optionally from the Directory Server repository in case this info is not present for the
   * particular card range.
   */
  private ProtocolVersionEnum dsStartProtocolVersion;
  /**
   * The most recent active protocol version that is supported for the DS, retrieved from the card range
   * data repository, or optionally from the Directory Server repository in case this info is not present for the
   * particular card range.
   */
  private ProtocolVersionEnum dsEndProtocolVersion;
  /**
   * The highest (most recent) active protocol version supported by the 3DS Server, DS and ACS. This value is obtained
   * as the highest common divisor between the highest 3DS Server, DS and ACS supported protocol version, whereby
   * the DS and ACS highest (#dsEndProtocolVersion and #acsEndProtocolVersion) supported protocol version are
   * retrieved from the card range data repository.
   *
   * If the highest DS and ACS protocol versions cannot be retrieved this field will be null.
   *
   * If present, it is recommended that this value be utilised in the subsequent authentication request.
   */
  private ProtocolVersionEnum highestCommonSupportedProtocolVersion;
  /**
   * The ACS Information Indicator provides additional information to the Requestor. The element lists
   * all applicable values for the card range. This information is available only if the Directory Server
   * provided the information.
   *
   * Possible values are:
   *   01 - Authentication Available at ACS
   *   02 - Attempts Supported by ACS or DS
   *   03 - Decoupled Authentication Supported
   *   04 - Whitelisting Supported
   *   80-99 - PS-specific value (these values are dependent on the payment scheme type)
   *
   *   Example: "acsInfoInd": ["01","02","80","81"]
   */
  private List<AcsInformationIndicatorEnum> acsInfoInd;
  /**
   * The ACS URL that will be used by the 3DS Method, retrieved from the card range data repository.
   */
  private URL threeDSMethodURL;
  /**
   * Map containing a key 'threeDSMethodData' and value encoded ThreeDSMethodData JSON object (containing 3DS Server
   * Transaction ID and 3DS Method Notification URL). This map shall be utilised when communicating to the ACS 3DS
   * Method URL. In case 3DS Method URL is not stored in the card range data repository for the particular card
   * range, this field will be null.
   */
  private Map<String, String> threeDSMethodDataForm;
  /**
   * Object containing the 3DS Method Data (3DS Server Transaction ID and 3DS Method Notification URL).
   * It's placed as a supplement to the threeDSMethodDataForm. In case 3DS Method URL is not stored in the card range
   * data repository for the particular card range, this field will be null.
   */
  private ThreeDSMethodData threeDSMethodData;
  /**
   * Object suggesting purpose of not existence of some fields in the returned output (Invalid cardholder account
   * number passed, not available card range data, not available 3DS Method URL for cardholder account number,
   * failure in encoding/serialization of the 3DS Method data).
   */
  private ErrorDetails errorDetails;
  /**
   * Boolean indicating whether a card is found within the card ranges. Present only for API v2.
   */
  @JsonInclude(value = JsonInclude.Include.NON_NULL)
  private Boolean isCardFoundIn2xRanges;
}

ThreeDSVersioningResponse JSON sample (v2)

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
{
  "threeDSServerTransID": "8a880dc0-d2d2-4067-bcb1-b08d1690b26e",
  "acsStartProtocolVersion": "2.1.0",
  "acsEndProtocolVersion": "2.1.0",
  "dsStartProtocolVersion": "2.1.0",
  "dsEndProtocolVersion": "2.1.0",
  "threeDSMethodURL": "http://www.acs.com/script",
  "acsInfoInd": ["01", "02"],
  "threeDSMethodDataForm": {
    "threeDSMethodData": "eyJ0aHJlZURTTWV0aG9kTm90aWZpY2F0aW9uVVJMIjoiaHR0cDovL3d3dy4zZHMuY29tL25vdGlmaWNhdGlvbi11cmwiLCJ0aHJlZURTU2VydmVyVHJhbnNJRCI6IjhhODgwZGMwLWQyZDItNDA2Ny1iY2IxLWIwOGQxNjkwYjI2ZSJ9"
  },
  "threeDSMethodData": {
    "threeDSMethodNotificationURL": "http://www.3ds.com/notification-url",
    "threeDSServerTransID": "8a880dc0-d2d2-4067-bcb1-b08d1690b26e"
  },
  "errorDetails": null,
  "isCardFoundIn2xRanges": true
}

ThreeDSVersioningResponse JSON sample (default version)

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
{
  "threeDSServerTransID": "8a880dc0-d2d2-4067-bcb1-b08d1690b26e",
  "acsStartProtocolVersion": "2.1.0",
  "acsEndProtocolVersion": "2.1.0",
  "dsStartProtocolVersion": "2.1.0",
  "dsEndProtocolVersion": "2.1.0",
  "threeDSMethodURL": "http://www.acs.com/script",
  "acsInfoInd": ["01", "02"],
  "threeDSMethodDataForm": {
    "threeDSMethodData": "eyJ0aHJlZURTTWV0aG9kTm90aWZpY2F0aW9uVVJMIjoiaHR0cDovL3d3dy4zZHMuY29tL25vdGlmaWNhdGlvbi11cmwiLCJ0aHJlZURTU2VydmVyVHJhbnNJRCI6IjhhODgwZGMwLWQyZDItNDA2Ny1iY2IxLWIwOGQxNjkwYjI2ZSJ9"
  },
  "threeDSMethodData": {
    "threeDSMethodNotificationURL": "http://www.3ds.com/notification-url",
    "threeDSServerTransID": "8a880dc0-d2d2-4067-bcb1-b08d1690b26e"
  },
  "errorDetails": null
}

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

1
2
3
4
5
6
7
8
9
10
11
12
13
14
{
  "threeDSServerTransID": "93c0ae4a-725b-45e1-a6d8-229e632b6b9f",
  "acsStartProtocolVersion": null,
  "acsEndProtocolVersion": null,
  "dsStartProtocolVersion": null,
  "dsEndProtocolVersion": null,
  "highestCommonSupportedProtocolVersion": null,
  "acsInfoInd": null,
  "threeDSMethodURL": null,
  "threeDSMethodDataForm": null,
  "threeDSMethodData": null,
  "errorDetails": null,
  "isCardFoundIn2xRanges": false
}

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

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
{
  "threeDSServerTransID": null,
  "acsStartProtocolVersion": null,
  "acsEndProtocolVersion": null,
  "dsStartProtocolVersion": null,
  "dsEndProtocolVersion": null,
  "threeDSMethodURL": null,
  "threeDSMethodDataForm": null,
  "threeDSMethodData": null,
  "errorDetails": {
    "threeDSServerTransID": "892bd5f6-3a8c-43c0-99d9-6cabe4f651ba",
    "errorCode": "404",
    "errorComponent": "S",
    "errorDescription": "Card account number not found in card ranges from Directory Server"
  }
}