SDK de Segurança
Fluxo completo 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:
1. Análise de fraude
2. Tokenização
3. Autenticação 3DS
4. Criar cobrança
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 '@soarlabz/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 = 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 '@soarlabz/security-sdk' ; async function processarPagamentoSeguro ( dados : DadosPagamento ) {
Preenche formulário
initialize()
GET /config
Capabilities do merchant
fraudAnalysis.setup()
POST /fraud/setup
ThreatMetrix config
Carrega fingerprinting (background)
tokenizer.tokenize(card)
POST /tokenize
token + brand + metadados
threeds.authenticate(dados)
POST /3ds/sessions
Solicita token
access_token
Sessão pendente
BP.Mpi autenticação (client-side)
CAVV + ECI + XID
POST /3ds/sessions/{id}/fingerprinting
Resultado final
Token + CAVV + fraud_session_id
POST /charges
Cobrança criada
Resultado
Confirmação
Comprador
Seu Frontend
PayHub SDK
PayHub API
ThreatMetrix
Braspag MPI
Seu Backend
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 .
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 ();
}
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.' );
}
}
}
