Fingerprint and Google reCAPTCHA systems provide anti-fraud protection in the new checkout application. 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.

Please note, that all examples are using JavaScript and specific packages for this language.

Step 1: Fingerprint

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 fingerprint JS script globally on all pages using fingerprintPublicKey from the configuration object as the API key.
[Client Side] Before loading the payment page call fp.get() with the cardPayments.fraudAssessment.id from the order object.
```
fp.get({ linkedId: cardPayment.fraudAssessment?.id });
```
[Fingerprint] A fingerprint is internally generated and sent to Ventrata via webhook.
[Client Side] Poll GET /orders/:id endpoint until cardPayments.fraudAssessment.fingerprintReceived is set to true.

Additional Information

We use fingerprintjs-pro for fingerprinting. You can refer to their quickstart guide for more details.

One way to integrate Fingerprint is to include the JavaScript NPM package in your build process:

import * as FingerprintJS from '@fingerprintjs/fingerprintjs-pro' 

const fpPromise = FingerprintJS.load({
  apiKey: "{fingerprintPublicKey}",
  endpoint: "https://fp.ventrata.com",
  scriptUrlPattern: "https://fp.ventrata.com/web/v<version>/<apiKey>/loader_v<loaderVersion>.js" 
});

Then, before loading the payment screen, you can use the integration as follows:

fpPromise.then(fp => fp.get({ linkedId: "{cardPayments.fraudAssessment.id}" }))

📒 NOTE

We strongly recommend using the NPM integration instead of the CDN integration to minimise the risk of being blocked by ad blockers.

📒 NOTE

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

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.

How to Integrate and Use the Fingerprint Anit-Fraud Protection

How to Integrate Google Pay with Adyen

Ventrata Glossary