3DS Versioning

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 and the default values located in the PRes message are utilised. The schemeId is optional, but should be passed when it is not one of the schemes for which scheme resolving regular expressions are provided in the 3DS Server Configuration Properties.

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)
  • Union Pay scheme ID: UPOP

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",
  "scheme": "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

27
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
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;
}

ThreeDSVersioningResponse JSON sample

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

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"
  }
}