Third Party 3DS2 Guide

If you have an external 3DS2 authentication provider, Spreedly’s Third Party 3DS2 solution allows you to pass externally obtained 3DS2 authentication data values in a normal transaction to a supported gateway.

Many gateways allow third-party 3DS2 authentication results to be passed as part of a standard authorize or purchase request. This allows merchants to contract with the 3DS2 provider of their choosing, while retaining the flexibility to send their final purchase or authorize requests to any gateway supporting third-party providers. Spreedly supports passing these “bring your own” third-party auth values on select gateways that support this feature.

Gateways that support third party auth values:

Sending 3DS2 Auth Data

In order to submit the results from a third-party 3DS2 authentication with an Authorize or Purchase request, you can include the following fields:

NameFormatOther Names
three_ds_versionString e.g. "2.1.0"
❯❯ ecommerce_indicatorString: 2 byteseci
❯❯ authentication_valueString: 28 bytes (Base64-encoding a 20 byte value)CAVV, AVV, UCAF Indicator, cryptogram
❯❯ directory_server_transaction_idString: 36 bytesdsTransID, xid (when explicitly used by a gateway to refer to the directory server transaction id for 3DS 2.0 requests)
❯❯ acs_transaction_idString: 36 bytesAccess Control Server (ACS)/ Issuer transaction identifier
❯❯ xidString: 28 bytes (Base64-encoding a 20 byte value)authentication transaction id
❯❯ authentication_value_algorithmStringcavvAlgorithm
❯❯ directory_response_statusStringdirectoryResponse, 3D secure directory server TransStatus response
❯❯ authentication_response_statusStringauthenticationResponse, 3D Secure authentication TransStatus response
❯❯ enrolledStringVerify Enrollment Response, VERes, Enrollment status
❯❯ three_ds_server_trans_idString: 36 bytes3D Secure server transaction i

Where this feature is supported for a gateway, and as long as you specify a three_ds_version string for version 2.x, the three_ds options object that you send will be included in the request to the underlying gateway.

Not all gateways require all of these fields, and some gateways may use only a subset of the fields for specific purposes (such as indicating an exempted transaction). Please see the gateway guide and the gateway’s own documentation for gateway-specfic nuance.

Example Usage

$ curl \
  -u 'C7cRfNJGODKh4Iu5Ox3PToKjniY:4UIuWybmdythfNGPqAqyQnYha6s451ri0fYAo4p3drZUi7q2Jf4b7HKg8etDtoKJ' \
  -H 'Content-Type: application/json' \
  -d '{
        "transaction": {
          "payment_method_token": "56wyNnSmuA6CWYP7w0MiYCVIbW6",
          "amount": 100,
          "currency_code": "USD",
          "three_ds_version": "2.1.0",
          "three_ds": {
            "ecommerce_indicator": "06",
            "authentication_value": "M2RzMiBpcyBzdXBlcmF3ZXNvbWU=",
            "directory_server_transaction_id": "362DF058-6061-47F1-A504-CACCBDF422B7",
            "xid": "YXV0aCB0eG4gaWRzIGFyZSBmdW4=",
            "authentication_value_algorithm": "1",
            "directory_response_status": "Y",
            "authentication_response_status": "Y",
            "enrolled": "Y"
$ curl \
  -u 'C7cRfNJGODKh4Iu5Ox3PToKjniY:4UIuWybmdythfNGPqAqyQnYha6s451ri0fYAo4p3drZUi7q2Jf4b7HKg8etDtoKJ' \
  -H 'Content-Type: application/xml' \
  -d '<transaction>