A device fingerprint uniquely identifies the device a customer is using at checkout. Anti-fraud connections use this to determine whether this device or user has been flagged for fraudulent behavior in the past, allowing it to reject the transaction and protecting you from fraud.

Each anti-fraud service will have a different way of collecting the device fingerprint, and therefore we’ve introduced our own f.js library that wraps around each of these, allowing you to focus on using your preferred anti-fraud service.

If you are using Embed or one of our e-commerce plugins, then you will not need to perform any of the steps below. Embed will automatically load the right library for you and ensure the device fingerprint is collected.

​
Usage without Embed

To create a device fingerprint, load the f.js library into your checkout page. This can be the page on which you render your checkout using Secure Fields, or any other integration.

<script src="https://api.{gr4vy_id}.gr4vy.app/f.js"></script>

In a sandbox environment make sure you use api.sandbox.{gr4vy_id} .gr4vy.app/f.js.

This will automatically load the fingerprinting library for your configured anti-fraud service and attach the fingerprint value to window.gr4vyAntiFraud.f. This fingerprint can then be sent as the anti_fraud_fingerprint property when creating a transaction.

curl -i -X POST "https://api.example.gr4vy.app/transactions" \
    -H "Authorization: Bearer [JWT_TOKEN]" \
    -H "Content-Type: application/json" \
    -d '{
          "amount": 1299,
          "currency": "AUD",
          "anti_fraud_fingerprint": "[window.gr4vyAntiFraud.f]"
        }'

​
Embed, E-commerce, and custom

When you are using Embed, or one of the e-commerce plugins like Magento, then the device fingerprint is automatically created for you and sent along when creating a transaction. You can override this behavior by sending in a custom fingerprint to Embed.

For example, if you know what anti-fraud service is in use, and you’ve already loaded that service’s fingerprint script, then you can pass in the fingerprint created by that service directly to Embed or our API. When the antiFraudFingerprint value is set we will not load any of the device fingerprint libraries and, instead, we will pass along the fingerprint provided as-is when creating a transaction.


For most anti-fraud services the fingerprint represents either the session ID or device fingerprint ID defined by that service’s anti-fraud library. Please refer to the documentation of your anti-fraud service for more details.

​
Custom & native fingerprints

In the event you are unable to use the automated solution to generate the device fingerprint, you will need to use the anti-fraud fingerprint libraries yourself and you can then pass the fingerprint to us by using the anti_fraud_fingerprint when creating a new transaction.

curl -i -X POST "https://api.example.gr4vy.app/transactions" \
    -H "Authorization: Bearer [JWT_TOKEN]" \
    -H "Content-Type: application/json" \
    -d '{
          "amount": 1299,
          "currency": "AUD",
          "anti_fraud_fingerprint": "<your device fingerprint>"
        }'

When you accept PayPal the device fingerprint will be sent to both PayPal and the Anti-Fraud service. To ensure the same fingerprint works for both services, we recommend creating a PayPal fingerprint first, and then passing the ID generated by their library to the anti fraud fingerprint library to seed the value.

​
Merchant accounts

In an environment with multiple merchant accounts it’s important to add the merchant_account_id as a query parameter to the fingerprint script. This will ensure the script is loaded for the configured anti-fraud service for that specific merchant account.

<script
  src="https://api.{gr4vy_id}.gr4vy.app/f.js?merchant_account_id=example"
  type="text/javascript"
></script>

Please note that when using an Integration API key with Embed or one of our ecommerce platforms, then the merchantAccountId needs to be set explicitly for Embed to load the anti-fraud scripts for that merchant account.

Was this page helpful?

SetupReviews