Fluxo completo
Integre tokenização, 3D Secure e análise de fraude em um fluxo de pagamento ponta a ponta.
Visão geral
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.
Implementação completa
1. Inicialização do SDK
import { Client } from '@soarlabz/security-sdk';
const client = new Client({
publicKey: 'pk_live_sua_chave',
});
await client.initialize();2. Fluxo de pagamento
async function processarPagamento(dadosFormulario: DadosPagamento) {
// --- Etapa 1: Análise de fraude ---
let fraudSessionId: string | undefined;
if (client.isFraudAnalysisAvailable()) {
const fraud =
Tratamento de erros
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) {
Diagrama de sequência completo
Configurações do merchant
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.
Boas práticas
Inicie a análise de fraude cedo
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.
Envie o endereço de cobrança no 3DS
O endereço completo do comprador aumenta significativamente a chance de um fluxo frictionless (sem interação).
Trate cada status do 3DS
Nem todo status diferente de authenticated é um erro. unenrolled pode ser aceitável dependendo da política do merchant.
Não armazene dados sensíveis
O token substitui completamente os dados do cartão. Nunca armazene PAN, CVV ou dados completos de cartão no seu frontend ou backend.
Use cartões de teste
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.