3.1. /preauth endpoint

The /preauth endpoint is used for two things:

  • Determine if card number is enrolled for 3-D Secure v2. This can be used to decide if you should fall back to using 3-D Secure v1.0.2

  • 3DSMethod invocation information

Request flow

This near-pseudocode describes the flow your code should perform.

  1. Generate the input as described in the reference (2.1.0, 2.2.0). A request might look like:

    /preauth example input, same for versions 2.1.0 and 2.2.0
    {
  "acctNumber": "4111111111111111",
  "ds": "visa"
}

  2. Send the request to the 3-D Secure Server. Consult the requests guide for information about how to make requests. A simple request performed using cURL:

    /preauth request example using cURL
    APIKEY=********-****-****-****-************
PAN=9171598723598723
curl -H "APIKey: $APIKEY" \
     -H 'Content-Type: application/json; charset=utf-8' \
     -d "{\"acctNumber\": \"$PAN\"}" \
        https://service.sandbox.3dsecure.io/preauth

  3. If the returned JSON has "messageType": "Erro" or the HTTP response code is not 200, then the request failed. Look e.g. at the BIN not enrolled error section. You should terminate the authentication.

    Note that JSON is returned even if the HTTP status code is not 200, in all but the rarest cases.

  1. If the authentication is done from a cardholder browser:

    1. If threeDSMethodURL is included in the response, invoke the 3DS Method.

    2. Use the threeDSServerTransID in the /auth request.

Response Data

Successful requests will have HTTP response code 200.

Success

If the card number is enrolled for 3-D Secure v2, the response might look something like:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
{
  "acsStartProtocolVersion": "2.1.0",
  "acsEndProtocolVersion": "2.2.0",
  "dsStartProtocolVersion": "2.1.0",
  "dsEndProtocolVersion": "2.2.0",
  "dsProtocolVersions": [
    "2.1.0",
    "2.2.0"
  ],
  "acsProtocolVersions": [
    {
      "acsInfoInd": [
        "01",
        "02",
        "84",
        "85",
        "86",
        "87",
        "88",
        "89",
        "92",
        "93",
        "94"
      ],
      "threeDSMethodURL": "https://acs.tld/3dsmethod",
      "version": "2.1.0"
    },
    {
      "acsInfoInd": [
        "01",
        "02",
        "84",
        "85",
        "86",
        "87",
        "88",
        "89",
        "92",
        "93",
        "94"
      ],
      "threeDSMethodURL": "https://acs.tld/3dsmethod",
      "version": "2.2.0"
    }
  ],
  "threeDSServerTransID": "d461f105-1792-407f-95ff-9a496fd918a9",
  "threeDSMethodURL": "https://acs.tld/3dsmethod"
}

Note

When using "deviceChannel": "02" (BRW) you must use the same threeDSServerTransID returned above for the /auth call.

The threeDSServerTransID expires after 80 seconds.

BIN not enrolled error

When the card number is not enrolled by a known card scheme, the response will look like:

1
2
3
4
5
6
7
8
{
  "messageType": "Erro",
  "errorCode": "305",
  "errorComponent": "S",
  "errorDescription": "Unknown BIN",
  "errorDetail": "No CRD found, card with BIN ****** is not enrolled with any known DS",
  "messageVersion": "2.2.0"
}

As this is the only time this combination is returned from this endpoint, you can reliably catch this by checking that:

  1. messageType is Erro

  2. errorCode is 305

Note

This error would mean you can/should retry with 3-D Secure version 1.

Other errors

Any others errors are caught by checking if messageType is Erro.

General endpoint information

  1. This endpoint relies on cached data and should respond “instantly”.

  2. The cached data is refreshed every few hours and should always be up to date.

  3. This endpoint does not incur any fees.