A integração destes sistemas requer passos específicos detalhados abaixo.
Pré-requisitos:
Certifique-se de que está a utilizar um token Ventrata Checkout.
Este token é o mesmo que o seu ID Checkout. Trata-se de um token especializado concebido para ser público e pode ser utilizado com segurança no lado do cliente para fazer pedidos diretamente à api.ventrata.com. Restringe o uso de determinados endpoints.
📒 NOTA
Caso necessite de usar estes endpoints restritos, utilize tokens de ligação OCTO.
📒 NOTA
Todos os exemplos utilizam JavaScript e pacotes específicos para esta linguagem.
Passo 1: Fingerprint
The following steps outline the integration process:
1. Obter a configuração do checkout
[Lado do cliente] Faça uma chamada GET /ventrata/checkout/config para obter o objeto de configuração do checkout.
Certifique-se de utilizar a capability ventrata/checkout para obter uma resposta correta.
fetch("https://api.ventrata.com/octo/ventrata/checkout/config", {
"headers": {
"authorization": "Bearer <YOUR_TOKEN_HERE>",
"octo-capabilities": "ventrata/checkout",
},
"method": "GET",
});
A resposta contém fingerprintPublicKey — a sua chave API do Fingerprint — segura para utilização no lado do cliente.
2. Instalar o Fingerprint Agent
[Lado do cliente] Instale o pacote Fingerprint Agent v4.
npm install @fingerprint/agent
‼️ IMPORTANTE
A partir do Fingerprint v4, o script CDN/IIFE (<script src="...">) já não é suportado.
Deve utilizar o pacote NPM ou uma importação ESM.
Se anteriormente carregava o Fingerprint através de uma tag de script CDN, deverá mudar para o pacote NPM antes de continuar.
3. Inicializar o Agent
[Lado do cliente] Inicialize o agent uma vez quando a página carregar, utilizando os valores da configuração do 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. Gerar um Fingerprint
[Lado do cliente] Antes de carregar a página de pagamento, chame fpAgent.get() com o fraudAssessment.id do pagamento com cartão do pedido.
//cardPayment is from GET /octo/orders/:id
await fpAgent.get({ linkedId: cardPayment.fraudAssessment.id });
[Fingerprint] O Fingerprint irá gerar uma impressão digital do dispositivo e enviá-la diretamente para a Ventrata através de webhook.
[Lado do cliente] Consulte (poll) o endpoint GET /orders/:id até que:
cardPayments[n].fraudAssessment.fingerprintReceived === true
Política de Segurança de Conteúdo (CSP)
Se o seu site utilizar uma Content Security Policy, adicione a seguinte diretiva para permitir a integração do Web Worker do Fingerprint:
script-src <your custom subdomain>;
connect-src <your custom subdomain>;
worker-src blob:;
Se esta configuração estiver ausente, o Fingerprint fará fallback de forma graciosa, mas com precisão reduzida.
Informações adicionais
O Fingerprint transmite o sinal do dispositivo diretamente para os servidores da Ventrata. Não é necessário encaminhar quaisquer dados manualmente.
📒 NOTA
Lembre-se de implementar mecanismos robustos de tratamento de erros para detetar e gerir erros desconhecidos. Recomendamos seguir as boas práticas gerais de tratamento de erros.
Diferença principal entre v3 e v4
| v3 (@fingerprintjs/fingerprintjs- | v4 (@fingerprint/agent) |
Pacote | @fingerprintjs/fingerprintjs-pro | @fingerprint/agent |
Método de inicialização | FingerprintJS.load() — assíncrono, devolve uma Promise | Fingerprint.start() — síncrono, devolve diretamente o agent |
Configuração do endpoint
| endpoint: "https://fp.ventrata.com" | endpoints: ["https://checkout-api.ventrata.com/fp"] |
Padrão de URL do script
| scriptUrlPattern: "..." | Removido — não é necessário com endpoint |
Passo 2: Google reCAPTCHA
Os passos seguintes descrevem o processo de integração:
[Lado do cliente] Utilize
GET /ventrata/checkout/configpara obter o objeto de configuração do checkout.Certifique-se de utilizar a função (capability)
ventrata/checkoutpara obter uma resposta correta.fetch("https://api.ventrata.com/octo/ventrata/checkout/config", {
"headers": {
"authorization": "Bearer <YOUR_TOKEN_HERE>",
"octo-capabilities": "ventrata/checkout",
},
"method": "GET",
});[Lado do cliente] Carregue o script JavaScript do reCAPTCHA globalmente em todas as páginas. Utilize a
recaptchaEnterpriseSiteKeydo objeto de configuração obtido no Passo 1.<script src="https://www.recaptcha.net/recaptcha/enterprise.js?render={recaptchaEnterpriseSiteKey}">[Lado do cliente] Execute regularmente a geração de tokens em segundo plano para acionar o processamento de aprendizagem automática do reCAPTCHA. Isto deve ser feito a intervalos de 10 segundos. Use a função
grecaptcha.enterprise.executecomrecaptchaEnterpriseSiteKeyeaction: CHECKOUT. Segue um exemplo de como esta geração poderá ficar: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 do cliente] Depois de receber uma impressão digital com sucesso, atualize o pedido com um token reCAPTCHA gerado pelo
window.grecaptcha.enterprise.execute. O token deve ser gerado e o pedido atualizado imediatamente antes do utilizador ser direcionado para o gateway de pagamento.const reCatpchaOrder = await cartService.updateOrder(
orderForRecaptchaFlow.id, {
currency: orderForRecaptchaFlow.pricing.currency,
cardPayment: {
fraudAssessment: {
googleRecaptchaEnterprise: {
token: recaptchaTokenFromExecuteFn,
siteKey: recaptchaEnterpriseSiteKey,
},
},
},
},
);
📒 NOTARepita este passo a cada 60 segundos até que o pedido seja confirmado ou até que um erro crítico impeça a inicialização do gateway de pagamento. Durante este processo, é recomendável parar a
recaptchaIntervalStartdo Passo 3 para evitar a invalidação do token pelo Google. Assim que o pedido for atualizado com sucesso, retome a geração de tokens em segundo plano.O pedido será confirmado automaticamente assim que o webhook de autorização for recebido da Adyen.