Autenticação 3DS

Dois fluxos de 3DS

O SDK 1.2.0 suporta autenticação antes da cobrança (por exemplo, Cielo/BP.Mpi) e 3DS inteligente depois da cobrança (Zendry). As capacidades incluem conexões próprias, subcontas e processamento elegível pela conexão master.

Fluxo recomendado

Crie uma chave por intenção de pagamento e reutilize-a desde a preparação até a cobrança. Ela também faz a seleção de rota escolher a mesma conexão quando existem regras de tráfego.

const idempotencyKey = crypto.randomUUID();
const prepared = await client.preparePayment({
  ...paymentRequest,
  idempotencyKey,
  paymentMethod: 'credit_card',
  paymentLinkId: linkId, // opcional para integrações fora do link de pagamento
});

if (!prepared.success) throw prepared.error;

// Este endpoint é do seu backend. Chaves secretas ficam somente nele.
const charge = await createChargeOnYourBackend({
  amount: paymentRequest.amount,
  currency: paymentRequest.currency,

preparePayment() coleta device também quando smart_threeds: true e threeds: false. Isso permite scoring e autenticação após a cobrança quando o 3DS antes da cobrança está desligado. Se você usar skipThreeDS, sua integração continua responsável por fornecer os dados exigidos pela adquirente.

Uso individual

const result = await client.threeds.authenticate({
  amount: 15000,
  currency: 'BRL',
  installments: 1,
  paymentMethod: 'credit_card',
  paymentLinkId: linkId,
  idempotencyKey,
  card: {

Zendry sem cliente inicializado

Quando seu backend já sabe que a rota usa Zendry, a coleta não depende de chave pública:

import { Logger, ZendryController } from '@soarlabz/security-sdk';

const zendry = new ZendryController(new Logger(false));
const collected = await zendry.threeDS();
// Envie collected.device e collected.user_agent ao seu backend.

O SDK carrega o script oficial https://api.zendry.co/sdk/v1/zendry.js. device contém language, screen_height, screen_width e time_zone_offset. O offset é em horas com sinal: Brasil = -3. Não use minutos de Date.getTimezoneOffset() nesse campo.

A documentação Zendry indica device opcional no esquema geral, mas obrigatório para contas com postura de risco reforçada. Envie-o em toda venda Zendry. Em integrações em cadeia, IP e user-agent devem ser os do comprador; headers da chamada backend → Zendry representam o servidor.

Challenge, retomada e erros

• Ausência de iframe é normal: data-only/frictionless não exige interação. Uma aprovação no aplicativo do banco também pode concluir sem callback do iframe.
• A action é de uso único, expira em 15 minutos e pertence à cobrança original. Não a reaproveite em outra tentativa.
• O wrapper limita o carregamento do script a 15 segundos, remove scripts com falha e permite nova tentativa antes de criar cobrança.
• Depois de iniciar uma action, timeout, falha de rede ou reload exigem consulta da mesma cobrança. Não crie outro pagamento nem reexecute a action automaticamente.
• O link da plataforma guarda apenas referência, estado e action ainda não iniciada na sessão; nunca guarda PAN, CVV ou dados do comprador para retomada.
• A tela “Pagamento confirmado” e o redirecionamento da loja esperam captured com confirmation_pending: false no servidor.
• Uma nova tentativa financeira requer um desfecho terminal confirmado da anterior.

Validação

O sandbox Zendry não executa 3DS real. Um cartão sintético aprovado no sandbox valida o transporte, não o challenge do emissor. A homologação do challenge real precisa de uma transação de produção autorizada e comprovação completa navegador → adquirente → webhook/reconsulta → confirmação financeira.