For extra Fraud protection, the 3DS2 protocol requires certain information about the customer’s device to recognize the overall risk for a given transaction. This process of collecting device information for risk-based analysis is called Device Fingerprinting.

Based on the merchant’s requirements across the multiple regions, it is required to identify the need of Device Data Collection (DDC) on a platform level. To fulfill this requirement, the POP system should be able to support this feature for 3DS2 opted payments.

API Usage

Use the Authorize operation to submit 3DS data with a transaction.

Authorize Request

The code below is an example of the authorization request before Device Data Collection (DDC):

<root>
  <authorize-payment account="{{account_id}}" client-id="{{client_id}}">
    <transaction type-id="{{txn_type_id}}" id="{{txnid}}" store-card="false">
      <card type-id="{{card_id}}">
        <amount country-id="{{country_id}}" currency-id="{{currency_id}}">{{amount}}</amount>
        <cvc>{{cvc}}</cvc>
        <card-holder-name>{{card_holder_name}}</card-holder-name>
        <card-number>{{card_no}}</card-number>
        <expiry>{{exprity in mm/yy format}}</expiry>
        <address country-id="{{country_id}}">
          <first-name>{{billing_address_first_name}}</first-name>
          <last-name>{{billing_address_last_name}}</last-name>
          <street>{{billing_address_street}}</street>
          <postal-code>{{billing_address_postal_code}}</postal-code>
          <city>{{billing_address_city}}</city>
          <state>{{billing_address_state}}</state>
          <contact-details>
            <mobile operator-id="{{operater_id}}" country-id="{{country_id}}">{{billing_address_mobile_no}}</mobile>
            <email>{{billing_address_email}}</email>
          </contact-details>
        </address>
      </card>   
    </transaction>      
   <client-info language="{{lan}}" sdk-version="{{sdk_ver}}" version="{{ver}}" platform="{{plaform}}" profileid="{{profile_id}}">
      <mobile operator-id="64000" country-id="640">2147483647</mobile>
      <email>{{cust_email}}</email>
      <customer-ref>{{cust_ref_id}}</customer-ref>
      <ip>{{cust_public_id}}</ip>
    </client-info>
  </authorize-payment>
</root>

Authorize Response

The code below is an example of the authorization response:

<?xml version="1.0" encoding="UTF-8"?>
<root>
	<status code="200501">DDC verification required for Authorization</status>
	<web-method>{{html encoded data}}</web-method>
	<expiry>{{in_millisecond}}</expiry>	
</root>

Get DDC Completion Notification from JavaScript

The frontend picks the JavaScript from the first Authorize response, which is mentioned in and runs on the browser. The web-method contains the pre-defined JSON format, we receive the token from CYBS. If we receive the token within eight seconds (which is the defined time), then HPP sets the value in as False. If we receive the DDC ID after the specific timeline, then that will be expiry as True. The frontend passes the received DDC ID and all response details in <device_data_info> in the second Authorize Request completes the transaction.

Contract Definition

The Contract Definitions are listed in the table below:

Response Handling

The different workflows for DDC scenarios are described below.

Scenario - The user enters the card or payment information and clicks Submit.

• Action - Disable the Submit button and call the Auth API.
• Contract - No Change.

Scenario - 200501 status code

• Action - Load HTML from the web-method node in the invisible IFrame and start a timer using the expiry node:

  • Scenario 1 : Device Data Collected Successfully
  • Scenario 2 : Device Data Collection Will Fail
  • Scenario 3 : Device Data Collection Will Expire

• Contract -

  XML

  <?xml version="1.0" encoding="UTF-8"?>
  <root>
  	<status code="200501">DDC verification required for Authorization</status>
  	<web-method>{{html encoded data}}</web-method>
  	<expiry>{{in_millisecond}}</expiry>	
  </root>
  

Scenario - DDC is completed Successfully/ Failed.

• Action - Application will get JSON in the format shown below:

  JSON

  {
  		"id": "{{ddc_id}}",
  		"collection_time": "{{in_millisecond}}",
  		"expired": "{{boolean}}",
  		"additional_info": {
  			"info": [
  				{
  					"key": "{{key}}",
  					"value": "{{value}}"
  				},
  				{
  					"key": "{{key}}",
  					"value": "{{value}}"
  				}
  			]
  		}
  	}
  

  • Convert JSON to XML.
  • Add expired": "{{boolean}}, "collection_time": "{{in_millisecond}}" in abobe json.
  • Append XML to auth request Call Auth API.

• Contract - Request : No Change +

  XML

  <device_data_info>
  	<id>{{ddc_id}}</id>
  	<collection_time>{{in_millisecond}}</collection_time>
  	<expired>{{boolean}}</expired>
  	<additional_info>
  		<info>
  			<key>{{key}}</key>
  			<value>{{value}}</value>
  		</info>
  		<info>
  			<key>{{key}}</key>
  			<value>{{value}}</value>
  		</info>
  	</additional_info>
  </device_data_info>
  

Scenario - DDC is expired.

• Action - The action includes the following:
  • Exit IFrame.
  • Populate the device_data_info node with these values:
    • expired = true
    • collection_time = assign times in millisecond
  • Append to auth request and Call Auth API.
• Contract -
  XML

  <device_data_info>	
  	<collection_time>{{in_millisecond}}</collection_time>
  	<expired>true</expired>	
  </device_data_info>
  

Scenario - 2005 status code

• Action - Redirect.
• Contract -
  XML

  <?xml version="1.0" encoding="UTF-8"?>
  <root>
  	<status code="2005">3D verification required for Authorization</status>
  	<web-method>{{html encoded data}}</web-method> or <parsed-challenge> ... </parsed-challenge>	
  	<device_collection_status>
  		<status>
  			<code>{{DDC Code}}</code>
  			<description>3D verification required for Authorization</description>
  		</status>
  	</device_collection_status>
  </root>
  

Scenario - 2000 status code

• Action - Show the error and allow the user to retry.
• Contract -
  XML

  <?xml version="1.0" encoding="UTF-8"?>
  <root>
  	<status code="2010">{{Msg}}</status>
  	<device_collection_status>
  		<status>
  			<code>{{DDC Code}}</code>
  			<description>3D verification required for Authorization</description>
  		</status>
  	</device_collection_status>	
  </root>
  

Scenario - XX status code

• Action - Show the error and allow the user to retry.
• Contract -
  XML

  <?xml version="1.0" encoding="UTF-8"?>
  <root>
  	<status code="XX">{{Msg}}</status>
  	<device_collection_status>
  		<status>
  			<code>{{DDC Code}}</code>
  			<description>3D verification required for Authorization</description>
  		</status>
  	</device_collection_status>	
  </root>
  

Contract Definitions

The Contract Definitions are listed in the table below: