Prepare tokenização, antifraude e o modo 3DS correto em uma chamada.
Use o SDK 1.2.0. O método executa antifraude disponível, tokenização e preparação/autenticação 3DS. Ele não cria nem confirma a cobrança.
const idempotencyKey = crypto.randomUUID();
const result = await client.preparePayment({
...paymentRequest,
idempotencyKey,
paymentMethod: 'credit_card',
paymentLinkId: linkId,
}, {
onStepChange: ({ step, status }) => atualizarEtapa(step, status),
});
if (!result.success) {
mostrarErro(result.failedAt, result.error.message);
return;
}
const charge = await criarCobrancaNoSeuBackend({
amount: paymentRequest.amount,
currency: paymentRequest.currency,
payment_method: 'credit_card',
payment_details: { token: result.token, installments: paymentRequest.installments ?? 1 },
idempotency_key: idempotencyKey,
fraud_session_id: result.fraudSessionId,
three_ds_session_id: result.threeds?.sessionId,
three_ds: result.threeds?.cavv ? {
cavv: result.threeds.cavv,
eci: result.threeds.eci,
xid: result.threeds.xid,
version: result.threeds.version,
reference_id: result.threeds.referenceId,
} : undefined,
metadata: { device: result.threeds?.device, user_agent: result.threeds?.userAgent },
});
if (charge.payment_fields?.threeds_action) {
marcarChallengeIniciado(idempotencyKey); // persista antes da chamada; não repita após reload
await client.zendry.completeThreeDS(charge.payment_fields.threeds_action);
}
const status = await consultarConfirmacaoNoSeuBackend(charge.id, idempotencyKey);
if (status.status === 'captured' && !status.confirmation_pending) mostrarSucesso();Os helpers de criação e consulta pertencem à sua aplicação e são executados pelo seu backend. Nunca exponha a chave secreta no navegador. Reutilize a mesma chave de idempotência durante a preparação, criação e recuperação.
| Campo | Descrição |
|---|---|
| success | União discriminada; verifique antes de acessar o resultado |
| token | Token do cartão para seu backend |
| idempotencyKey | Chave fornecida na preparação |
| brand / lastFourDigits / firstSixDigits | Informações retornadas pela tokenização |
| threeds.mode | pre_charge ou device_only |
| threeds.sessionId | Envie como three_ds_session_id |
| threeds.cavv / eci / xid | Presentes quando a adquirente produz autenticação antes da cobrança |
| threeds.device / userAgent | Contexto do comprador para o fluxo Zendry depois da cobrança |
| fraudSessionId | Sessão de antifraude, quando executada |
| steps / durationMs | Etapas executadas e duração |
Em device_only, status authenticated descreve a coleta do dispositivo, não autorização do emissor. O offset do device Zendry é em horas com sinal (Brasil = -3).
A coleta Zendry também ocorre quando smart_threeds está disponível e threeds está desligado. O modo de autenticação é definido pela adquirente elegível da rota.
As opções skipFraudAnalysis e skipThreeDS desabilitam suas etapas. Se você desabilitar uma etapa, sua aplicação continua responsável pelos requisitos da adquirente e do merchant. threeDSTimeout controla a autenticação antes da cobrança; o wrapper Zendry limita carregamento e conclusão do challenge separadamente.
Uma falha de preparação não significa que exista uma cobrança. Corrija os dados e repita a preparação quando necessário. Depois que o backend receber a solicitação de pagamento, uma falha de rede pode ter resultado ambíguo: consulte a mesma referência, sem criar outro pagamento.
Guarde apenas referências da tentativa e o marcador de challenge iniciado. Remova a action antes de consumi-la; nunca persista PAN/CVV e não reexecute uma action após reload. A tela e a liberação do pedido aguardam a confirmação financeira do servidor.