Fluxo simplificado

O que é

O método preparePayment() encapsula todas as etapas do fluxo de pagamento em uma única chamada. Internamente, ele orquestra:

Análise de fraude — coleta fingerprint do dispositivo (ThreatMetrix)
Tokenização — substitui os dados do cartão por um token seguro
Autenticação 3DS — verifica a identidade do portador junto ao emissor

Etapas indisponíveis para o merchant (por configuração ou falta de conexão com adquirente) são automaticamente ignoradas.

Este é o método recomendado para a maioria das integrações. Use os controladores individuais (tokenizer, threeds, fraudAnalysis) apenas quando precisar de controle granular sobre cada etapa.

Uso básico

import { Client } from '@accithus/security-sdk';

const client = new Client({
  publicKey: 'pk_live_sua_chave',
});
await client.initialize();

const result = await client.preparePayment({
  amount: 15000,
  currency: 'BRL',
  installments: 1,
  card: {
    number: '4000000000002701',
    holderName: 'COMPRADOR TESTE',
    expirationMonth: '12',
    expirationYear: '2030',
    cvv: '123',
  },
  customer: {
    name: 'Comprador Teste',
    email: '[email protected]',
    phone: '5511999999999',
  },
  address: {
    street: 'Rua Exemplo',
    number: '123',
    neighborhood: 'Centro',
    city: 'São Paulo',
    state: 'SP',
    zipCode: '01310100',
    country: 'BR',
  },
});

if (result.success) {
  // Envie ao backend para criar a cobrança
  await criarCobranca({
    card_token: result.token,
    fraud_session_id: result.fraudSessionId,
    three_ds: result.threeds,
  });
} else {
  console.error(`Falha em: ${result.failedAt}`, result.error.message);
}

Parâmetros

`PreparePaymentRequest`

Campo	Tipo	Obrigatório	Descrição
`amount`	`number`	Sim	Valor em centavos (ex: `15000` = R$ 150,00).
`currency`	`string`	Sim	Código ISO 4217 da moeda (`BRL`, `USD`, `EUR`).
`installments`	`number`	Não	Parcelas (padrão: `1`).
`card.number`	`string`	Sim	Número do cartão (13–19 dígitos).
`card.holderName`	`string`	Sim	Nome do portador como impresso no cartão.
`card.expirationMonth`	`string`	Sim	Mês de validade (`01`–`12`).
`card.expirationYear`	`string`	Sim	Ano de validade (4 dígitos).
`card.cvv`	`string`	Sim	Código de segurança (3–4 dígitos).
`customer.name`	`string`	Sim	Nome do comprador.
`customer.email`	`string`	Sim	Email do comprador.
`customer.phone`	`string`	Sim	Telefone com DDI+DDD (ex: `5511999999999`).
`address`	`object`	Não	Endereço de cobrança. Recomendado — melhora a taxa de aprovação no 3DS.

Endereço (opcional, recomendado)

Campo	Tipo	Obrigatório	Descrição
`address.street`	`string`	Sim	Logradouro.
`address.number`	`string`	Sim	Número.
`address.complement`	`string`	Não	Complemento.
`address.zipCode`	`string`	Sim	CEP.
`address.neighborhood`	`string`	Sim	Bairro.
`address.city`	`string`	Sim	Cidade.
`address.state`	`string`	Sim	Estado (UF, 2 caracteres).
`address.country`	`string`	Sim	País (código ISO, ex: `BR`).

`PreparePaymentOptions`

const result = await client.preparePayment(dados, {
  skipFraudAnalysis: false,
  skipThreeDS: false,
  threeDSTimeout: 120000,
  onStepChange: (event) => {
    console.log(`${event.step}: ${event.status}`);
  },
});

Opção	Tipo	Padrão	Descrição
`skipFraudAnalysis`	`boolean`	`false`	Pula a análise de fraude mesmo se disponível.
`skipThreeDS`	`boolean`	`false`	Pula a autenticação 3DS mesmo se disponível.
`threeDSTimeout`	`number`	`120000`	Timeout do fluxo 3DS em milissegundos.
`onStepChange`	`function`	—	Callback chamado a cada mudança de etapa.

Retorno

O método retorna uma union discriminada — verifique result.success para determinar o tipo:

Sucesso (`PaymentSuccess`)

if (result.success) {
  result.token;          // "tok_abc123..."
  result.brand;          // "visa"
  result.lastFourDigits; // "2701"
  result.firstSixDigits; // "400000"
  result.fraudSessionId; // "braspag_abc...uuid" | undefined
  result.threeds;        // { status, cavv, eci, xid, ... } | undefined
  result.steps;          // resumo de cada etapa
  result.durationMs;     // tempo total em ms
}

Campo	Tipo	Descrição
`success`	`true`	Discriminante.
`token`	`string`	Token do cartão para criar a cobrança.
`brand`	`string`	Bandeira detectada.
`lastFourDigits`	`string`	Últimos 4 dígitos.
`firstSixDigits`	`string`	Primeiros 6 dígitos (BIN).
`threeds`	`object \| undefined`	Dados da autenticação 3DS (se executada).
`threeds.status`	`'authenticated' \| 'unenrolled'`	Status da autenticação.
`threeds.cavv`	`string`	Cryptogram (presente se `authenticated`).
`threeds.eci`	`string`	Electronic Commerce Indicator.
`threeds.xid`	`string`	Identificador da transação 3DS.
`fraudSessionId`	`string \| undefined`	ID da sessão de fraude (se executada).
`steps`	`PaymentStepSummary[]`	Resumo de execução de cada etapa.
`durationMs`	`number`	Duração total do fluxo.

Falha (`PaymentFailure`)

if (!result.success) {
  result.error;          // Error — a exceção que causou a falha
  result.failedAt;       // "fraud_analysis" | "tokenization" | "three_ds"
  result.partialResult;  // dados das etapas que completaram antes da falha
  result.steps;          // resumo de cada etapa (incluindo a falha)
  result.durationMs;     // tempo total em ms
}

Campo	Tipo	Descrição
`success`	`false`	Discriminante.
`error`	`Error`	A exceção original.
`failedAt`	`PaymentStep`	A etapa onde ocorreu a falha.
`partialResult.token`	`string \| undefined`	Token (se tokenização completou).
`partialResult.brand`	`string \| undefined`	Bandeira (se tokenização completou).
`partialResult.fraudSessionId`	`string \| undefined`	Sessão de fraude (se completou).
`steps`	`PaymentStepSummary[]`	Inclui a etapa com falha.
`durationMs`	`number`	Duração total do fluxo.

Em caso de falha no 3DS, o partialResult contém o token e o fraudSessionId das etapas anteriores. Isso permite que você decida no backend se aceita a transação sem autenticação 3DS.

Callback de progresso

O callback onStepChange permite atualizar a UI conforme cada etapa progride:

const result = await client.preparePayment(dados, {
  onStepChange: ({ step, status }) => {
    // step: 'fraud_analysis' | 'tokenization' | 'three_ds'
    // status: 'started' | 'completed' | 'skipped' | 'failed'

    switch (status) {
      case 'started':
        mostrarLoading(step);
        break;
      case 'completed':
        marcarConcluido(step);
        break;
      case 'skipped':
        marcarIgnorado(step);
        break;
      case 'failed':
        marcarErro(step);
        break;
    }
  },
});

Exemplo com React

function Checkout() {
  const [currentStep, setCurrentStep] = useState<string | null>(null);
  const [completedSteps, setCompletedSteps] = useState<string[]>([]);

  async function handlePay() {
    const result = await client.preparePayment(formData, {
      onStepChange: ({ step, status }) => {
        if (status === 'started') setCurrentStep(step);
        if (status === 'completed') {
          setCompletedSteps((prev) => [...prev, step]);
          setCurrentStep(null);
        }
      },
    });
    // ...
  }

  return (
    <div>
      <StepIndicator
        steps={['fraud_analysis', 'tokenization', 'three_ds']}
        current={currentStep}
        completed={completedSteps}
      />
      <button onClick={handlePay}>Pagar</button>
    </div>
  );
}

Quando usar cada abordagem

Cenário	Abordagem
Checkout padrão com todas as etapas	`preparePayment()`
Controle fino sobre cada etapa	Controladores individuais (`tokenizer`, `threeds`, `fraudAnalysis`)
Tokenizar sem cobrar (salvar cartão)	`client.tokenizer.tokenize()` direto
3DS obrigatório mas fraude opcional	`preparePayment({ skipFraudAnalysis: true })`
Fluxo customizado com UI por etapa	Controladores individuais com estado manual

Comparação com o fluxo manual

Fluxo simplificado
Fluxo manual

const result = await client.preparePayment({
  amount: 15000,
  currency: 'BRL',
  card: { number, holderName, expirationMonth, expirationYear, cvv },
  customer: { name, email, phone },
});

if (result.success) {
  await criarCobranca({
    card_token: result.token,
    fraud_session_id: result.fraudSessionId,
    three_ds: result.threeds,
  });
}

let fraudSessionId;
if (client.isFraudAnalysisAvailable()) {
  const fraud = await client.fraudAnalysis.setup();
  fraudSessionId = fraud.sessionId;
}

const token = await client.tokenizer.tokenize({
  card: { number, holderName, expirationMonth, expirationYear, cvv },
});

let threeDSResult;
if (client.isThreeDSAvailable()) {
  threeDSResult = await client.threeds.authenticate({
    amount: 15000,
    currency: 'BRL',
    card: { number, expirationMonth, expirationYear },
    customer: { name, email, phone },
  });
}

await criarCobranca({
  card_token: token.token,
  fraud_session_id: fraudSessionId,
  three_ds: threeDSResult?.status === 'authenticated'
    ? { cavv: threeDSResult.cavv, eci: threeDSResult.eci, xid: threeDSResult.xid }
    : undefined,
});

Tratamento de erros

O preparePayment() nunca lança exceções (exceto para ValidationError de campos obrigatórios ausentes). Erros de cada etapa são capturados e retornados no resultado:

const result = await client.preparePayment(dados);

if (!result.success) {
  switch (result.failedAt) {
    case 'fraud_analysis':
      // Falha na coleta de fingerprint — pode tentar novamente
      // ou prosseguir sem antifraude (se merchant permitir)
      break;

    case 'tokenization':
      // Dados do cartão inválidos ou erro de API
      exibirErro('Verifique os dados do cartão');
      break;

    case 'three_ds':
      // 3DS falhou — token disponível em partialResult
      if (result.partialResult.token) {
        // Decisão do merchant: aceitar sem 3DS?
        const aceitar = await consultarBackend(result.partialResult);
        if (aceitar) {
          await criarCobranca({
            card_token: result.partialResult.token,
            fraud_session_id: result.partialResult.fraudSessionId,
          });
        }
      }
      break;
  }
}

O único caso em que preparePayment() lança uma exceção é quando card.holderName não é fornecido — esse campo é obrigatório para o fluxo completo pois é necessário tanto na tokenização quanto no 3DS.

Começando

Cobranças

Submerchants

Financeiro

Configuração

SDK de Segurança

Webhooks

Fluxo simplificado

O que é

Uso básico

Parâmetros

`PreparePaymentRequest`

Endereço (opcional, recomendado)

`PreparePaymentOptions`

Retorno

Sucesso (`PaymentSuccess`)

Falha (`PaymentFailure`)

Callback de progresso

Exemplo com React

Quando usar cada abordagem

Comparação com o fluxo manual

Tratamento de erros

​O que é

​Uso básico

​Parâmetros

​PreparePaymentRequest

​Endereço (opcional, recomendado)

​PreparePaymentOptions

​Retorno

​Sucesso (PaymentSuccess)

​Falha (PaymentFailure)

​Callback de progresso

​Exemplo com React

​Quando usar cada abordagem

​Comparação com o fluxo manual

​Tratamento de erros

O que é

Uso básico

Parâmetros

`PreparePaymentRequest`

Endereço (opcional, recomendado)

`PreparePaymentOptions`

Retorno

Sucesso (`PaymentSuccess`)

Falha (`PaymentFailure`)

Callback de progresso

Exemplo com React

Quando usar cada abordagem

Comparação com o fluxo manual

Tratamento de erros