Worldfy PaymentsWorldfy Payments
SuporteDashboard
GuiaAPI Reference
SuporteDashboard

Começando

IntroduçãoAutenticaçãoErrosPaginação e Filtros
Cobranças
Visão GeralMétodos de PagamentoCaptura e Estorno
Financeiro
RecebíveisAntecipaçõesCarteiras e ExtratosSaques
Configuração
Chaves de APIRecebedores
SDK de Segurança
Visão geralTokenizaçãoAutenticação 3DSAnálise de fraudeFluxo simplificadoFluxo completoErrosProdução e segurança
Webhooks
Visão GeralConfiguraçãoRetentativas
Eventos
Eventos de CobrançasEventos de Saques

Fluxo simplificado

Execute o fluxo completo de pagamento com uma única chamada: análise de fraude, tokenização e 3DS em um só método.

Erros

Referência completa dos tipos de erro do Security SDK e como tratá-los.

SDK de Segurança

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:

1. Análise de fraude 2. Tokenização 3. Autenticação 3DS 4. Criar cobrança
EtapaOnde executaObrigatórioDescrição
Análise de fraudeFrontend (SDK)ConfigurávelColeta fingerprint do dispositivo via ThreatMetrix.
TokenizaçãoFrontend (SDK)SimSubstitui dados do cartão por um token seguro.
Autenticação 3DSFrontend (SDK)ConfigurávelAutentica o portador junto ao emissor.
Criar cobrançaBackend (API)SimCria 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 '@worldfy/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 = 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',
      product_type: 'physical',
      customer: {
        name: dadosFormulario.customerName,
        email: dadosFormulario.customerEmail,
        tax_id: dadosFormulario.customerDocument,
        phone: dadosFormulario.customerPhone,
        type: 'individual',
      },
      items: dadosFormulario.items,
      payment_details: {
        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,
    }),
  });

  return cobranca.json();
}

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 '@worldfy/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.');
    }
  }
}

Diagrama de sequência completo

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 Worldfy SDK Worldfy API ThreatMetrix Braspag MPI Seu Backend

Configurações do merchant

O comportamento do SDK é controlado pelas configurações do merchant no dashboard:

ConfiguraçãoEfeito
Require 3DSSe ativado, a API rejeita cobranças de cartão sem dados de autenticação 3DS.
Require Fraud AnalysisSe ativado, a API rejeita cobranças sem fraud_session_id.
CapabilitiesDefine 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.

Fluxo simplificado

Execute o fluxo completo de pagamento com uma única chamada: análise de fraude, tokenização e 3DS em um só método.

Erros

Referência completa dos tipos de erro do Security SDK e como tratá-los.

On this page

Visão geralImplementação completa1. Inicialização do SDK2. Fluxo de pagamentoTratamento de errosDiagrama de sequência completoConfigurações do merchantBoas práticasInicie a análise de fraude cedoEnvie o endereço de cobrança no 3DSTrate cada status do 3DSNão armazene dados sensíveisUse cartões de teste