La integración de estos sistemas requiere pasos específicos detallados a continuación.
Requisitos previos:
Asegúrate de que estás utilizando un token de Ventrata Checkout.
Este token es el mismo que tu Checkout ID. Se trata de tokens especializados diseñados para ser públicos y que pueden utilizarse de forma segura del lado del cliente para realizar solicitudes directamente a api.ventrata.com. Estos tokens restringen el uso de determinados endpoints.
📒 NOTA
Si necesitas utilizar estos endpoints restringidos, usa tokens de conexión OCTO en su lugar.
📒 NOTA
Todos los ejemplos utilizan JavaScript y paquetes específicos para este lenguaje.
Paso 1: Fingerprint
Los siguientes pasos describen el proceso de integración:
1. Recuperar la configuración de checkout
[Lado del cliente] Llama a GET /ventrata/checkout/config para obtener el objeto de configuración de checkout.
Asegúrate de usar la capacidad ventrata/checkout para obtener una respuesta correcta.
fetch("https://api.ventrata.com/octo/ventrata/checkout/config", {
"headers": {
"authorization": "Bearer <YOUR_TOKEN_HERE>",
"octo-capabilities": "ventrata/checkout",
},
"method": "GET",
});
La respuesta contiene fingerprintPublicKey, que es tu clave API de Fingerprint, segura para usar del lado del cliente.
2. Instalar el agente de Fingerprint
[Lado del cliente] Instala el paquete Fingerprint Agent v4.
npm install @fingerprint/agent
‼️ IMPORTANTE
A partir de Fingerprint v4, el script CDN/IIFE (<script src="...">) ya no es compatible. Debes utilizar el paquete NPM o una importación ESM.
Si anteriormente cargabas Fingerprint mediante una etiqueta de script CDN, cambia al paquete NPM antes de continuar.
3. Inicializar el agente
[Lado del cliente] Inicializa el agente una vez cuando se cargue la página, utilizando los valores de tu configuración de 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. Generar una huella digital (Fingerprint)
[Lado del cliente] Antes de cargar la página de pago, llama a fpAgent.get() con el fraudAssessment.id del pago con tarjeta del pedido.
//cardPayment is from GET /octo/orders/:id
await fpAgent.get({ linkedId: cardPayment.fraudAssessment.id });
[Fingerprint] Fingerprint generará una huella digital del dispositivo y la enviará directamente a Ventrata mediante webhook.
[Lado del cliente] Sondea el endpoint GET /orders/:id hasta que:
cardPayments[n].fraudAssessment.fingerprintReceived === true
Content Security Policy (CSP)
Si tu sitio utiliza una Content Security Policy, añade la siguiente directiva para permitir la integración de Web Worker de Fingerprint:
script-src <your custom subdomain>;
connect-src <your custom subdomain>;
worker-src blob:;
Si falta esta configuración, Fingerprint realizará un fallback automáticamente, pero con menor precisión.
Información adicional
Fingerprint transmite la señal del dispositivo directamente a los servidores de Ventrata. No necesitas reenviar ningún dato manualmente.
📒 NOTA
Recuerda implementar medidas sólidas de manejo de errores para detectar y gestionar errores desconocidos. Recomendamos seguir las mejores prácticas generales de manejo de errores.
Las principales diferencias entre v3 y v4
| v3 (@fingerprintjs/fingerprintjs- | v4 (@fingerprint/agent) |
Paquete | @fingerprintjs/fingerprintjs-pro | @fingerprint/agent |
Método de incialización | FingerprintJS.load() — asíncrono, devuelve una Promise | Fingerprint.start() — síncrono, devuelve el agente directamente |
Configuración del endpoint | endpoint: "https://fp.ventrata.com" | endpoints: ["https://checkout-api.ventrata.com/fp"] |
Patrón de URL del script | scriptUrlPattern: "..." | Eliminado — no necesario con endpoint |
Paso 2: Google reCAPTCHA
Los siguientes pasos describen el proceso de integración:
[Lado del cliente] Llama a
GET /ventrata/checkout/configpara obtener el objeto de configuración de checkout.Asegúrate de usar la capacidad
ventrata/checkoutpara obtener una respuesta correcta.fetch("https://api.ventrata.com/octo/ventrata/checkout/config", {
"headers": {
"authorization": "Bearer <YOUR_TOKEN_HERE>",
"octo-capabilities": "ventrata/checkout",
},
"method": "GET",
});[Lado del cliente] Carga el script JavaScript de reCAPTCHA de forma global en todas las páginas. Usa la
recaptchaEnterpriseSiteKeydel objeto de configuración obtenido en el Paso 1.<script src="https://www.recaptcha.net/recaptcha/enterprise.js?render={recaptchaEnterpriseSiteKey}">[Lado del cliente] Ejecuta regularmente la generación de tokens en segundo plano para activar el procesamiento de aprendizaje automático de reCAPTCHA. Esto debe hacerse en intervalos de 10 segundos. Llama a la función
grecaptcha.enterprise.executecon los parámetrosrecaptchaEnterpriseSiteKeyyaction: CHECKOUT. A continuación se muestra un ejemplo de cómo podría verse esta generación: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[Lado del cliente] Tras recibir una huella digital exitosa, actualiza el pedido con un token de reCAPTCHA generado por
window.grecaptcha.enterprise.execute. El token debe generarse y el pedido actualizarse justo antes de que el usuario sea dirigido a la pasarela de pago.const reCatpchaOrder = await cartService.updateOrder(
orderForRecaptchaFlow.id,
{
currency: orderForRecaptchaFlow.pricing.currency,
cardPayment: {
fraudAssessment: {
googleRecaptchaEnterprise: {
token: recaptchaTokenFromExecuteFn,
siteKey: recaptchaEnterpriseSiteKey,
},
},
},
},
);
📒 NOTARepite este paso cada 60 segundos hasta que el pedido se confirme o hasta que un error crítico impida la inicialización de la pasarela de pago. Durante este proceso, es mejor detener el
recaptchaIntervalStartdel Paso 3 para evitar que Google invalide el token. Una vez que el pedido se haya actualizado correctamente, reanuda la generación de tokens en segundo plano.El pedido se confirmará automáticamente una vez que se reciba el webhook de autorización de Adyen.