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

# Enviar autenticação 3DS

> Envia a autenticação 3DS ao banco depois da coleta de dados do navegador e devolve o novo status, com a URL do desafio quando o banco pedir.

Depois de iniciar a autenticação e, se pedido, coletar os dados do dispositivo (fingerprinting), esta rota envia a autenticação para o banco emissor decidir. A resposta diz se o banco aprovou sem interação, se ele quer um desafio do comprador ou se a autenticação falhou.

É a segunda chamada do **3DS via API**. A primeira é [Iniciar autenticação](https://docs.fastpaybrasil.com/referencia/3d-secure/iniciar.md).

## Quando usar

| Situação | O que enviar |
| - | - |
| A inicialização trouxe `fingerprintingUrl` e o iframe devolveu o resultado | `authenticationId` e `fingerprintingResult` |
| A inicialização veio com `status` `requires_submission`, sem `fingerprintingUrl` | Só o `authenticationId` |
| A inicialização já veio com `requires_challenge` | Não precisa desta rota. Mostre o desafio e vá para [resultado do desafio](https://docs.fastpaybrasil.com/referencia/3d-secure/resultado-desafio.md) |

## Antes de chamar

* Tenha o `authenticationId` devolvido por [`POST /v1/three-ds/authenticate`](https://docs.fastpaybrasil.com/referencia/3d-secure/iniciar).
* Use a **chave pública** (`pk_`, ou `pk_test_` no sandbox) no cabeçalho Basic, como usuário e com senha vazia.
* Se houve fingerprinting, espere a mensagem de fim do iframe oculto (ou o tempo limite de cerca de 60 segundos) antes de chamar.

> [!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_`). 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

**authenticationId** `string` *required*

ID da autenticação 3DS devolvido por `POST /v1/three-ds/authenticate`. Trate como texto opaco e repasse exatamente o valor recebido. Ex.: `tdsa_1QmCRMJM0r9zBvr4OVmMRa6X`.

**fingerprintingResult** `string`

Resultado do fingerprinting em Base64, recebido pelo `postMessage` do iframe oculto. Omita se não houve etapa de fingerprinting. Ex.: `VGhpcyBpcyBhIHNhbXBsZSciAzRFMgTWV0aG9kIFJlc3VsdA==`.

## Respostas

**authenticationId** `string`

ID da autenticação 3DS. Ex.: `tdsa_1QmCRMJM0r9zBvr4OVmMRa6X`.

**status** `string`

Status da autenticação depois do envio: `requires_challenge`, `succeeded`, `failed`, `error` ou `processing`. Ex.: `requires_challenge`.

**challengeUrl** `string | null`

URL do desafio. Carregue em um iframe visível quando o `status` for `requires_challenge`. Ex.: `https://provedor-3ds.exemplo.com/challenge/tdsa_1QmCRMJM0r9zBvr4OVmMRa6X`.

**outcome** `string | null`

Resultado da autenticação. Só vem preenchido em estados finais. Ex.: `authenticated`.

| `status` | Próximo passo |
| - | - |
| `requires_challenge` | Mostre `challengeUrl` em iframe visível. Quando chegar a mensagem `3ds-authentication-challenge-complete`, chame [resultado do desafio](https://docs.fastpaybrasil.com/referencia/3d-secure/resultado-desafio.md) |
| `succeeded` | Banco aprovou sem desafio (frictionless). Chame [resultado do desafio](https://docs.fastpaybrasil.com/referencia/3d-secure/resultado-desafio.md) para obter o criptograma e criar a cobrança |
| `processing` | A autenticação ainda está em processamento |
| `failed` / `error` | Estado final. Não crie a cobrança autenticada. Ofereça nova tentativa ou outro meio de pagamento |

> [!NOTE]
>
> **Para o negócio:** a resposta desta rota decide se o comprador vai ver uma tela do banco. Com `succeeded`, o pagamento segue sem interação extra. Com `requires_challenge`, o checkout precisa mostrar o desafio do banco emissor e esperar o comprador concluir.

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

Os erros vêm no formato `{ statusCode, message, error }`. Trate o erro pelo código HTTP, não pelo texto da mensagem.

## Capturar o resultado do fingerprinting

A página carregada no iframe oculto avisa o fim da coleta com uma mensagem `postMessage` neste formato:

```json theme={null}
{
  "type": "3ds-authentication-fingerprinting-complete",
  "fingerprintingResult": "VGhpcyBpcyBhIHNhbXBsZSciAzRFMgTWV0aG9kIFJlc3VsdA=="
}
```

Registre o listener antes de carregar o iframe e aceite só mensagens que venham desse iframe e tenham o `type` esperado. Se a mensagem não chegar em cerca de 60 segundos (o padrão do SDK), siga sem o resultado: `fingerprintingResult` é opcional.

```javascript theme={null}
function coletarFingerprint(fingerprintingUrl, tempoLimiteMs = 60000) {
  return new Promise((resolve) => {
    const iframe = document.createElement('iframe');
    iframe.style.display = 'none';

    function finalizar(resultado) {
      window.removeEventListener('message', onMessage);
      clearTimeout(timer);
      iframe.remove();
      resolve(resultado);
    }

    function onMessage(event) {
      if (event.source !== iframe.contentWindow) return;
      if (event.data?.type !== '3ds-authentication-fingerprinting-complete') return;
      finalizar(event.data.fingerprintingResult);
    }

    window.addEventListener('message', onMessage);
    const timer = setTimeout(() => finalizar(undefined), tempoLimiteMs);

    iframe.src = fingerprintingUrl;
    document.body.appendChild(iframe);
  });
}
```

> [!TIP]
>
> **Para o desenvolvedor:** a mensagem vem da página do provedor de 3DS, o host da `fingerprintingUrl`. Esse host pode mudar: valide `event.source` e `event.data.type` e não fixe um domínio em `event.origin`.

## 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 ou de outro ambiente | Use a `pk_` (ou `pk_test_`) da conta que iniciou a autenticação |
| `status` `failed` logo após o envio | O banco recusou a autenticação | Ofereça outra forma de pagamento ou outro cartão |
| Checkout parado esperando o fingerprinting | Listener registrado depois do iframe, filtro pelo `type` errado, ou iframe bloqueado | Registre o listener antes, filtre por `3ds-authentication-fingerprinting-complete` e use um tempo limite de cerca de 60 segundos |

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

{
  "authenticationId": "tdsa_1QmCRMJM0r9zBvr4OVmMRa6X",
  "fingerprintingResult": "VGhpcyBpcyBhIHNhbXBsZSciAzRFMgTWV0aG9kIFJlc3VsdA=="
}
```

```bash cURL theme={null}
curl -X POST "https://api-global.fastpaybrasil.com/v1/three-ds/submit" \
  -u "$FINVIA_PUBLIC_KEY:" \
  -H "Content-Type: application/json" \
  -d '{
    "authenticationId": "tdsa_1QmCRMJM0r9zBvr4OVmMRa6X",
    "fingerprintingResult": "VGhpcyBpcyBhIHNhbXBsZSciAzRFMgTWV0aG9kIFJlc3VsdA=="
  }'
```

```javascript Navegador theme={null}
const credentials = btoa(`${FINVIA_PUBLIC_KEY}:`);

const fingerprintingResult = auth.fingerprintingUrl
  ? await coletarFingerprint(auth.fingerprintingUrl)
  : undefined;

const response = await fetch('https://api-global.fastpaybrasil.com/v1/three-ds/submit', {
  method: 'POST',
  headers: {
    Authorization: `Basic ${credentials}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({ authenticationId: auth.authenticationId, fingerprintingResult }),
});

const submit = await response.json();

if (submit.status === 'requires_challenge') {
  // Carregue submit.challengeUrl em um iframe visível
}
```

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

```json 200 Sem desafio theme={null}
{
  "authenticationId": "tdsa_1QmCRMJM0r9zBvr4OVmMRa6X",
  "status": "succeeded",
  "challengeUrl": null,
  "outcome": "authenticated"
}
```

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

## Veja também

> [card] [Iniciar autenticação](https://docs.fastpaybrasil.com/referencia/3d-secure/iniciar.md)
>
> Primeiro passo do 3DS via API.

> [card] [Resultado do desafio](https://docs.fastpaybrasil.com/referencia/3d-secure/resultado-desafio.md)
>
> Dados para criar a cobrança autenticada.

> [card] [Cancelar autenticação](https://docs.fastpaybrasil.com/referencia/3d-secure/cancelar.md)
>
> Quando o comprador desiste no meio do fluxo.

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


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