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

# Iniciar autenticação 3DS

> Cria uma autenticação 3D Secure para um cartão e devolve o primeiro passo: coleta de dados do navegador ou desafio do banco.

O 3D Secure (3DS) é a verificação em que o banco emissor do cartão confirma que quem está comprando é o titular. Esta rota abre essa verificação: você envia o valor, o cartão e os dados do navegador, e a Finvia devolve um `authenticationId` e o próximo passo. Às vezes o banco aprova sem interagir com o comprador (fluxo sem atrito, ou frictionless). Outras vezes ele pede um desafio: o comprador se autentica diretamente no banco emissor, em uma tela exibida dentro do seu checkout.

Esta é a primeira chamada do **3DS via API**, o fluxo em que você conduz cada etapa. Se prefere que a Finvia conduza tudo, use o [3DS gerenciado](https://docs.fastpaybrasil.com/guias/3d-secure/gerenciado.md). Se usa o SDK de segurança, ele faz estas chamadas por você ([SDK de 3D Secure](https://docs.fastpaybrasil.com/guias/3d-secure/sdk.md)).

## Quando usar

| Situação | Caminho |
| - | - |
| Você quer controlar cada etapa do 3DS no seu front-end | Esta rota, seguida de [enviar](https://docs.fastpaybrasil.com/referencia/3d-secure/enviar.md) e [resultado do desafio](https://docs.fastpaybrasil.com/referencia/3d-secure/resultado-desafio.md) |
| Você quer o fluxo pronto no navegador, com modal | [SDK de 3D Secure](https://docs.fastpaybrasil.com/guias/3d-secure/sdk.md) |
| Você quer que a Finvia conduza a autenticação a partir da cobrança | `threeDSMode` `managed` em [`POST /v1/charges`](https://docs.fastpaybrasil.com/referencia/cobrancas/criar) |
| Pagamento com Apple Pay | Não se aplica: a autenticação já vem no token do Apple Pay |

> [!NOTE]
>
> **Para o negócio:** quando a configuração da sua conta exige 3DS, uma cobrança de cartão sem autenticação bem-sucedida é recusada. O 3DS acrescenta uma etapa ao checkout e, em alguns casos, um desafio para o comprador. Decida com o time técnico qual dos três caminhos (gerenciado, SDK ou via API) combina com o seu checkout.

## Antes de chamar

* Use a **chave pública** (`pk_`, ou `pk_test_` no sandbox) no cabeçalho Basic, como usuário e com senha vazia. Esta rota foi feita para ser chamada do navegador, onde a chave secreta nunca pode aparecer.
* A conta precisa ter um provedor de 3DS configurado. Sem ele, a rota responde `404` com a mensagem `No 3DS provider configured for this gateway`.
* Colete os dados do navegador do comprador (objeto `browser`).

```text theme={null}
Authorization: Basic base64(pk_sua_chave_publica:)
```

> [!WARNING]
>
> Nunca use a chave secreta (`sk_`) no front-end. As rotas de 3D Secure usam a chave pública.

> [!NOTE]
>
> O contrato desta rota declara a autenticação `basic` e diz, na descrição da rota, que a chave usada é a pública (`pk_`) como usuário do Basic. A descrição genérica do esquema `basic` no contrato fala em chave secreta. Siga a descrição da rota: chave pública.

## Corpo da requisição

Campos obrigatórios: `amount`, `currency`, `card` e `browser`.

**amount** `number` *required*

Valor da transação na moeda informada, em reais quando a moeda é `BRL`. Ex.: `100`.

**currency** `string` *required*

Código da moeda no padrão ISO 4217. Ex.: `BRL`.

**card** `object` *required*

Cartão que será autenticado.

**propriedades**

**number** `string` *required*

Número do cartão. Ex.: `4111111111111111`.

**holderName** `string`

Nome do titular. Ex.: `John Doe`.

**expirationMonth** `string` *required*

Mês de validade, de 1 a 12, com 1 ou 2 dígitos. Ex.: `12`.

**expirationYear** `string` *required*

Ano de validade com 4 dígitos. Ex.: `2025`.

**browser** `object` *required*

Dados do navegador do comprador, usados pelo banco na análise (schema `BrowserInfo`).

**propriedades**

**userAgent** `string` *required*

User agent do navegador. Ex.: `Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36`.

**ipAddress** `string` *required*

IP do comprador. Ex.: `177.128.144.97`.

**acceptHeader** `string`

Valor do cabeçalho Accept do navegador. Ex.: `text/html,application/xhtml+xml`.

**language** `string`

Idioma do navegador. Ex.: `pt-BR`.

**timezoneOffset** `integer`

Diferença do fuso em minutos em relação ao UTC. Ex.: `-180`.

**javascriptEnabled** `boolean`

Se o JavaScript está habilitado. Ex.: `true`.

**javaEnabled** `boolean`

Se o Java está habilitado. Ex.: `false`.

**screenWidth** `integer`

Largura da tela em pixels. Ex.: `1920`.

**screenHeight** `integer`

Altura da tela em pixels. Ex.: `1080`.

**colorDepth** `integer`

Profundidade de cor da tela, em bits. Ex.: `24`.

> [!TIP]
>
> **Para o desenvolvedor:** quase todos os campos de `browser` saem direto do JavaScript da página: `navigator.userAgent`, `navigator.language`, `screen.width`, `screen.height` e `screen.colorDepth`. Para `timezoneOffset`, inverta o sinal de `new Date().getTimezoneOffset()`: no horário de Brasília ele devolve `180`, e o exemplo do contrato é `-180`. O `ipAddress` precisa vir do seu servidor, que enxerga o IP de quem fez a requisição.

## Respostas

**authenticationId** `string`

Identificador da autenticação 3DS. Guarde: ele é enviado em [enviar](https://docs.fastpaybrasil.com/referencia/3d-secure/enviar.md), [cancelar](https://docs.fastpaybrasil.com/referencia/3d-secure/cancelar.md) e [resultado do desafio](https://docs.fastpaybrasil.com/referencia/3d-secure/resultado-desafio.md). O valor é gerado pelo provedor de 3DS e deve ser tratado como texto opaco: repasse exatamente o que recebeu, sem validar prefixo nem tamanho. Ex.: `tdsa_1QmCRMJM0r9zBvr4OVmMRa6X`.

**status** `string`

Situação atual da autenticação: `requires_submission`, `requires_challenge`, `succeeded`, `failed`, `error`, `canceled` ou `processing`. Ex.: `requires_submission`.

**fingerprintingUrl** `string | null`

URL para carregar em um iframe **oculto**, que coleta dados do dispositivo (fingerprinting). Ao terminar, a página envia por `postMessage` a mensagem `{ "type": "3ds-authentication-fingerprinting-complete", "fingerprintingResult": "<Base64>" }`. Depois chame [`POST /v1/three-ds/submit`](https://docs.fastpaybrasil.com/referencia/3d-secure/enviar). Ex.: `https://provedor-3ds.exemplo.com/fingerprint/tdsa_1QmCRMJM0r9zBvr4OVmMRa6X`.

**challengeUrl** `string | null`

URL para carregar em um iframe **visível** quando o `status` é `requires_challenge`. É nesse iframe que o comprador faz o desafio do banco. Ao final, a página envia por `postMessage` a mensagem `{ "type": "3ds-authentication-challenge-complete", "status": "succeeded" }` (ou `failed`, `error`, `canceled`). Ex.: `https://provedor-3ds.exemplo.com/challenge/tdsa_1QmCRMJM0r9zBvr4OVmMRa6X`.

**outcome** `string | null`

Resultado da autenticação. Só vem preenchido em estados finais. Valores: `authenticated`, `informational`, `attempt_acknowledged`, `rejected`, `denied`, `abandoned`, `not_supported`, `processing_error`, `internal_error`, `canceled`. Ex.: `authenticated`.

> [!NOTE]
>
> As URLs de `fingerprintingUrl` e `challengeUrl` são da página do provedor de 3DS, e o host pode mudar. Não fixe o domínio no código. Ao receber uma mensagem, confira se `event.source === iframe.contentWindow` e se `event.data.type` é o tipo esperado. O fluxo completo, com exemplos, está no guia [3DS via API](https://docs.fastpaybrasil.com/guias/3d-secure/via-api.md).

### O que fazer com cada status

| `status` | Próximo passo |
| - | - |
| `requires_submission` | Se veio `fingerprintingUrl`, carregue em iframe oculto e espere a mensagem de fim, por cerca de 60 segundos. Depois chame [enviar](https://docs.fastpaybrasil.com/referencia/3d-secure/enviar.md), com `fingerprintingResult` se ele chegou e sem ele se não chegou. Sem `fingerprintingUrl`, chame enviar direto |
| `requires_challenge` | Carregue `challengeUrl` em iframe visível. Depois da mensagem de fim do desafio, chame [resultado do desafio](https://docs.fastpaybrasil.com/referencia/3d-secure/resultado-desafio.md) |
| `processing` | A autenticação ainda está em processamento |
| `succeeded` | Autenticação concluída. Busque o resultado em [resultado do desafio](https://docs.fastpaybrasil.com/referencia/3d-secure/resultado-desafio.md) para criar a cobrança |
| `failed` / `error` | Estado final. Chame [resultado do desafio](https://docs.fastpaybrasil.com/referencia/3d-secure/resultado-desafio.md) para obter o `state` e não siga com a cobrança autenticada |
| `canceled` | A autenticação foi cancelada |

| HTTP | Significado | Mensagem (`message`) |
| - | - | - |
| `200` | Autenticação iniciada | |
| `401` | Chave pública inválida | `Unauthorized` |
| `404` | Nenhum provedor de 3DS configurado para a conta | `No 3DS provider configured for this gateway` |

Trate o erro pelo código HTTP, não pelo texto da mensagem.

O corpo de erro tem três campos:

**statusCode** `integer`

Código HTTP.

**message** `string`

Mensagem descritiva do erro.

**error** `string`

Tipo do erro.

## Fluxo completo do 3DS via API

**1. Inicie a autenticação**

Chame esta rota com o cartão, o valor e os dados do navegador. Guarde o `authenticationId`.

**2. Faça o fingerprinting, se pedido**

Se a resposta trouxer `fingerprintingUrl`, carregue a URL em um iframe oculto e espere a mensagem `3ds-authentication-fingerprinting-complete`, com o `fingerprintingResult`.

**3. Envie a autenticação**

Chame [`POST /v1/three-ds/submit`](https://docs.fastpaybrasil.com/referencia/3d-secure/enviar) com o `authenticationId` e, se houver, o `fingerprintingResult`.

**4. Mostre o desafio, se pedido**

Se o `status` for `requires_challenge`, carregue `challengeUrl` em um iframe visível para o comprador concluir o desafio e espere a mensagem `3ds-authentication-challenge-complete`.

**5. Busque o resultado**

Chame [`POST /v1/three-ds/challenge-result`](https://docs.fastpaybrasil.com/referencia/3d-secure/resultado-desafio) depois do fim do desafio, ou quando a autenticação já estiver em estado final. A resposta traz o criptograma e os identificadores da autenticação.

**6. Crie a cobrança**

Envie o resultado no campo `paymentMethod.threeDS` de [`POST /v1/charges`](https://docs.fastpaybrasil.com/referencia/cobrancas/criar), chamado do seu servidor com a chave secreta.

## Erros comuns

| Sintoma | Causa | Como resolver |
| - | - | - |
| `404` `No 3DS provider configured for this gateway` | A conta não tem provedor de 3DS configurado | Fale com o time Finvia para habilitar o 3DS |
| `401` `Unauthorized` | Chave pública inválida, de outro ambiente, ou chave secreta no lugar | Use a `pk_` (ou `pk_test_`) da conta |
| Chave secreta exposta no navegador | A chamada foi feita com `sk_` no front-end | Troque pela chave `pk_` e gere uma nova chave secreta |
| Iframe de fingerprinting não devolve nada | Listener de `postMessage` não registrado antes de carregar o iframe | Registre o listener e só depois carregue a `fingerprintingUrl` |

```http REST (JSON) theme={null}
POST /v1/three-ds/authenticate HTTP/1.1
Host: api-global.fastpaybrasil.com
Authorization: Basic <base64 de "SUA_CHAVE_PUBLICA:">
Content-Type: application/json

{
  "amount": 100,
  "currency": "BRL",
  "card": {
    "number": "4111111111111111",
    "holderName": "Joao Silva",
    "expirationMonth": "12",
    "expirationYear": "2025"
  },
  "browser": {
    "userAgent": "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36",
    "ipAddress": "177.128.144.97",
    "acceptHeader": "text/html,application/xhtml+xml",
    "language": "pt-BR",
    "timezoneOffset": -180,
    "javascriptEnabled": true,
    "javaEnabled": false,
    "screenWidth": 1920,
    "screenHeight": 1080,
    "colorDepth": 24
  }
}
```

```bash cURL theme={null}
curl -X POST "https://api-global.fastpaybrasil.com/v1/three-ds/authenticate" \
  -u "$FINVIA_PUBLIC_KEY:" \
  -H "Content-Type: application/json" \
  -d '{
    "amount": 100,
    "currency": "BRL",
    "card": {
      "number": "4111111111111111",
      "holderName": "Joao Silva",
      "expirationMonth": "12",
      "expirationYear": "2025"
    },
    "browser": {
      "userAgent": "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36",
      "ipAddress": "177.128.144.97",
      "acceptHeader": "text/html,application/xhtml+xml",
      "language": "pt-BR",
      "timezoneOffset": -180,
      "javascriptEnabled": true,
      "javaEnabled": false,
      "screenWidth": 1920,
      "screenHeight": 1080,
      "colorDepth": 24
    }
  }'
```

```javascript Navegador theme={null}
// Chave pública: pode ficar no front-end
const credentials = btoa(`${FINVIA_PUBLIC_KEY}:`);

const response = await fetch('https://api-global.fastpaybrasil.com/v1/three-ds/authenticate', {
  method: 'POST',
  headers: {
    Authorization: `Basic ${credentials}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    amount: 100,
    currency: 'BRL',
    card: { number: cardNumber, holderName, expirationMonth: '12', expirationYear: '2025' },
    browser: {
      userAgent: navigator.userAgent,
      ipAddress: ipDoComprador, // obtido pelo seu servidor
      language: navigator.language,
      timezoneOffset: -new Date().getTimezoneOffset(),
      javascriptEnabled: true,
      javaEnabled: false,
      screenWidth: screen.width,
      screenHeight: screen.height,
      colorDepth: screen.colorDepth,
    },
  }),
});

const auth = await response.json();
```

```json 200 Fingerprinting theme={null}
{
  "authenticationId": "tdsa_1QmCRMJM0r9zBvr4OVmMRa6X",
  "status": "requires_submission",
  "fingerprintingUrl": "https://provedor-3ds.exemplo.com/fingerprint/tdsa_1QmCRMJM0r9zBvr4OVmMRa6X",
  "challengeUrl": null,
  "outcome": null
}
```

```json 200 Desafio theme={null}
{
  "authenticationId": "tdsa_1QmCRMJM0r9zBvr4OVmMRa6X",
  "status": "requires_challenge",
  "fingerprintingUrl": null,
  "challengeUrl": "https://provedor-3ds.exemplo.com/challenge/tdsa_1QmCRMJM0r9zBvr4OVmMRa6X",
  "outcome": null
}
```

```json 404 theme={null}
{
  "statusCode": 404,
  "message": "No 3DS provider configured for this gateway",
  "error": "Not Found"
}
```

## Veja também

> [card] [3DS via API](https://docs.fastpaybrasil.com/guias/3d-secure/via-api.md)
>
> Guia do fluxo completo com as rotas de 3DS.

> [card] [Enviar autenticação](https://docs.fastpaybrasil.com/referencia/3d-secure/enviar.md)
>
> Próximo passo depois do fingerprinting.

> [card] [Visão geral do 3D Secure](https://docs.fastpaybrasil.com/guias/3d-secure/visao-geral.md)
>
> Gerenciado, SDK ou via API.

> [card] [SDK de 3D Secure](https://docs.fastpaybrasil.com/guias/3d-secure/sdk.md)
>
> O mesmo fluxo com o SDK no navegador.


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