Integrating these systems requires specific steps detailed below.

Prerequisites:

Ensure that you are using a Ventrata Checkout token.
This token is the same as your Checkout ID. These are specialised tokens that are designed to be public and can be safely used client-side making requests directly to api.ventrata.com. They restrict the use of certain endpoints.

📒 NOTE

In case you require to use these restricted endpoints, please use OCTO connection tokens instead.

📒 NOTE

All examples use JavaScript and specific packages for this language.

Step 1: Fingerprint

The following steps outline the integration process:

1. Retrieve checkout configuration

[Client Side] Call GET /ventrata/checkout/config to retrieve the checkout configuration object.

Ensure you use the ventrata/checkout capability for a correct response.

fetch("https://api.ventrata.com/octo/ventrata/checkout/config", {
  "headers": {
    "authorization": "Bearer <YOUR_TOKEN_HERE>",
    "octo-capabilities": "ventrata/checkout",
  },
  "method": "GET",
});

The response contains fingerprintPublicKey — your Fingerprint API key — safe to use client-side.

2. Install the Fingerprint Agent

[Client Side] Install the Fingerprint Agent v4 package.

npm install @fingerprint/agent

‼️ IMPORTANT

Starting with Fingerprint v4, the CDN/IIFE script (<script src="...">) is no longer supported. You must use the NPM package or an ESM import. If you were previously loading Fingerprint via a CDN script tag, switch to the NPM package before proceeding.

3. Initialise the Agent

[Client Side] Initialise the agent once when the page loads, using the values from your checkout configuration:

import * as Fingerprint from "@fingerprint/agent";

const fpAgent = Fingerprint.start({
  apiKey: fingerprintPublicKey,      //from GET /ventrata/checkout/config
  endpoints:[fingerprintEndpoint],   // typically "https://checkout-api.ventrata.com/fp"
)}

4. Generate a Fingerprint

[Client Side] Before loading the payment page, call fpAgent.get() with the fraudAsessment.id from the order's card payment.

//cardPayment is from GET /octo/orders/:id 
await fpAgent.get({ linkedId: cardPayment.fraudAssessment.id });

[Fingerprint] Fingerprint will generate a device fingerprint and send it directly to Ventrata via webhook.

[Client Side] Poll GET /orders/:id endpoint until:

cardPayments[n].fraudAssessment.fingerprintReceived === true

Content Security Policy (CSP)

If your site uses a Content Security Policy, add the following directive to allow Fingerprint's Web Worker integration:

script-src <your custom subdomain>;
connect-src <your custom subdomain>;
worker-src blob:;

If this configuration is missing, Fingerprint will fall back gracefully, but with reduced accuracy.

Additional Information

Fingerprint transmits the device signal directly to Ventrata’s servers. You do not need to forward any data manually.

📒 NOTE

Please remember to implement robust error handling measures to catch and manage unknown errors. We recommend following general error-handling best practices.

Key difference between v3 and v4

	v3 (@fingerprintjs/fingerprintjs- pro)	v4 (@fingerprint/agent)
Package	@fingerprintjs/fingerprintjs-pro	@fingerprint/agent
Init method	FingerprintJS.load() — async, returns a Promise	Fingerprint.start() — synchronous, returns the agent directly
Endpoint config	endpoint: "https://fp.ventrata.com"	endpoints: ["https://checkout-api.ventrata.com/fp"] (array)
Script URL pattern	scriptUrlPattern: "..."	Removed — not needed with endpoint

Step2: Google reCAPTCHA

The following steps outline the integration process:

[Client Side] Call GET /ventrata/checkout/config to retrieve the checkout configuration object.

Ensure you use the ventrata/checkout capability for a correct response.

fetch("https://api.ventrata.com/octo/ventrata/checkout/config", {
  "headers": {
    "authorization": "Bearer <YOUR_TOKEN_HERE>",
    "octo-capabilities": "ventrata/checkout",
  }, 
  "method": "GET",
});

[Client Side] Load the reCAPTCHA JavaScript script globally on all pages. Use the recaptchaEnterpriseSiteKey from the configuration object retrieved in Step 1.
```
<script src="https://www.recaptcha.net/recaptcha/enterprise.js?render={recaptchaEnterpriseSiteKey}">
```

[Client Side] Regularly execute token generation in the background to trigger reCAPTCHA's machine learning processing. This should be done at 10-second intervals. Call the grecaptcha.enterprise.execute function with the recaptchaEnterpriseSiteKey and action: CHECKOUT parameters. Here is an example of how this generation might look:

function recaptchaIntervalStart(recaptchaEnterpriseSiteKey: string) {
  const intervalInSecs = 10; 
  const milliseconds = 1000;
  recaptchaIntervalID = window.setInterval(() => {
    if (window.grecaptcha?.enterprise?.ready) {
      window.grecaptcha.enterprise.ready(async () => {
        try {
      window.grecaptcha.enterprise.execute(recaptchaEnterpriseSiteKey, { 
            action: "CHECKOUT",
          });
        } catch (e) {
          console.error("reCAPTCHA interval failure", e);
          Sentry.captureException(e);
        }
      });
    }
  }, intervalInSecs * milliseconds);
  return recaptchaIntervalID;
} 
.... 
.... 
recaptchaIntervalStart(recaptchaEnterpriseSiteKey) // e.g. on `DOMContentLoaded` event

[Client Side] After receiving a successful fingerprint, update the order with a reCAPTCHA token generated by window.grecaptcha.enterprise.execute. The token should be generated, and the order updated, just before the user is directed to the payment gateway.
```
const reCatpchaOrder = await cartService.updateOrder(
  orderForRecaptchaFlow.id,
  { 
    currency: orderForRecaptchaFlow.pricing.currency,
    cardPayment: { 
      fraudAssessment: { 
        googleRecaptchaEnterprise: {
          token: recaptchaTokenFromExecuteFn,
          siteKey: recaptchaEnterpriseSiteKey,
        },
      },
    },
  },
);
```
📒 NOTE
Repeat this step every 60 seconds until the order is confirmed, or until a critical error prevents payment gateway initialisation. During this process, it is best to stop the recaptchaIntervalStart from Step 3 to avoid token invalidation by Google. Once the order is successfully updated, resume token generation in the background.
The order will automatically confirm once the authorisation webhook is received from Adyen.