> ## Documentation Index
> Fetch the complete documentation index at: https://docs.fastpaybrasil.com/llms.txt
> Use this file to discover all available pages before exploring further.

# SDK de segurança (3DS)

> Faça a autenticação 3D Secure completa no front-end com o SDK de segurança e envie o resultado na criação da cobrança.

O SDK de segurança faz a autenticação 3D Secure (3DS) inteira no navegador do comprador com uma única chamada, o método `process()`. Ele coleta os dados do navegador, abre o desafio do banco emissor em um modal quando necessário e devolve o resultado da autenticação. O seu backend envia esse resultado no campo `paymentMethod.threeDS` ao criar a cobrança.

> [!NOTE]
>
> **Para o negócio:** o SDK é a forma de integrar o 3DS com menos código no checkout. O cliente vê a tela do banco só quando o emissor pede uma confirmação. Nos demais casos, a autenticação acontece sem interação.

> [!NOTE]
>
> O pacote foi publicado com o nome anterior da marca: `@fastpaybr/security-sdk`. A classe exportada é `Client`, que também é o export padrão. Pelo CDN, ela fica em `FastPay.Client`. Também mantêm o nome anterior a classe de erro `FastPayError` e o prefixo `[FastPay]` nas mensagens de log de depuração. Esses nomes são esperados e só mudam com uma nova versão do SDK.

## Quando usar

| Situação | Recomendação |
| - | - |
| Checkout web com cartão digitado e 3DS exigido pela conta | SDK |
| Você quer a autenticação pronta antes de criar a cobrança | SDK |
| Você precisa controlar cada tela e cada chamada | [3DS via API](https://docs.fastpaybrasil.com/guias/3d-secure/via-api.md) |
| Você prefere que a Finvia conduza o 3DS depois de criar a cobrança | [3DS gerenciado](https://docs.fastpaybrasil.com/guias/3d-secure/gerenciado.md) |

## Como funciona

O desenho abaixo mostra o que acontece entre o clique em pagar e a resposta da cobrança quando você usa o SDK.

```mermaid placement="top-right" className="finvia-diagrama" theme={null}
%%{init: {"theme": "base", "fontFamily": "Inter, sans-serif", "themeVariables": {"fontFamily": "Inter, Arial, sans-serif", "fontSize": "15px", "primaryColor": "#EAF3FF", "primaryBorderColor": "#017AFF", "primaryTextColor": "#070D15", "secondaryColor": "#F3F5F8", "tertiaryColor": "#FFFFFF", "lineColor": "#5B6B82", "textColor": "#070D15", "edgeLabelBackground": "#FFFFFF", "clusterBkg": "#F7F9FC", "clusterBorder": "#D5DCE6", "actorBkg": "#FFFFFF", "actorBorder": "#98A2B3", "actorTextColor": "#070D15", "actorLineColor": "#B8C2D1", "signalTextColor": "#070D15", "labelBoxBkgColor": "#EAF3FF", "labelBoxBorderColor": "#017AFF", "labelTextColor": "#003A7A", "loopTextColor": "#070D15", "noteBkgColor": "#FFF6E5", "noteBorderColor": "#F0B44C", "noteTextColor": "#5C3D00", "activationBkgColor": "#EAF3FF", "activationBorderColor": "#017AFF", "sequenceNumberColor": "#FFFFFF", "signalColor": "#5B6B82"}, "flowchart": {"curve": "basis", "nodeSpacing": 45, "rankSpacing": 55, "padding": 18}, "sequence": {"mirrorActors": false, "showSequenceNumbers": true, "actorMargin": 60, "messageMargin": 38, "boxMargin": 10, "noteMargin": 12, "wrap": true}}}%%
sequenceDiagram
    autonumber
    box rgb(255,246,229) Comprador
        participant C as Comprador
    end
    box rgb(243,245,248) Sua aplicação
        participant N as Seu checkout com o SDK
        participant L as Seu backend
    end
    box rgb(234,243,255) Finvia
        participant F as Finvia API
    end
    box rgb(244,240,255) Fora da Finvia
        participant E as Banco emissor
    end
    N->>N: Inicializa o SDK com a chave pública (pk_)
    C->>N: Informa o cartão e confirma a compra
    N->>F: process() · envia amount, currency, card e dados do navegador
    opt O emissor pede verificação do dispositivo
        N->>E: Fingerprinting em iframe oculto
    end
    alt O emissor pede confirmação
        N-->>C: Abre o modal com a tela do banco
        C->>E: Confirma a compra
    else Sem fricção
        Note over N,E: Segue sem interação do comprador
    end
    F-->>N: Resultado da autenticação · type e state
    alt state success
        N->>L: Envia o resultado como veio
        L->>F: POST /v1/charges · sk_ · cvv · installments · threeDS
        F-->>L: 201 · paid, refused ou failed
        L-->>C: Mostra o resultado do pedido
    else Outro state, ou modal fechado (type none, state failure)
        N-->>C: Com 3DS obrigatório, não crie a cobrança · ofereça nova tentativa
    end
```

O SDK roda no navegador com a chave pública. O CVV e as parcelas não passam pelo `process()`: eles vão só na criação da cobrança, feita pelo seu backend com a chave secreta.

**1. Inicialize o SDK com a chave pública**

Crie o `Client` com a chave pública (`pk_`) e chame `initialize()`. Confira `isThreeDSAvailable()`.

**2. Chame process() com os dados da compra**

Valor, moeda, cartão e cliente. O endereço é opcional.

**3. O SDK coleta os dados do navegador**

O SDK coleta sozinho os dados do navegador, inclusive o IP público do comprador, e, quando o emissor pede, faz o fingerprinting (verificação do dispositivo).

**4. Desafio, quando necessário**

Se o emissor pede confirmação, o SDK abre um modal com a tela do banco. Se não pede, o fluxo segue sem fricção.

**5. Resultado**

`process()` devolve o resultado com `state`. Se for `success`, envie o resultado ao seu backend. Se o comprador fechar o modal, o resultado é `{ type: 'none', state: 'failure' }`.

**6. Seu backend cria a cobrança**

`POST /v1/charges` com o resultado em `paymentMethod.threeDS`, usando a chave secreta.

| `state` do resultado | O que acontece |
| - | - |
| `success` | Criar a cobrança com os dados 3DS |
| `failure` | Falha na autenticação: transação recusada |
| `unenrolled` | Cartão não inscrito |
| `error` | Erro no processo |
| `unsupported_brand` | Bandeira não suportada |
| `disabled` | 3DS desabilitado |

## Regras de negócio

| Regra | Detalhe |
| - | - |
| Chave usada no SDK | Chave pública (`pk_`). A chave secreta nunca vai para o navegador |
| Cobrança | Criada pelo seu backend, com a chave secreta, depois da autenticação |
| Estado que libera a cobrança | Só `success`, quando o 3DS é exigido pela configuração da conta. Sem 3DS obrigatório, os dados 3DS são repassados sem validação |
| Dados de `process()` | `amount`, `currency`, `card` e `customer` obrigatórios; `address` opcional. `process()` não aceita `installments`: as parcelas vão só na cobrança |
| O que o SDK envia à API | Só `amount`, `currency`, `card` e os dados do navegador, que ele coleta sozinho (inclusive o IP público). `customer` e `address` não são enviados |
| Fechar o modal | `process()` não lança erro: devolve `{ type: 'none', state: 'failure' }` |

## Instalação

> [tab] NPM
>
> ```bash theme={null}
> npm install @fastpaybr/security-sdk
> ```

> [tab] CDN
>
> ```html theme={null}
> <script src="https://js.fastpaybrasil.com/security-sdk.min.js"></script>
> ```
>
> O script expõe o objeto global `FastPay`. A classe fica em `FastPay.Client` (ou `FastPay.default`).

## Inicialização

### Configuração básica

```javascript theme={null}
import { Client } from '@fastpaybr/security-sdk'
// ou: import FinviaClient from '@fastpaybr/security-sdk' (export padrão)

const client = new Client({
  credentials: {
    publicKey: 'pk_sua_chave_publica'
  },
  debug: false
})

await client.initialize()

if (client.isThreeDSAvailable()) {
  console.log('3DS disponível e pronto para uso')
}
```

### Verificação de status

```javascript theme={null}
// Verificar se o SDK foi inicializado
if (client.isReady()) {
  console.log('SDK inicializado com sucesso')
}

// Verificar se o 3DS está disponível
if (client.isThreeDSAvailable()) {
  console.log('3DS pronto para uso')
}
```

## Fluxo de autenticação

### Processo completo (recomendado)

O método `process()` conduz todo o fluxo de autenticação:

```javascript theme={null}
try {
  const result = await client.threeds.process(
    {
      // Dados da transação
      amount: 100.00, // Valor na moeda especificada
      currency: 'BRL',

      // Dados do cartão
      card: {
        number: '4111111111111111',
        holderName: 'Joao Silva',
        expirationMonth: '12',
        expirationYear: '2028'
      },

      // Dados do cliente (obrigatório na tipagem do SDK)
      customer: {
        name: 'Joao Silva',
        email: 'joao@email.com',
        phone: '+5511987654321'
      },

      // Endereço do cliente (opcional)
      address: {
        street: 'Av. Paulista',
        number: '1000',
        complement: 'Apto 51',
        zipCode: '01310100',
        neighborhood: 'Bela Vista',
        city: 'São Paulo',
        state: 'SP',
        country: 'BRA'
      }
    },
    {
      // Opções (todas opcionais)
      fingerprintingTimeout: 60000, // Tempo limite do fingerprinting (padrão: 60s)
      challengeTimeout: 600000, // Tempo limite do desafio (padrão: 10min)
      modal: {
        width: '600px', // Largura do modal (padrão: 600px)
        height: '600px', // Altura do modal (padrão: 600px)
        showCloseButton: true // Mostrar botão de fechar
      }
    }
  )

  // Resultado da autenticação
  console.log('Autenticação concluída:', result)

  if (result.state === 'success') {
    // Envie o resultado ao seu backend, que cria a cobrança
    const charge = await createCharge({
      // ... outros dados da cobrança
      threeDS: result
    })
  }
} catch (error) {
  console.error('Erro na autenticação 3DS:', error)
}
```

### Estrutura do resultado

```typescript theme={null}
interface ChallengeResultResponse {
  type: 'full' | 'partial' | 'none'
  state: 'success' | 'failure' | 'unenrolled' | 'error' | 'unsupported_brand' | 'disabled'

  // Dados da autenticação (quando state === 'success')
  cryptogram?: string // CAVV/AAV
  directoryServerTransactionId?: string // DS Transaction ID
  threeDsServerTransactionId?: string // 3DS Server Transaction ID
  acsTransactionId?: string // ACS Transaction ID
  eci?: string // Electronic Commerce Indicator
  version?: string // Versão do protocolo 3DS
}
```

Os campos opcionais ficam ausentes quando não há valor; eles não vêm com `null`. Repasse o objeto ao backend como veio.

> [!NOTE]
>
> Se o comprador fechar o modal do desafio, `process()` não lança erro. Ele devolve `{ type: 'none', state: 'failure' }`. Trate esse resultado como autenticação não concluída e ofereça nova tentativa.

### Estados de autenticação

| Estado | Descrição | Ação recomendada |
| - | - | - |
| `success` | Autenticação bem-sucedida | Prosseguir com a cobrança |
| `failure` | O cliente falhou na autenticação | Recusar a transação ou pedir outra forma de pagamento |
| `unenrolled` | Cartão não inscrito no 3DS | Avaliar a sua política de risco |
| `error` | Erro no processo de autenticação | Tentar de novo ou usar outra forma de pagamento |
| `unsupported_brand` | A bandeira não suporta 3DS | Usar outra forma de pagamento |
| `disabled` | 3DS desabilitado para este cartão | Avaliar a sua política de risco |

## Customização do modal

### Container personalizado

Você pode indicar o seu próprio elemento para receber o iframe do desafio:

```javascript theme={null}
// Container personalizado
const customContainer = document.getElementById('my-3ds-container')

const result = await client.threeds.process({
  // ... dados da transação
  challengeContainer: customContainer
})
```

```html theme={null}
<div id="my-3ds-container" style="width: 500px; height: 500px;"></div>
```

### Desabilitar o modal automático

```javascript theme={null}
const result = await client.threeds.process(
  {
    // ... dados
    challengeContainer: document.getElementById('my-container')
  },
  {
    modal: false // Desabilita o modal automático
  }
)
```

> [!WARNING]
>
> Com `modal: false`, informe `challengeContainer`. Sem o container, o SDK não tem onde mostrar o desafio e devolve o erro "container is required".

### Customizar a aparência do modal

```javascript theme={null}
const result = await client.threeds.process(
  {
    /* ... dados */
  },
  {
    modal: {
      width: '800px',
      height: '700px',
      closeOnOverlayClick: false, // Impede fechar ao clicar fora (padrão: false)
      showCloseButton: false // Oculta o botão de fechar
    }
  }
)
```

## Exemplos de implementação

> [tab] React
>
> ```jsx theme={null}
> import { useState } from 'react'
> import { Client } from '@fastpaybr/security-sdk'
>
> function CheckoutForm() {
>   const [loading, setLoading] = useState(false)
>   const [result, setResult] = useState(null)
>
>   const handleSubmit = async (formData) => {
>     setLoading(true)
>
>     try {
>       const client = new Client({
>         credentials: { publicKey: process.env.REACT_APP_FINVIA_PUBLIC_KEY }
>       })
>
>       await client.initialize()
>
>       if (!client.isThreeDSAvailable()) {
>         throw new Error('3DS não disponível')
>       }
>
>       const threeDSResult = await client.threeds.process({
>         amount: formData.amount,
>         currency: 'BRL',
>         card: {
>           number: formData.cardNumber,
>           holderName: formData.cardHolder,
>           expirationMonth: formData.expMonth,
>           expirationYear: formData.expYear
>         },
>         customer: {
>           name: formData.customerName,
>           email: formData.customerEmail,
>           phone: formData.customerPhone
>         },
>         address: formData.address
>       })
>
>       if (threeDSResult.state === 'success') {
>         // Criar a cobrança com os dados 3DS (no seu backend)
>         const charge = await createCharge({
>           ...formData,
>           threeDS: threeDSResult
>         })
>
>         setResult(charge)
>       } else {
>         throw new Error(`Autenticação falhou: ${threeDSResult.state}`)
>       }
>     } catch (error) {
>       console.error('Erro:', error)
>       alert(error.message)
>     } finally {
>       setLoading(false)
>     }
>   }
>
>   return (
>     <form onSubmit={handleSubmit}>
>       {/* Campos do formulário */}
>       <button type='submit' disabled={loading}>
>         {loading ? 'Processando...' : 'Finalizar pagamento'}
>       </button>
>     </form>
>   )
> }
> ```

> [tab] JavaScript puro
>
> ```html theme={null}
> <!DOCTYPE html>
> <html>
>   <head>
>     <title>Checkout com 3DS</title>
>   </head>
>   <body>
>     <form id="checkout-form">
>       <!-- Campos do formulário -->
>       <button type="submit">Pagar</button>
>     </form>
>
>     <script src="https://js.fastpaybrasil.com/security-sdk.min.js"></script>
>     <script>
>       let client = null
>
>       async function initializeSDK() {
>         client = new FastPay.Client({
>           credentials: {
>             publicKey: 'pk_sua_chave_publica'
>           }
>         })
>
>         await client.initialize()
>
>         if (!client.isThreeDSAvailable()) {
>           alert('3DS não disponível no momento')
>         }
>       }
>
>       document.getElementById('checkout-form').addEventListener('submit', async (e) => {
>         e.preventDefault()
>
>         try {
>           const result = await client.threeds.process({
>             amount: 100.00,
>             currency: 'BRL',
>             card: {
>               number: document.getElementById('card-number').value,
>               holderName: document.getElementById('card-holder').value,
>               expirationMonth: document.getElementById('exp-month').value,
>               expirationYear: document.getElementById('exp-year').value
>             },
>             customer: {
>               name: document.getElementById('name').value,
>               email: document.getElementById('email').value,
>               phone: document.getElementById('phone').value
>             },
>             // address é opcional
>           })
>
>           if (result.state === 'success') {
>             // Enviar o resultado ao backend para criar a cobrança
>             console.log('3DS completo:', result)
>           }
>         } catch (error) {
>           console.error('Erro:', error)
>         }
>       })
>
>       // Inicializar ao carregar a página
>       initializeSDK()
>     </script>
>   </body>
> </html>
> ```

> [tab] Vue.js
>
> ```vue theme={null}
> <template>
>   <form @submit.prevent="handleSubmit">
>     <!-- Campos do formulário -->
>     <button type="submit" :disabled="loading">
>       {{ loading ? 'Processando...' : 'Pagar' }}
>     </button>
>   </form>
> </template>
>
> <script>
> import { Client } from '@fastpaybr/security-sdk'
>
> export default {
>   data() {
>     return {
>       loading: false,
>       client: null
>     }
>   },
>
>   async mounted() {
>     this.client = new Client({
>       credentials: {
>         publicKey: process.env.VUE_APP_FINVIA_PUBLIC_KEY
>       }
>     })
>
>     await this.client.initialize()
>   },
>
>   methods: {
>     async handleSubmit() {
>       if (!this.client.isThreeDSAvailable()) {
>         alert('3DS não disponível')
>         return
>       }
>
>       this.loading = true
>
>       try {
>         const result = await this.client.threeds.process({
>           // ... dados da transação
>         })
>
>         if (result.state === 'success') {
>           // Criar a cobrança (no seu backend)
>           await this.createCharge(result)
>         }
>       } catch (error) {
>         console.error('Erro:', error)
>       } finally {
>         this.loading = false
>       }
>     }
>   }
> }
> </script>
> ```

> [!TIP]
>
> **Para o desenvolvedor:** nos exemplos, `createCharge` representa uma chamada ao **seu** backend. É o backend que chama `POST /v1/charges` com a chave secreta.

## Métodos disponíveis

| Método | O que faz | Retorno |
| - | - | - |
| `client.initialize()` | Inicializa o SDK e carrega os provedores de 3DS disponíveis | `Promise<void>` |
| `client.isReady()` | Verifica se o SDK foi inicializado com sucesso | `boolean` |
| `client.isThreeDSAvailable()` | Verifica se o 3DS está disponível e pronto para uso | `boolean` |
| `client.threeds.process(request, options)` | Executa o fluxo completo de autenticação 3DS | `Promise<ChallengeResultResponse>` |

```javascript theme={null}
await client.initialize()
const ready = client.isReady()
const available = client.isThreeDSAvailable()
```

### Parâmetros de `process()`

```typescript theme={null}
interface ThreeDSProcessRequest {
  amount: number // Valor na moeda especificada
  currency: string // Código da moeda (ex.: BRL)
  card: {
    number: string // Número do cartão
    holderName?: string // Nome do titular
    expirationMonth: string // Mês de validade (1-12)
    expirationYear: string // Ano de validade (4 dígitos)
  }
  customer: {
    name: string // Nome completo
    email: string // E-mail do cliente
    phone: string // Telefone com código do país
  }
  address?: {
    street: string // Logradouro
    number: string // Número
    complement?: string // Complemento (opcional)
    zipCode: string // CEP
    neighborhood: string // Bairro
    city: string // Cidade
    state: string // Estado
    country: string // País (código ISO 3166-1 alpha-3)
  }
  challengeContainer?: HTMLElement // Container personalizado para o desafio
}

interface ThreeDSProcessOptions {
  fingerprintingTimeout?: number // Tempo limite do fingerprinting em ms (padrão: 60000)
  challengeTimeout?: number // Tempo limite do desafio em ms (padrão: 600000)
  modal?:
    | {
        width?: string // Largura do modal (padrão: '600px')
        height?: string // Altura do modal (padrão: '600px')
        closeOnOverlayClick?: boolean // Fechar ao clicar fora (padrão: false)
        showCloseButton?: boolean // Mostrar o botão X (padrão: true)
      }
    | false // false para desabilitar o modal automático
}
```

> [!NOTE]
>
> `customer` é obrigatório na tipagem e `address` é opcional. Nenhum dos dois vai para a API: o SDK envia só `amount`, `currency`, `card` e os dados do navegador, que ele coleta sozinho, inclusive o IP público do comprador. `process()` não recebe `installments`; as parcelas vão só na criação da cobrança. O tempo limite das requisições que o cliente do SDK faz à API aceita no máximo 30000 ms.

## Integração com a API de cobranças

Depois de obter o resultado do 3DS, envie-o ao seu backend, que cria a cobrança com o resultado em `paymentMethod.threeDS`:

```javascript theme={null}
// 1. No navegador: executar a autenticação 3DS
const threeDSResult = await client.threeds.process({
  amount: 100.00,
  currency: 'BRL',
  card: {
    /* ... */
  },
  customer: {
    /* ... */
  }
})

// 2. No backend: criar a cobrança incluindo os dados 3DS
const charge = await fetch('https://api-global.fastpaybrasil.com/v1/charges', {
  method: 'POST',
  headers: {
    'Authorization': `Basic ${credentials}`, // chave secreta, só no backend
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    amount: 100.00,
    currency: 'BRL',
    customer: {
      name: 'Joao Silva',
      email: 'joao@email.com',
      document: {
        type: 'cpf',
        id: '52998224725'
      },
      phone: '+5511987654321'
    },
    paymentMethod: {
      type: 'credit_card',
      number: '4111111111111111',
      holderName: 'Joao Silva',
      expirationMonth: '12',
      expirationYear: '2028',
      cvv: '123',
      installments: 1,
      // Incluir os dados 3DS
      threeDS: threeDSResult
    },
    items: [
      {
        title: 'Produto XYZ',
        type: 'digital',
        description: 'Descrição',
        unit_price: 100.00,
        quantity: 1
      }
    ]
  })
})

const result = await charge.json()
console.log('Cobrança criada:', result)
```

> [!NOTE]
>
> Os campos do cartão na cobrança seguem o contrato de `POST /v1/charges`: `number`, `holderName`, `expirationMonth`, `expirationYear`, `cvv`, `installments` e `threeDS`. O `items[].unit_price` usa a mesma unidade do `amount`: valor decimal em reais. Para `amount: 100.00`, use `unit_price: 100.00`. Os nomes `cardNumber` e `cardholderName` não existem no contrato.

### Cenários de validação

As validações abaixo só valem quando o 3DS é obrigatório para a sua conta. Nos outros casos, os dados 3DS são repassados sem validação.

| Situação | `reason` da cobrança recusada |
| - | - |
| Cobrança sem `threeDS` | `3ds_required: Não foi possível completar a autenticação 3DS obrigatória` |
| Falha de autenticação | `3ds_failed: The cardholder failed to authenticate. Please try again or use a different card` |
| Dados incompletos (`cryptogram` ou `eci` ausentes ou nulos) | `3ds_incomplete: Required authentication data (cryptogram or ECI) is missing` |
| Tudo certo | A cobrança segue normalmente |

### Exemplos de erros

```json theme={null}
{
  "id": "2vorkDcXyvzifL63YX09S9VqcnI",
  "status": "refused",
  "reason": "3ds_required: Não foi possível completar a autenticação 3DS obrigatória"
}
```

```json theme={null}
{
  "id": "2vorkDcXyvzifL63YX09S9VqcnI",
  "status": "refused",
  "reason": "3ds_failed: The cardholder failed to authenticate. Please try again or use a different card"
}
```

Os textos de `reason` aparecem aqui exatamente como a API devolve, sem ponto final. Trate a recusa pelo prefixo (`3ds_required`, `3ds_failed`, `3ds_incomplete`).

## Tratamento de erros

### Erros lançados pelo SDK

Os erros lançados pelo SDK são instâncias de `FastPayError`, nome que vem da marca anterior. Com `debug: true`, as mensagens de log no console começam com `[FastPay]`.

```javascript theme={null}
try {
  const result = await client.threeds.process({
    /* ... */
  })
} catch (error) {
  if (error.message.includes('not available')) {
    // O provedor de 3DS não está disponível
    console.error('3DS não disponível no momento')
  } else if (error.message.includes('timeout')) {
    // Tempo limite esgotado
    console.error('Tempo limite na autenticação')
  } else if (error.message.includes('container')) {
    // Container não informado quando necessário
    console.error('Container para o desafio não informado')
  } else {
    // Outros erros
    console.error('Erro desconhecido:', error)
  }
}
```

### Estados de erro no resultado

```javascript theme={null}
const result = await client.threeds.process({
  /* ... */
})

switch (result.state) {
  case 'success':
    // Autenticação bem-sucedida
    break

  case 'failure':
    // O cliente falhou na autenticação
    alert('A autenticação falhou. Tente de novo ou use outro cartão.')
    break

  case 'unenrolled':
    // Cartão não inscrito no 3DS
    // Decisão de negócio: aceitar ou recusar
    break

  case 'error':
    // Erro no processo
    alert('Erro na autenticação. Tente de novo.')
    break

  case 'unsupported_brand':
    // A bandeira não suporta 3DS
    alert('Este cartão não suporta 3D Secure.')
    break

  case 'disabled':
    // 3DS desabilitado
    alert('O 3D Secure está desabilitado para este cartão.')
    break
}
```

## Boas práticas

> [accordion] 1. Sempre inicialize antes de usar
>
> ```javascript theme={null}
> // Errado
> const result = await client.threeds.process({
>   /* ... */
> })
>
> // Correto
> await client.initialize()
> if (client.isThreeDSAvailable()) {
>   const result = await client.threeds.process({
>     /* ... */
>   })
> }
> ```

> [accordion] 2. Trate todos os estados
>
> ```javascript theme={null}
> const result = await client.threeds.process({
>   /* ... */
> })
>
> // Sempre trate todos os estados possíveis
> if (result.state === 'success') {
>   // Prosseguir com a cobrança
> } else {
>   // Lidar com a falha de acordo com a sua política de negócio
>   handleAuthenticationFailure(result.state)
> }
> ```

> [accordion] 3. Use variáveis de ambiente para a chave
>
> Evite a chave fixa no código:
>
> ```javascript theme={null}
> const client = new Client({
>   credentials: { publicKey: 'pk_abc123' }
> })
> ```
>
> Prefira a variável de ambiente do build:
>
> ```javascript theme={null}
> const client = new Client({
>   credentials: { publicKey: process.env.FINVIA_PUBLIC_KEY }
> })
> ```
>
> A chave pública pode ir para o navegador; a variável de ambiente facilita trocar entre a chave de teste e a de produção.

> [accordion] 4. Mostre o carregamento ao cliente
>
> ```javascript theme={null}
> // Mostrar feedback visual ao cliente
> setLoading(true)
> try {
>   const result = await client.threeds.process({
>     /* ... */
>   })
>   // Processar o resultado
> } finally {
>   setLoading(false)
> }
> ```

> [accordion] 5. Ative o log de depuração só em desenvolvimento
>
> ```javascript theme={null}
> const client = new Client({
>   credentials: { publicKey: 'your_key' },
>   debug: process.env.NODE_ENV === 'development' // Apenas em desenvolvimento
> })
> ```

> [accordion] 6. Ajuste os tempos limite só se necessário
>
> Os valores padrão são 60 segundos para o fingerprinting e 10 minutos para o desafio:
>
> ```javascript theme={null}
> const result = await client.threeds.process(
>   {
>     /* ... */
>   },
>   {
>     fingerprintingTimeout: 60000, // Padrão: 60s
>     challengeTimeout: 600000 // Padrão: 10min
>   }
> )
> ```
>
> * **Fingerprinting:** 60 segundos de espera pela verificação do dispositivo.
> * **Desafio:** 10 minutos para o comprador concluir a confirmação no banco. Um valor menor encerra antes a espera no checkout.
> * Se os tempos limite se repetem, investigue a causa antes de mudar o valor.

## Erros comuns

| Sintoma | Causa | Como resolver |
| - | - | - |
| O modal não aparece | O fluxo foi sem fricção (sem desafio), o modal foi bloqueado por bloqueador de pop-up ou o container personalizado está com `display:none` | Confira o resultado; se usar container, garanta que ele esteja visível |
| Tempo limite no fingerprinting | Internet lenta do cliente, problema no provedor de 3DS ou bloqueio de scripts no navegador | Investigue a causa antes de mudar o padrão de 60 segundos |
| `state` `failure` com `type` `none` | O comprador fechou o modal do desafio | Ofereça nova tentativa |
| Erro "3DS provider not available" | SDK não inicializado, nenhum provedor de 3DS configurado para a conta ou erro na inicialização | Chame `initialize()` e confira `isThreeDSAvailable()`. Persistindo, fale com a Finvia |
| Erro "container is required" | Modal desabilitado sem `challengeContainer` | Use o modal automático ou informe o container |
| Cobrança `refused` com `3ds_required` | Cobrança criada sem `threeDS` | Envie o resultado do SDK em `paymentMethod.threeDS` |
| Cobrança `refused` com `3ds_failed` | O titular não concluiu a autenticação | Peça para tentar de novo ou usar outro cartão |
| Dados do cartão inválidos | Número ou validade com erro de digitação | Valide os dados no formulário antes de chamar o SDK |

### Solução de problemas

> [accordion] Modal não aparece
>
> ```javascript theme={null}
> // Verificar se houve desafio
> console.log('Resultado:', result)
>
> // Garantir que o container está visível
> const container = document.getElementById('container')
> container.style.display = 'block'
> ```

> [accordion] Tempo limite no fingerprinting
>
> O padrão é 60 segundos. Tempos limite frequentes indicam problemas de rede, de bloqueio de scripts ou no provedor de 3DS, que precisam ser investigados. Ative `debug: true` em desenvolvimento e procure no console as mensagens com o prefixo `[FastPay]`.

> [accordion] Erro 3DS provider not available
>
> ```javascript theme={null}
> await client.initialize()
>
> if (!client.isThreeDSAvailable()) {
>   console.error('3DS não disponível. Verifique a configuração da conta.')
>   // Implementar alternativa ou avisar o cliente
> }
> ```

> [accordion] Erro container is required
>
> Opção 1: use o modal automático (padrão).
>
> ```javascript theme={null}
> const result = await client.threeds.process({
>   /* ... */
> })
> ```
>
> Opção 2: informe o container se o modal estiver desabilitado.
>
> ```javascript theme={null}
> const result = await client.threeds.process(
>   {
>     /* ... */
>     challengeContainer: document.getElementById('my-container')
>   },
>   { modal: false }
> )
> ```

> [accordion] Dados do cartão inválidos
>
> ```javascript theme={null}
> // Validar os dados antes de chamar o SDK
> function validateCard(cardNumber, month, year) {
>   if (!isValidCardNumber(cardNumber)) {
>     alert('Número do cartão inválido')
>     return false
>   }
>
>   if (!isValidExpiration(month, year)) {
>     alert('Data de validade inválida')
>     return false
>   }
>
>   return true
> }
> ```

## Perguntas frequentes

> [accordion] Qual chave uso no SDK?
>
> A chave pública (`pk_`). Ela foi feita para o navegador. A chave secreta fica só no backend, que cria a cobrança.

> [accordion] Preciso enviar o CVV ao SDK?
>
> Não. O `process()` recebe número, nome, mês e ano do cartão. O CVV vai só na criação da cobrança, feita pelo seu backend.

> [accordion] O SDK cria a cobrança?
>
> Não. O SDK só autentica. A cobrança é criada pelo seu backend com `POST /v1/charges`, levando o resultado em `paymentMethod.threeDS`.

> [accordion] O que acontece se o comprador fechar o modal?
>
> `process()` não lança erro. Ele devolve `{ type: 'none', state: 'failure' }`. Não crie a cobrança com esse resultado; ofereça nova tentativa.

> [accordion] Por que o pacote e a classe de erro usam o nome anterior da marca?
>
> O SDK foi publicado com o nome anterior da marca. O pacote `@fastpaybr/security-sdk`, o global `FastPay` do CDN, a classe de erro `FastPayError` e o prefixo `[FastPay]` nos logs continuam assim até uma nova versão do SDK.

> [accordion] O que fazer quando o estado é unenrolled ou disabled?
>
> A decisão é da sua política de risco. Se a sua conta exige 3DS, só `success` permite seguir com a cobrança.

## Como testar

O 3D Secure é homologado em um cenário específico da sua conta, conforme o [roteiro de homologação](https://docs.fastpaybrasil.com/homologacao/roteiro.md). No teste, inclua: autenticação com `state` `success` seguida de cobrança `paid`, cobrança sem `threeDS` (recusa com `3ds_required`) e o tratamento de cada `state` diferente de `success` no seu checkout.

## Veja também

> [card] [3D Secure: visão geral](https://docs.fastpaybrasil.com/guias/3d-secure/visao-geral.md)
>
> Comparativo das três formas de integrar.

> [card] [3DS via API](https://docs.fastpaybrasil.com/guias/3d-secure/via-api.md)
>
> As mesmas etapas, chamadas uma a uma.

> [card] [Criar uma cobrança](https://docs.fastpaybrasil.com/referencia/cobrancas/criar.md)
>
> Campo `paymentMethod.threeDS`.

> [card] [Cartão de crédito](https://docs.fastpaybrasil.com/guias/cobrancas/cartao-de-credito.md)
>
> Cobrança com cartão digitado.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.