Device fingerprint
A device fingerprint is a method of identifying device details to facilitate a digital transaction. It collects and analyzes the device's characteristics to determine its unique fingerprint, helping you to fully or partially specify devices to prevent online identity theft and payment fraud.
Benefits
- Reduced fraud risks based on device trustworthiness
- Detection of spoofed data used to create a fake fingerprint
- Transparent and seamless user experience
- Detection of replay and bot attacks
- Ability to collect data even if a consumer has cookies/JavaScript disabled
We partnered with Microsoft to collect important static and dynamic device data. You can combine fingerprint capability with Microsoft Dynamics 365 Fraud Protection to increase the accuracy of detecting suspicious transactions. The device fingerprint can be used in the transaction risk assessment and form part of the Fraud Protection Network to track and link events for identifying fraud patterns. Once you implement device fingerprinting as part of your fraud strategy, you're enabling Microsoft to collect required data:
- Device attributes such as installed plugins, processor class
- Operating system attributes, such as OS information
- Browser-related attributes, if applicable, such as browser language, font, etc.
- Network attributes, such as IP address, etc.
How does it work
Device fingerprinting is a multi-step process where the first step involves Microsoft collecting the device information that gets linked to a transaction, providing you with additional fraud signals. With the help of JavaScript SDK, information is passed to Microsoft Dynamics 365 Fraud Protection, where AI is used to create a device identity.
- Consumer selects a payment method and makes a transaction with you.
- You send a request to verify if the selected payment product is enabled for device fingerprinting. You'll receive a response from us and will need to check for the property deviceFingerprintEnabled with the value set to true.
- Once you have established that the payment product is enabled, you need to send us a request to generate the deviceTransaction ID and run the device fingerprint JavaScript on your hosted page.
- The script will collect the device data from the consumer's browser and share the device details and deviceTransaction ID with Microsoft.
- You send us the transaction to process your payment (including the deviceTransaction ID).
- We'll send the transaction details and the deviceTransaction ID to Microsoft for risk assessment. Then we'll receive the fraud result along with Device attributes from Microsoft.
- Based on the fraud result, the transaction will be passed to the acquiring bank for Authorization, and the results will be returned to you. The response will include details about your risk assessment and the device details.
The collection and analysis of device fingerprints are integrated into MyCheckout hosted payment pages (picking this option spares you from making any changes yourself). The service is also available for integration on your own checkout pages through the Server API.
Our solution can still collect a device's fingerprint even if the consumer disabled cookies and/or JavaScript. However, it's your responsibility to inform the customer of the data you collect and how it's processed using third-party solutions.
The collection of device fingerprints from web clients (using browser software) relies on JavaScript or similar client-side scripting language to harvest a suitably large number of parameters.
The device fingerprint might be installed using multiple web clients or even virtual operating systems. It means that if consumers make multiple payments using different operating systems, the device fingerprint will differ even though it's the same user. A similar situation occurs if a mobile device runs privacy software or browser extensions that block ads and trackers, limiting data collection.
Technical integration
Irrespective of the checkout page type you opted for (MyCheckout hosted payment pages and your own checkout page), the first integration step is ensuring that the device fingerprint service and Microsoft Fraud Protection have been enabled for each payment product in your account. To get that information, please contact your account manager.
Using the MyCheckout hosted payment pages
The fingerprint service is seamlessly integrated into MyCheckout hosted payment pages. You don't need to deal manually with the service integration — just let us know if you'd like to enable it in your account. The service output is automatically included in the messaging towards Microsoft Fraud Protection and can be used to create additional fraud rules.
Using your own checkout pages
To use the device fingerprint, you'll need to add some code to your payment pages for collecting the required device information. The code is transaction-specific and can be retrieved dynamically using an API call that returns the following:
- HTML code to be added to your checkout page
- the deviceFingerprintTransactionId to be included in your CreatePayment API request
The further processing can differ depending on payment products (the API requests also vary). By calling the API for each transaction, you're sure to use the correct device fingerprint collection code, including the proper indicators to gather the device data and a unique deviceFingerprintTransactionId
Step 1: Determine for which payment products device fingerprint is enabled
Make GET https://{domainname}/v1/{merchantId}/products API call so the system informs you of the payment products enabled for the device fingerprint service. This API call is available both in the Server and the Client API.
GET /v1/9930/products?currencyCode=EUR&countryCode=NL&hide=fields HTTP/1.1
Authorization: GCS v1HMA:36f6f588bff5373d:S9HKCdy2el8l+i013Ar2cais8nJA761Ikt3eyrpiz+g=
Date: Sat, 08 Jun 2019 22:46:57 GMT
Content-Type: application/json
Host: api.preprod.connect.worldline-solutions.com
Connection: close
User-Agent: Paw/3.1.8 (Macintosh; OS X/10.14.5) GCDHTTPRequest
Check for the GET PaymentProduct API response
In the response, we need to look for the deviceFingerprintEnabled property. For each payment product, we can call the GET Payment Product Request, so its status is always "true" (in case the consumer is using this payment product in their current checkout). The example below shows that the response for the device fingerprint service has been enabled for Visa and Mastercard but not for iDEAL.
Expand example code
{
"paymentProducts": [
{
"deviceFingerprintEnabled": true,
"allowsInstallments": false,
"allowsRecurring": true,
"allowsTokenization": true,
"authenticationIndicator": {
"name": "AUTHENTICATIONINDICATOR",
"value": "1"
},
"autoTokenized": false,
"displayHints": {
"displayOrder": 1,
"label": "Visa",
"logo": "templates/master/global/css/img/ppimages/pp_logo_1_v2.png"
},
"id": 1,
"maxAmount": 999999999999,
"minAmount": 0,
"mobileIntegrationLevel": "OPTIMISED_SUPPORT",
"paymentMethod": "card",
"paymentProductGroup": "cards",
"usesRedirectionTo3rdParty": false
},
{
"deviceFingerprintEnabled": true,
"allowsInstallments": false,
"allowsRecurring": true,
"allowsTokenization": true,
"authenticationIndicator": {
"name": "AUTHENTICATIONINDICATOR",
"value": "0"
},
"autoTokenized": false,
"displayHints": {
"displayOrder": 4,
"label": "MasterCard",
"logo": "templates/master/global/css/img/ppimages/pp_logo_3_v3.png"
},
"id": 3,
"maxAmount": 1000000,
"minAmount": 0,
"mobileIntegrationLevel": "OPTIMISED_SUPPORT",
"paymentMethod": "card",
"paymentProductGroup": "cards",
"usesRedirectionTo3rdParty": false
}
]
}
}Step 2: Call the GET DeviceFingerprint API
Once you have specified which payment product your consumer uses and the device fingerprint service available for it, you can call the GET DeviceFingerprint API.
It should be done on your checkout page before you submit the transaction: this is a call to trigger a Microsoft profiling service. We’re performing actions in the pre-production environment, and the selected payment product is Visa. Please see the example request below, including the full HTTP headers.
POST /v1/11325/products/1/deviceFingerprint HTTP/1.1
Authorization: GCS v1HMAC:4d9c5e9225959a6c:a+fdQP/uXYvOZTfj6d2pkaAAkhgNul/eEyXgFIa1D/Q=
Date: Tue, 27 Jun 2023 13:13:14 GMT
Content-Type: application/json
Host: api.preprod.connect.worldline-solutions.com
Connection: close
User-Agent: Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/114.0.0.0 Safari/537.36
Content-Length: 140
Step 3: Obtain details from the response
The response from the profiling service returns the information needed to collect the Fraud Protection device data. The two returned properties, HTML and deviceFingerprintTransactionId, each serve their own purpose. More detailed information on this API and SDK-specific code example can be found in our API Reference on the Get Device Fingerprint Response.
{
"deviceFingerprintTransactionId":"014be106-68**-47**-9d**-db072607****",
"html":"
" } Step 4: Incorporate the HTML property into your checkout page
The content of the HTML property needs to be incorporated into your checkout page, where you have the final submit button. When executed, this script will collect the required information and send it to Microsoft Fraud Protection. The script will only be performed when it already contains all the correct settings, the deviceFingerprintTransactionId, and when the consumer clicks the submit button.
You should not include it in your other pages: every executed script counts, affecting your invoice.
Step 5: Call the CreatePayment API
When a user presses the button, you normally have all the payment information collected to perform the CreatePayment API call. To make sure this device fingerprint data will be taken into account, you'll need to include the deviceFingerprintTransactionId in the order.customer.devic .deviceFingerprintTransactionId property that was returned in the GetDeviceFingerprint API. This will link the captured device fingerprint with the transaction being assessed within the Microsoft Fraud Protection tool.
Expand request code
POST /v1/11325/payments HTTP/1.1
Authorization: GCS v1HMAC:36f6f588bff5373d:4ItHCmmjtYuovLPKSOWjORLrWx+cjPpso9aOZGvlHCM=
Date: Sat, 08 Jun 2019 22:17:19 GMT
Content-Type: application/json
Host: api.preprod.connect.worldline-solutions.com
Connection: close
User-Agent: Paw/3.1.8 (Macintosh; OS X/10.14.5) GCDHTTPRequest
Content-Length: 512
{
"order": {
"amountOfMoney": {
"currencyCode": "EUR",
"amount": 100
},
"customer": {
"device": {
"deviceFingerprintTransactionId": "67daae5e-da54-4645-ad6e-da4382d0b32b"
},
"billingAddress": {
"countryCode": "NL"
}
}
},
"cardPaymentMethodSpecificInput": {
"paymentProductId": 1,
"card": {
"cvv": "123",
"cardNumber": "4012000033330026",
"expiryDate": "1223",
"cardholderName": "Wile E. Coyote"
}
}
}Expand response code
HTTP/1.1 201
Date: Sat, 08 Jun 2019 22:36:49 GMT
Server: Apache
Location: https://api.preprod.connect.worldline-solutions.com/v1/9930/payments/000000993010000638450000100001
Content-Type: application/json
Connection: close
Transfer-Encoding: chunked
{
"creationOutput" : {
"additionalReference" : "AB Electronics ",
"externalReference" : "AB Electronics v24887"
},
"payment" : {
"id" : "000001132510000000640000100001",
"paymentOutput" : {
"amountOfMoney" : {
"amount" : 100,
"currencyCode" : "EUR"
},
"references" : {
"merchantReference" : "AB Electronics v24887",
"paymentReference" : "0"
},
"paymentMethod" : "card",
"cardPaymentMethodSpecificOutput" : {
"paymentProductId" : 1,
"authorisationCode" : "379677",
"fraudResults" : {
"fraudServiceResult" : "accepted",
"avsResult" : "0",
"cvvResult" : "0",
"microsoftFraudProtection" : {
"clauseName" : "NO_CLAUSE_HIT",
"deviceCountryCode" : "nl",
"deviceId" : "d125********************************************************d6c9",
"fraudScore" : 124,
"policyApplied" : "NO_RULE_HIT",
"trueIpAddress" : "147********.77",
"userDeviceType" : "browser_computer"
}
},
"card" : {
"cardNumber" : "************9936",
"cardholderName" : "Wile E. Coyote",
"expiryDate" : "1233"
}
}
},
"status" : "CAPTURE_REQUESTED",
"statusOutput" : {
"isCancellable" : true,
"statusCategory" : "PENDING_CONNECT_OR_3RD_PARTY",
"statusCode" : 800,
"statusCodeChangeDateTime" : "20230628150247",
"isAuthorized" : true,
"isRefundable" : false,
"isRetriable" : false
}
}
}
As long as the same payment product is configured for both Microsoft Dynamics 365 Fraud Protection and the device fingerprint service, some of the collected details will be available in the fraud detection tool for fraud detection evaluation. Additional properties regarding the device fingerprint service get returned in the microsoftfraudprotection object.
| Property | Description |
|---|---|
| DeviceID | This is the device fingerprint value. Based on the amount of data the device fingerprint script collected, this will be a proxy ID for the device consumer used. |
| Device Category |
The type of device used by the consumer. Possible values:
|
| True IP Address | The true IP address as determined by Microsoft. It might be different from the IP address you see on your side due to the proxy-piercing technology deployed by Microsoft. |
| Device Country Code | The consumer's country is based on the location of the True IP Address determined by Microsoft. |
Reporting
You can view the collected device data on the Microsoft Dynamics Fraud Protection tool. Go to the Device section or access more details in the JSON view when checking your transaction summary. The collected data points can be used in your fraud rules to help you manage fraud. This is how the Device Details tool looks like:
Down below you can find the JSON View. For details on the description of each field, refer to the Microsoft Fraud Protection guide.
Expand request code
"deviceContext": {
"deviceContextId": "064eca46-3a03-71ff-8b79-60bf8d56b50e",
"provider": "DFPFingerPrinting",
"deviceContextDC": null,
"externalDeviceId": null,
"externalDeviceType": null,
"ipAddress": "185.139.245.8"
},
Expand response code
"deviceAttributes": {
"trueIp": "147.161.172.110",
"deviceId": "d1251c2a2c9860df617f9c7a4f1d1590bd1cdab3a8c01cf8d6326c1d533ed6c9",
"deviceCountryCode": "nl",
"deviceState": "noord-holland",
"deviceCity": "amsterdam",
"devicePostalCode": "1101",
"carrier": "zscaler switzerland gmbh",
"userAgentType": "browser_computer",
"browserUserAgent": "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/116.0.0.0 Safari/537.36",
"browserUserAgentLanguages": "en-GB,en-US;q=0.9,en;q=0.8",
"cookieEnabled": "yes",
"fontsCount": "112",
"javaScriptEnabled": "yes",
"mimeTypesCount": "2",
"platform": "Win32",
"plugins": "",
"pluginsCount": "5",
"screenResolution": "1920x1080",
"timeZoneOffset": "60",
"proxy": "no"
},