L’intégration de ces systèmes nécessite des étapes spécifiques détaillées ci-dessous.
Prérequis :
Assurez-vous d’utiliser un jeton Ventrata Checkout.
Ce jeton est identique à votre identifiant Checkout. Il s’agit de jetons spécialisés conçus pour être publics et pouvant être utilisés en toute sécurité côté client pour effectuer des requêtes directement vers api.ventrata.com. Ils limitent l’utilisation de certains endpoints.
📒 REMARQUE
Si vous devez utiliser ces endpoints restreints, veuillez utiliser des jetons de connexion OCTO.
📒 REMARQUE
Tous les exemples utilisent JavaScript et des packages spécifiques à ce langage.
Étape 1 : Fingerprint
Les étapes suivantes décrivent le processus d’intégration :
1. Récupérer la configuration checkout
[Côté client] Appelez GET /ventrata/checkout/config pour récupérer l’objet de configuration checkout.
Assurez-vous d’utiliser la capability ventrata/checkout afin d’obtenir une réponse correcte.
fetch("https://api.ventrata.com/octo/ventrata/checkout/config", {
"headers": {
"authorization": "Bearer <YOUR_TOKEN_HERE>",
"octo-capabilities": "ventrata/checkout",
},
"method": "GET",
});
La réponse contient fingerprintPublicKey — votre clé API Fingerprint — qui peut être utilisée en toute sécurité côté client.
2. Installer l’agent Fingerprint
[Côté client] Installez le package Fingerprint Agent v4.
npm install @fingerprint/agent
‼️ IMPORTANT
À partir de Fingerprint v4, le script CDN/IIFE (<script src="...">) n’est plus pris en charge. Vous devez utiliser le package NPM ou un import ESM. Si vous chargiez auparavant Fingerprint via un script CDN, vous devez basculer vers le package NPM avant de continuer.
3. Initialiser l’agent
[Côté client] Initialisez l’agent une fois au chargement de la page en utilisant les valeurs issues de la configuration checkout :
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. Générer une empreinte Fingerprint
[Côté client] Avant de charger la page de paiement, appelez fpAgent.get() avec le fraudAssessment.id du paiement par carte de la commande.
//cardPayment is from GET /octo/orders/:id
await fpAgent.get({ linkedId: cardPayment.fraudAssessment.id });
[Fingerprint] Fingerprint génère une empreinte de l’appareil et l’envoie directement à Ventrata via webhook.
[Côté client] Interrogez l’endpoint GET /orders/:id jusqu’à ce que :
cardPayments[n].fraudAssessment.fingerprintReceived === true
Politique de sécurité du contenu (CSP)
Si votre site utilise une Content Security Policy, ajoutez la directive suivante pour autoriser l’intégration Web Worker de Fingerprint :
script-src <your custom subdomain>;
connect-src <your custom subdomain>;
worker-src blob:;
Si cette configuration est absente, Fingerprint fonctionnera tout de même, mais avec une précision réduite.
Informations supplémentaires
Fingerprint transmet directement les signaux de l’appareil aux serveurs de Ventrata. Vous n’avez pas besoin de transférer de données manuellement.
📒 REMARQUE
Veuillez mettre en place des mécanismes de gestion d'erreurs robustes afin d’intercepter et de gérer les erreurs inconnues. Nous recommandons de suivre les bonnes pratiques générales de gestion des erreurs.
Différence principale entre v3 et v4
| v3 (@fingerprintjs/fingerprintjs- | v4 (@fingerprint/agent) |
Package | @fingerprintjs/fingerprintjs-pro | @fingerprint/agent |
Méthode d’initialisation | FingerprintJS.load() — asynchrone, retourne une Promise | Fingerprint.start() — synchrone, retourne directement l’agent |
Configuration de l’endpoint | endpoint: "https://fp.ventrata.com" | endpoints: ["https://checkout-api.ventrata.com/fp"] |
Pattern d’URL du script | scriptUrlPattern: "..." | Supprimé — inutile avec endpoint |
Étape 2 : Google reCAPTCHA
Les étapes suivantes décrivent le processus d’intégration :
[Côté client] Appelez
GET /ventrata/checkout/configpour récupérer l’objet de configuration checkout.Assurez-vous d’utiliser la capability
ventrata/checkoutpour obtenir une réponse correcte.fetch("https://api.ventrata.com/octo/ventrata/checkout/config", {
"headers": {
"authorization": "Bearer <YOUR_TOKEN_HERE>",
"octo-capabilities": "ventrata/checkout",
},
"method": "GET",
});[Côté client] Chargez le script JavaScript de reCAPTCHA globalement sur toutes les pages. Utilisez le
recaptchaEnterpriseSiteKeyà partir de l’objet de configuration récupéré à l’étape 1.<script src="https://www.recaptcha.net/recaptcha/enterprise.js?render={recaptchaEnterpriseSiteKey}">[Côté client] Exécutez régulièrement la génération de jetons en arrière-plan afin d’activer le traitement par apprentissage automatique de reCAPTCHA. Cette action doit être effectuée toutes les 10 secondes. Appelez la fonction
grecaptcha.enterprise.executeavec lerecaptchaEnterpriseSiteKeyetaction: CHECKOUTparamètres suivants. Voici un exemple de mise en œuvre :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[Côté client] Après avoir reçu une empreinte valide, mettez à jour la commande avec un jeton reCAPTCHA généré par
window.grecaptcha.enterprise.execute. Le jeton doit être généré, et la commande mise à jour, juste avant que l’utilisateur ne soit dirigé vers la passerelle de paiement.const reCatpchaOrder = await cartService.updateOrder(
orderForRecaptchaFlow.id,
{
currency: orderForRecaptchaFlow.pricing.currency,
cardPayment: {
fraudAssessment: {
googleRecaptchaEnterprise: {
token: recaptchaTokenFromExecuteFn,
siteKey: recaptchaEnterpriseSiteKey,
},
},
},
},
);
📒 REMARQUERépétez cette étape toutes les 60 secondes jusqu’à ce que la commande soit confirmée ou qu’une erreur critique empêche l’initialisation de la passerelle de paiement. Pendant ce processus, il est préférable d’arrêter la
recaptchaIntervalStartde l’étape 3 afin d’éviter l’invalidation du jeton par Google. Une fois la commande mise à jour avec succès, reprenez la génération de jetons en arrière-plan.La commande sera automatiquement confirmée dès que le webhook d’autorisation sera reçu d’Adyen.