How To Use Third Party 3DS2 Providers

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:

Name	Format	Other Names
`three_ds_version`	String e.g. "2.1.0"
`three_ds_exemption_type`	String
`three_ds`	Object
❯❯ `ecommerce_indicator`	String: 2 bytes	eci
❯❯ `authentication_value`	String: 28 bytes (Base64-encoding a 20 byte value)	CAVV, AVV, 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 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). When using multiple gateways you can send a superset of 3DS authentication fields that cover all of your gateways and Spreedly will only send fields to the gateway if the gateway is able to accept them. Please see the gateway guide and the gateway’s own documentation for gateway-specific 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>'