Integre tokenização, 3D Secure e análise de fraude em um fluxo de pagamento ponta a ponta.
Um pagamento seguro com cartão de crédito passa por até quatro etapas antes da cobrança ser criada no seu backend:
| Etapa | Onde executa | Obrigatório | Descrição |
|---|---|---|---|
| Análise de fraude | Frontend (SDK) | Configurável | Coleta fingerprint do dispositivo via ThreatMetrix. |
| Tokenização | Frontend (SDK) | Sim | Substitui dados do cartão por um token seguro. |
| Autenticação 3DS | Frontend (SDK) | Configurável | Autentica o portador junto ao emissor. |
| Criar cobrança | Backend (API) | Sim | Cria a cobrança com token, CAVV e sessão de fraude. |
A ordem recomendada é fraude primeiro: o ThreatMetrix precisa de tempo para coletar o fingerprint em segundo plano. Iniciando a coleta antes da tokenização e do 3DS, você maximiza a qualidade dos dados antifraude.
import { Client } from '@pagsmile/security-sdk';
const client = new Client({
publicKey: 'pk_live_sua_chave',
});
await client.initialize();async function processarPagamento(dadosFormulario: DadosPagamento) {
// --- Etapa 1: Análise de fraude ---
let fraudSessionId: string | undefined;
if (client.isFraudAnalysisAvailable()) {
const fraud = await client.fraudAnalysis.setup();
fraudSessionId = fraud.sessionId;
}
// --- Etapa 2: Tokenização ---
const token = await client.tokenizer.tokenize({
card: {
number: dadosFormulario.cardNumber,
holderName: dadosFormulario.cardHolder,
expirationMonth: dadosFormulario.expMonth,
expirationYear: dadosFormulario.expYear,
cvv: dadosFormulario.cvv,
},
});
// --- Etapa 3: Autenticação 3DS ---
let threeDSResult = undefined;
if (client.isThreeDSAvailable()) {
threeDSResult = await client.threeds.authenticate({
amount: dadosFormulario.amount,
currency: 'BRL',
installments: dadosFormulario.installments,
card: {
number: dadosFormulario.cardNumber,
expirationMonth: dadosFormulario.expMonth,
expirationYear: dadosFormulario.expYear,
},
customer: {
name: dadosFormulario.customerName,
email: dadosFormulario.customerEmail,
phone: dadosFormulario.customerPhone,
},
address: dadosFormulario.address,
});
if (threeDSResult.status === 'failed') {
throw new Error('Autenticação 3DS falhou');
}
}
// --- Etapa 4: Criar cobrança no backend ---
const cobranca = await fetch('/api/charges', {
method: 'POST',
headers: { 'Content-Type': 'application/json' },
body: JSON.stringify({
amount: dadosFormulario.amount,
payment_method: 'credit_card',
card_token: token.token,
installments: dadosFormulario.installments,
fraud_session_id: fraudSessionId,
three_ds: threeDSResult?.status === 'authenticated'
? {
cavv: threeDSResult.cavv,
eci: threeDSResult.eci,
xid: threeDSResult.xid,
version: threeDSResult.version,
reference_id: threeDSResult.referenceId,
}
: undefined,
customer: {
name: dadosFormulario.customerName,
email: dadosFormulario.customerEmail,
document: dadosFormulario.customerDocument,
},
}),
});
return cobranca.json();
}Cada etapa pode falhar de forma independente. O padrão recomendado é tratar erros por etapa e dar feedback específico ao usuário:
import {
ValidationError,
ApiError,
ThreeDSError,
TimeoutError,
NetworkError,
AuthenticationError,
} from '@pagsmile/security-sdk';
async function processarPagamentoSeguro(dados: DadosPagamento) {
try {
return await processarPagamento(dados);
} catch (error) {
if (error instanceof AuthenticationError) {
// Chave pública inválida — erro de configuração
exibirErro('Erro de configuração. Contate o suporte.');
} else if (error instanceof ValidationError) {
// Dados inválidos no formulário
exibirErro(`Verifique o campo: ${error.field}`);
} else if (error instanceof ThreeDSError) {
// Falha na autenticação 3DS
exibirErro('Autenticação do cartão falhou. Tente outro cartão.');
} else if (error instanceof TimeoutError) {
// Timeout na comunicação
exibirErro('A operação demorou demais. Tente novamente.');
} else if (error instanceof NetworkError) {
// Sem conexão
exibirErro('Erro de conexão. Verifique sua internet.');
} else if (error instanceof ApiError) {
// Erro da API
exibirErro(error.message);
} else {
exibirErro('Erro inesperado. Tente novamente.');
}
}
}O comportamento do SDK é controlado pelas configurações do merchant no dashboard:
| Configuração | Efeito |
|---|---|
| Require 3DS | Se ativado, a API rejeita cobranças de cartão sem dados de autenticação 3DS. |
| Require Fraud Analysis | Se ativado, a API rejeita cobranças sem fraud_session_id. |
| Capabilities | Define quais funcionalidades estão disponíveis (depende das conexões com adquirentes). |
Use client.isThreeDSAvailable(), client.isTokenizationAvailable() e client.isFraudAnalysisAvailable() para adaptar o fluxo do checkout dinamicamente.
Chame fraudAnalysis.setup() assim que o SDK inicializar, antes mesmo do usuário terminar de preencher o formulário. Isso dá tempo ao ThreatMetrix para coletar dados.
O endereço completo do comprador aumenta significativamente a chance de um fluxo frictionless (sem interação).
Nem todo status diferente de authenticated é um erro. unenrolled pode ser aceitável dependendo da política do merchant.
O token substitui completamente os dados do cartão. Nunca armazene PAN, CVV ou dados completos de cartão no seu frontend ou backend.
Teste o fluxo completo com os cartões de teste antes de ir para produção. Veja os cartões disponíveis na seção Autenticação 3DS.