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 completo

Integre tokenização, 3D Secure e análise de fraude em um fluxo de pagamento ponta a ponta.

Produção e segurança

Configurações de CSP, conformidade PCI DSS e compatibilidade de navegadores para usar o SDK em produção.

SDK de Segurança

Erros

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

Hierarquia de erros

Todos os erros do SDK estendem WorldfyError, que por sua vez estende o Error nativo do JavaScript. Isso permite usar instanceof para identificar erros específicos:

Error
└── WorldfyError
    ├── AuthenticationError
    ├── ValidationError
    ├── ApiError
    ├── NetworkError
    ├── TimeoutError
    └── ThreeDSError

Tipos de erro

WorldfyError

Classe base de todos os erros do SDK. Use para capturar qualquer erro da biblioteca.

import { WorldfyError } from '@worldfy/security-sdk';

try {
  await client.tokenizer.tokenize({ ... });
} catch (error) {
  if (error instanceof WorldfyError) {
    // Qualquer erro do SDK
  }
}
PropriedadeTipoDescrição
namestringNome da classe do erro.
messagestringMensagem descritiva.

AuthenticationError

A chave pública é inválida, inativa ou não foi encontrada.

import { AuthenticationError } from '@worldfy/security-sdk';
PropriedadeTipoValor
namestring'AuthenticationError'
messagestring'Invalid public key'

Causas comuns:

  • Chave pública incorreta ou com typo
  • Chave revogada ou inativa

ValidationError

Dados de entrada inválidos. Lançado antes de fazer qualquer requisição à API.

import { ValidationError } from '@worldfy/security-sdk';

try {
  await client.tokenizer.tokenize({ ... });
} catch (error) {
  if (error instanceof ValidationError) {
    console.error(`Campo: ${error.field}`, error.message);
  }
}
PropriedadeTipoDescrição
namestring'ValidationError'
messagestringDescrição do erro de validação.
fieldstringNome do campo inválido (ex: card.number, card.cvv).

Validações na inicialização:

CampoRegra
publicKeyObrigatório, string, prefixo pk_, mínimo 10 caracteres.
timeoutSe fornecido, entre 1.000 e 60.000 ms.

Validações na tokenização:

CampoRegra
card.numberMínimo 13 dígitos.
card.cvvMínimo 3 dígitos.
card.holderNameNão pode ser vazio.
card.expirationMonthObrigatório.
card.expirationYearObrigatório.

ApiError

Erro retornado pela API da Worldfy (status HTTP diferente de 2xx, exceto 401).

import { ApiError } from '@worldfy/security-sdk';

try {
  await client.tokenizer.tokenize({ ... });
} catch (error) {
  if (error instanceof ApiError) {
    console.error(`Status: ${error.status}`, `Code: ${error.code}`, error.message);
  }
}
PropriedadeTipoDescrição
namestring'ApiError'
messagestringMensagem descritiva (em português).
statusnumberCódigo HTTP (400, 404, 422, 500 etc.).
codestringCódigo do erro em inglês (ex: TOKENIZE_FAILED, SESSION_EXPIRED).

NetworkError

Falha na comunicação com a API (sem resposta do servidor).

import { NetworkError } from '@worldfy/security-sdk';
PropriedadeTipoDescrição
namestring'NetworkError'
messagestringDescrição da falha de rede.

Causas comuns:

  • Sem conexão com a internet
  • DNS não resolvido
  • Firewall bloqueando a requisição
  • Servidor temporariamente indisponível

TimeoutError

A requisição excedeu o tempo limite configurado.

import { TimeoutError } from '@worldfy/security-sdk';
PropriedadeTipoDescrição
namestring'TimeoutError'
messagestringDescrição do timeout.

O timeout padrão é 30 segundos para requisições HTTP e 120 segundos para o fluxo 3DS completo.


ThreeDSError

Erro específico do fluxo de autenticação 3D Secure.

import { ThreeDSError } from '@worldfy/security-sdk';

try {
  await client.threeds.authenticate({ ... });
} catch (error) {
  if (error instanceof ThreeDSError) {
    console.error(`Status 3DS: ${error.status}`, error.message);
  }
}
PropriedadeTipoDescrição
namestring'ThreeDSError'
messagestringDescrição do erro.
statusstringStatus associado à falha técnica do 3DS ('error').

ThreeDSError é lançado apenas para falhas técnicas no fluxo. Os status unenrolled e failed são retornados normalmente no ThreeDSResult, não como exceção. Consulte a tabela de status em Autenticação 3DS.

Retries automáticos

O SDK implementa retries automáticos com backoff exponencial para erros de servidor (5xx):

TentativaEspera
1Imediata
2~1.000ms
3~2.000ms
4~4.000ms

Erros 4xx (validação, autenticação, não encontrado) não são retentados — são erros definitivos que requerem correção.

Exemplo completo

import {
  Client,
  WorldfyError,
  AuthenticationError,
  ValidationError,
  ApiError,
  NetworkError,
  TimeoutError,
  ThreeDSError,
} from '@worldfy/security-sdk';

try {
  const client = new Client({ publicKey: 'pk_...' });
  await client.initialize();
  // ... operações do SDK
} catch (error) {
  if (!(error instanceof WorldfyError)) {
    // Erro fora do SDK
    throw error;
  }

  switch (error.constructor) {
    case AuthenticationError:
      // Configuração inválida — contate suporte
      break;
    case ValidationError:
      // Corrija os dados do formulário
      break;
    case NetworkError:
    case TimeoutError:
      // Problema de conectividade — tente novamente
      break;
    case ThreeDSError:
      // Falha no 3DS — ofereça alternativa
      break;
    case ApiError:
      // Erro da API — exiba mensagem ao usuário
      break;
  }
}

Fluxo completo

Integre tokenização, 3D Secure e análise de fraude em um fluxo de pagamento ponta a ponta.

Produção e segurança

Configurações de CSP, conformidade PCI DSS e compatibilidade de navegadores para usar o SDK em produção.

On this page

Hierarquia de errosTipos de erroWorldfyErrorAuthenticationErrorValidationErrorApiErrorNetworkErrorTimeoutErrorThreeDSErrorRetries automáticosExemplo completo