> ## 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.

# 3D Secure: visão geral

> O que é a autenticação 3D Secure, as três formas de integrar na Finvia e como escolher entre elas.

O 3D Secure (3DS) é uma etapa de autenticação do titular do cartão feita pelo banco emissor durante a compra online. Antes de a cobrança ser processada, o banco confere se quem está comprando é mesmo o dono do cartão. Às vezes isso acontece sem o cliente perceber (fluxo sem fricção, *frictionless*); outras vezes o banco pede uma confirmação, como um código enviado por SMS ou uma aprovação no app do banco (desafio, *challenge*).

> [!NOTE]
>
> **Para o negócio:** o 3DS acrescenta uma confirmação do titular do cartão na compra. Quando a configuração da sua conta exige 3DS, a cobrança de cartão só segue com a autenticação bem-sucedida (`state` `success`); sem ela, a cobrança é recusada. Converse com o time Finvia para saber se o 3DS é exigido no seu perfil.

## Quando usar

| Situação | Recomendação |
| - | - |
| A configuração da sua conta exige 3DS | Integre uma das três formas desta página. Sem 3DS, a cobrança é recusada com `3ds_required` |
| Checkout web com cartão digitado ou cartão salvo | Qualquer uma das três formas |
| Apple Pay | Não se aplica: a autenticação já vem no token |
| Pix | Não se aplica: o 3DS é só para cartão |

## Termos que aparecem nesta seção

| Termo | O que é |
| - | - |
| Emissor / ACS | O banco que emitiu o cartão e o servidor dele que autentica o titular (ACS) |
| Fingerprinting | Coleta de dados do navegador do cliente, feita em um iframe oculto, para o emissor avaliar o risco |
| Frictionless | Autenticação aprovada sem interação do cliente |
| Challenge (desafio) | O emissor pede uma confirmação ao cliente, em uma janela visível |
| Criptograma (`cryptogram`) | Valor de autenticação (CAVV) gerado quando a autenticação dá certo |
| ECI | Electronic Commerce Indicator, código que indica o resultado da autenticação |

O desenho abaixo mostra o caminho de uma autenticação 3DS, com e sem desafio, e o que acontece com a cobrança em cada resultado.

```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}}}%%
flowchart TB
    INI["Envio do cartão e dos<br/>dados do navegador"]:::lojista
    ACS["Banco emissor (ACS)<br/>avalia o risco"]:::externo
    Q1{"O emissor pede<br/>confirmação?"}:::decisao
    CH["Desafio (challenge)<br/>código por SMS ou<br/>aprovação no app do banco"]:::alerta
    SUC(["state success<br/>com cryptogram e eci"]):::ok
    OUT(["Outro state<br/>failure, unenrolled, error..."]):::erro
    Q3{"3DS obrigatório<br/>na sua conta?"}:::decisao
    SEGUE(["Cobrança segue<br/>normalmente"]):::ok
    REC(["Cobrança recusada<br/>reason começa com 3ds_"]):::erro
    INI -->|"fingerprinting em iframe<br/>oculto, se o emissor pedir"| ACS
    ACS --> Q1
    Q1 ==>|"não: sem atrito<br/>(frictionless)"| SUC
    Q1 -->|"sim"| CH
    CH -->|"titular confirmou"| SUC
    CH -->|"não confirmou"| OUT
    ACS -.->|"cartão não inscrito<br/>ou erro"| OUT
    SUC ==> SEGUE
    OUT --> Q3
    Q3 -->|"sim"| REC
    Q3 -->|"não, dados repassados<br/>sem validação"| SEGUE
    classDef lojista fill:#F3F5F8,stroke:#475467,stroke-width:1.5px,color:#101828
    classDef externo fill:#F4F0FF,stroke:#6D28D9,stroke-width:1.5px,color:#3B1C80
    classDef ok fill:#E8F7EE,stroke:#15803D,stroke-width:1.5px,color:#0B4A23
    classDef erro fill:#FDECEC,stroke:#B42318,stroke-width:1.5px,color:#7A1209
    classDef alerta fill:#FFF6E5,stroke:#B45309,stroke-width:1.5px,color:#5C3D00
    classDef decisao fill:#FFFFFF,stroke:#017AFF,stroke-width:2px,color:#070D15
```

O fingerprinting e o desafio só acontecem quando o emissor pede. No 3DS gerenciado, a página da Finvia conduz essas telas. No SDK, o próprio SDK faz isso dentro do seu checkout. No 3DS via API, quem exibe os iframes é o seu checkout.

## As três formas de integrar

> [card] [3DS gerenciado](https://docs.fastpaybrasil.com/guias/3d-secure/gerenciado.md)
>
> Você cria a cobrança com `threeDSMode: "managed"`, abre a `authenticationUrl` para o comprador e acompanha o resultado.

> [card] [SDK de segurança](https://docs.fastpaybrasil.com/guias/3d-secure/sdk.md)
>
> Um SDK no front-end faz a autenticação completa e devolve o resultado para a cobrança.

> [card] [3DS via API](https://docs.fastpaybrasil.com/guias/3d-secure/via-api.md)
>
> Você conduz cada etapa pelas rotas de 3DS e monta o objeto `threeDS`.

### Como cada forma funciona

**3DS gerenciado.** Você cria a cobrança normalmente, com `paymentMethod.threeDSMode` `managed` e o objeto `browser` com os dados do navegador. Se o banco aprova sem interação, a resposta já traz o status final. Se o banco pede verificação ou desafio, a cobrança fica em `authentication_required` e a resposta traz a `authenticationUrl`, que você abre para o comprador (modal, iframe ou nova aba). A página da Finvia conduz a autenticação e conclui a cobrança, e o resultado chega pelos webhooks ou por `GET /v1/charges/{id}`. O comprador não volta automaticamente para a loja ao final.

**SDK de segurança.** No seu checkout, o SDK `@fastpaybr/security-sdk` (publicado com o nome anterior da marca) faz o fluxo inteiro com o método `process()`: coleta de dados do navegador, desafio em um modal quando o emissor pede, e resultado final. Você envia esse resultado no campo `paymentMethod.threeDS` de `POST /v1/charges`.

**3DS via API (BYO, *bring your own*).** Você chama as rotas de 3DS uma a uma (`POST /v1/three-ds/authenticate`, `submit`, `challenge-result`), exibe os iframes de fingerprinting e de desafio no seu front-end e monta o objeto `threeDS` para a cobrança.

### Comparativo

| | 3DS gerenciado | SDK de segurança | 3DS via API |
| - | - | - | - |
| Esforço de integração | Menor: abrir a `authenticationUrl` e acompanhar o resultado por webhook ou consulta | Baixo: instalar o SDK e chamar `process()` | Maior: você controla iframes, `postMessage` e cada chamada |
| Controle da experiência | Menor | Médio: modal configurável ou container próprio | Total |
| Quando a cobrança é criada | Antes da autenticação | Depois da autenticação | Depois da autenticação |
| Onde vai o resultado | A página de autenticação retoma a cobrança; você recebe o resultado por webhook ou `GET /v1/charges/{id}` | `paymentMethod.threeDS` em `POST /v1/charges` | `paymentMethod.threeDS` em `POST /v1/charges` |
| Chave usada no front-end | Nenhuma: a página de autenticação já traz o que precisa | Pública (`pk_`) no SDK | Pública (`pk_`) nas rotas de 3DS |
| Volta para a loja ao final | Não há | O fluxo roda dentro do seu checkout | O fluxo roda dentro do seu checkout |
| Indicado para | Quem quer delegar a condução do 3DS à Finvia | A maioria dos checkouts web | Checkouts com interface própria ou requisitos específicos |

> [!TIP]
>
> **Para o desenvolvedor:** em todas as formas, a cobrança continua sendo criada pelo seu backend com a chave secreta. A chave pública (`pk_`) é usada apenas nas etapas de autenticação que rodam no navegador.

Para escolher a forma de integrar, siga as perguntas do desenho abaixo.

```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}}}%%
flowchart TB
    INI(["Cobrança com cartão<br/>que vai usar 3DS"]):::neutro
    Q0{"É Pix ou<br/>Apple Pay?"}:::decisao
    NA["3DS não se aplica"]:::neutro
    Q1{"Quer delegar à Finvia<br/>as telas do 3DS?"}:::decisao
    GER["<b>3DS gerenciado</b><br/>threeDSMode managed<br/>cobrança criada antes"]:::neutro
    Q2{"Precisa controlar cada<br/>tela e cada chamada?"}:::decisao
    API["<b>3DS via API</b><br/>rotas /v1/three-ds/<br/>cobrança criada depois"]:::neutro
    SDK["<b>SDK de segurança</b><br/>process() no front-end<br/>cobrança criada depois"]:::neutro
    INI --> Q0
    Q0 -->|"sim"| NA
    Q0 -->|"não"| Q1
    Q1 -->|"sim, e acompanho<br/>por webhook"| GER
    Q1 -->|"não"| Q2
    Q2 -->|"sim"| API
    Q2 ==>|"não, a maioria<br/>dos checkouts"| SDK
    classDef decisao fill:#FFFFFF,stroke:#017AFF,stroke-width:2px,color:#070D15
    classDef neutro fill:#FFFFFF,stroke:#B8C2D1,stroke-width:1.5px,color:#344054
```

Nas três formas, a cobrança é criada pelo seu backend com a chave secreta. A diferença está em quem conduz as telas e em que momento a cobrança nasce.

## Resultado da autenticação

No SDK e no 3DS via API, o resultado de uma autenticação 3DS é o objeto `threeDS` (schema `CreditCardThreeDS`), que você envia em `POST /v1/charges`. Os campos `type` e `state` são obrigatórios. Nos demais, omita o campo quando não tiver valor e não envie `null`.

| Campo | O que é |
| - | - |
| `type` | Tipo de autenticação (ex.: `full`) |
| `state` | Resultado: `success`, `failure`, `unenrolled`, `error`, `unsupported_brand` ou `disabled` |
| `cryptogram` | CAVV em Base64. Com `state` `success`, é na prática obrigatório |
| `eci` | Electronic Commerce Indicator. Com `state` `success`, é na prática obrigatório |
| `version` | Versão do protocolo (ex.: `2.1.0`, `2.2.0`) |
| `directoryServerTransactionId` | ID da transação no Directory Server (bandeira) |
| `threeDsServerTransactionId` | ID da transação no 3DS Server |
| `acsTransactionId` | ID da transação no ACS (emissor) |

> [!NOTE]
>
> O schema também lista `mode`, `deviceData` e `challenge.returnUrl`. Não envie esses campos: `mode` é de uso interno, e `deviceData` e `challenge.returnUrl` não são lidos no 3DS da Finvia.

### Estados (`state`)

| Estado | Significado | 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 |

> [!WARNING]
>
> Quando o 3DS é exigido pela configuração da sua conta, só `state` `success` permite que a cobrança siga. Qualquer outro estado leva à recusa.

### ECI

| Valor | Significado |
| - | - |
| `05` | Autenticado |
| `06` | Tentativa de autenticação |
| `07` | Não autenticado |

Esses são os valores comuns citados no contrato.

## O que acontece se o 3DS faltar

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

| Situação | `reason` da cobrança recusada |
| - | - |
| 3DS não fornecido, ou o 3DS gerenciado não pôde ser feito (sem `browser` ou falha do serviço de 3DS) | `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` |
| `cryptogram` ou `eci` ausentes ou nulos | `3ds_incomplete: Required authentication data (cryptogram or ECI) is missing` |
| Autenticação sem sucesso no 3DS gerenciado | `3ds_<estado>: Authentication did not succeed` |
| Tudo certo | A cobrança segue normalmente |

Trecho da resposta de uma cobrança recusada por falta de 3DS:

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

A recusa vem na resposta da criação da cobrança e também no webhook `charge.refused` (ou `charge.failed`), enviado aos seus endpoints e à `postbackUrl` da cobrança ([Webhooks de cobrança](https://docs.fastpaybrasil.com/guias/webhooks/cobranca.md)). O texto de `reason` mistura português e inglês e aparece aqui exatamente como a API devolve. Trate pelo prefixo (`3ds_required`, `3ds_failed`, `3ds_incomplete`).

## Perguntas frequentes

> [accordion] Qual forma devo escolher?
>
> Se você quer usar um componente pronto no navegador, que conduz fingerprinting e desafio, use o SDK. Se você quer delegar as telas de autenticação à Finvia e pode acompanhar o resultado por webhook, sem volta automática do comprador para a loja, use o 3DS gerenciado. Se precisa controlar cada tela e cada etapa, use o 3DS via API.

> [accordion] Preciso de 3DS no Apple Pay?
>
> Não. No Apple Pay a autenticação já vem no token, e o 3DS não se aplica.

> [accordion] O cliente sempre vê uma tela do banco?
>
> Não. No fluxo sem fricção (`frictionless`), o emissor aprova sem interação. O desafio (`challenge`) só aparece quando o emissor pede.

> [accordion] Posso usar 3DS com cartão salvo?
>
> Sim. A variante de cartão salvo aceita `threeDSMode`, `browser` e `threeDS`, com as mesmas regras do cartão digitado.

## Como testar

O [roteiro de homologação](https://docs.fastpaybrasil.com/homologacao/roteiro.md) informa que o 3D Secure, quando se aplica ao seu perfil, é coberto em um cenário específico da sua conta. Combine esse cenário com o time Finvia e, nos testes de cartão (**CHG-01** a **CHG-03**), confira também os casos `3ds_required` e de `state` diferente de `success`.

## Veja também

> [card] [3DS gerenciado](https://docs.fastpaybrasil.com/guias/3d-secure/gerenciado.md)
>
> Fluxo com `threeDSMode` e `resume-3ds`.

> [card] [SDK de segurança](https://docs.fastpaybrasil.com/guias/3d-secure/sdk.md)
>
> Autenticação completa no front-end.

> [card] [3DS via API](https://docs.fastpaybrasil.com/guias/3d-secure/via-api.md)
>
> Rotas de autenticação passo a passo.

> [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.