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.

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 '@soarlabz/security-sdk';

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

const result = await

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

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':

Exemplo com React

function Checkout

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

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

if (result.success) {
  await criarCobranca

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;

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.

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.

Uso básico

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

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

const result = await

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

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':

Exemplo com React

function Checkout

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

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

if (result.success) {
  await criarCobranca

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;

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

On this page

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

On this page