Third Party 3DS2 Guide

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.

Supported Gateways

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:

Name Format Other names
three_ds_version String

(e.g. “2.1.0”)
three_ds Object
❯❯ ecommerce_indicator String: 2 bytes eci
❯❯ authentication_value String: 28 bytes

(Base64-encoding a 20 byte value)		 CAVV, AAV, UCAF Indicator, cryptogram
❯❯ directory_server_transaction_id String: 36 bytes dsTransID, xid (when explicitly used by a gateway to refer to the directory server transaction id for 3DS 2.0 requests)
❯❯ acs_transaction_id String: 36 bytes Access Control Server (ACS)/ Issuer transaction identifier
❯❯ xid String: 28 bytes

(Base64-encoding a 20 byte value)		 authentication transaction id
❯❯ authentication_value_algorithm String cavvAlgorithm
❯❯ directory_response_status String directoryResponse, 3D secure directory server TransStatus response
❯❯ authentication_response_status String authenticationResponse, 3D Secure authentication TransStatus response
❯❯ enrolled String Verify Enrollment Response, VERes, Enrollment status
❯❯ three_ds_server_trans_id String: 36 bytes 3D Secure server transaction id

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 https://core.spreedly.com/v1/gateways/LlkjmEk0xNkcWrNixXa1fvNoTP4/purchase.json \
  -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 https://core.spreedly.com/v1/gateways/LlkjmEk0xNkcWrNixXa1fvNoTP4/purchase.xml \
  -u 'C7cRfNJGODKh4Iu5Ox3PToKjniY:4UIuWybmdythfNGPqAqyQnYha6s451ri0fYAo4p3drZUi7q2Jf4b7HKg8etDtoKJ' \
  -H 'Content-Type: application/xml' \
  -d '<transaction>
        <payment_method_token>56wyNnSmuA6CWYP7w0MiYCVIbW6</payment_method_token>
        <amount>100</amount>
        <currency_code>USD</currency_code>
        <three_ds_version>2.1.0</three_ds_version>
        <three_ds>
          <ecommerce_indicator>06</ecommerce_indicator>
          <authentication_value>M2RzMiBpcyBzdXBlcmF3ZXNvbWU=</authentication_value>
          <directory_server_transaction_id>362DF058-6061-47F1-A504-CACCBDF422B7</directory_server_transaction_id>
          <xid>YXV0aCB0eG4gaWRzIGFyZSBmdW4=</xid>
          <authentication_value_algorithm>1</authentication_value_algorithm>
          <directory_response_status>Y</directory_response_status>
          <authentication_response_status>Y</authentication_response_status>
          <enrolled>Y</enrolled>
        </three_ds>
      </transaction>'