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

# Obter resultado do 3DS

> Devolve o resultado final da autenticação 3D Secure, com o criptograma e os identificadores que vão na cobrança de cartão.

Quando a autenticação 3DS termina, esta rota entrega o que a cobrança precisa para provar que o comprador foi autenticado: o estado final, o criptograma (CAVV), o ECI, a versão do protocolo e os identificadores da transação no banco e na bandeira. Esse conjunto vai no campo `paymentMethod.threeDS` de [`POST /v1/charges`](https://docs.fastpaybrasil.com/referencia/cobrancas/criar).

É a última chamada do **3DS via API**, antes da criação da cobrança.

## Quando usar

| Situação | Como usar esta rota |
| - | - |
| O comprador concluiu o desafio do banco | Chame com o `authenticationId` e use a resposta na cobrança |
| O envio voltou `succeeded` (sem desafio) | Chame para obter o criptograma e os identificadores |
| 3DS gerenciado (`threeDSMode` `managed`) | Não precisa chamar. A página de autenticação chama esta rota e [Retomar cobrança após 3DS](https://docs.fastpaybrasil.com/referencia/3d-secure/retomar-cobranca.md) |
| Uso do SDK de 3D Secure | O método `process()` do SDK já chama esta rota e devolve um objeto com estes campos |

## Antes de chamar

* Tenha o `authenticationId` devolvido por [`POST /v1/three-ds/authenticate`](https://docs.fastpaybrasil.com/referencia/3d-secure/iniciar).
* Chame só depois da mensagem de fim do desafio (`3ds-authentication-challenge-complete`), ou quando `authenticate` ou `submit` já devolveram um status final (`succeeded`, `failed`, `error` ou `canceled`). Antes disso, a rota responde `500` com a mensagem `Authentication challenge not yet completed...` ou devolve `state` `error`.
* Use a **chave pública** (`pk_`, ou `pk_test_` no sandbox) no cabeçalho Basic, como usuário e com senha vazia.

> [!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`. Ex.: `tdsa_1QmCRMJM0r9zBvr4OVmMRa6X`.

> [!NOTE]
>
> O `authenticationId` é gerado pelo provedor de 3DS e deve ser tratado como texto opaco. Repasse exatamente o valor recebido em `POST /v1/three-ds/authenticate`, sem validar prefixo nem tamanho.

## Respostas

A resposta `200` é o resultado final do desafio (schema `ThreeDSChallengeResult`). Os campos `type` e `state` vêm sempre. Os demais nunca vêm `null`: quando o provedor não devolve um valor, o campo fica ausente da resposta.

**type** `string`

Tipo de autenticação 3DS. Hoje vem sempre `full`. Ex.: `full`.

**state** `string`

Estado da autenticação: `success`, `failure`, `unenrolled`, `error`, `unsupported_brand` ou `disabled`. Ex.: `success`.

**cryptogram** `string`

CAVV, o valor de autenticação gerado pelo banco. Ausente quando não houver valor. Ex.: `Vt5xwasruB0Q6qRoG9mpzdRPqQs=`.

**directoryServerTransactionId** `string`

ID da transação no Directory Server (bandeira). Ex.: `607bb317-8d24-45a7-a3c0-7ae1fdca56d0`.

**threeDsServerTransactionId** `string`

ID da transação no 3DS Server. Ex.: `59588a8b-955e-4aa8-bae1-338bbfdba8fa`.

**acsTransactionId** `string`

ID da transação no ACS (banco emissor). Ex.: `6bf18a7a-3a7b-488f-bce1-3da96c73e746`.

**eci** `string`

Electronic Commerce Indicator. Ex.: `05`.

**version** `string`

Versão do protocolo 3DS. Ex.: `2.2.0`.

### O que fazer com cada `state`

| `state` | Significado | Ação sugerida |
| - | - | - |
| `success` | Autenticação bem-sucedida | Criar a cobrança com o resultado em `paymentMethod.threeDS` |
| `failure` | O comprador não passou na autenticação | Recusar a tentativa ou pedir outro meio de pagamento |
| `unenrolled` | Cartão não inscrito no 3DS | Decidir conforme a sua política de risco |
| `error` | Erro no processo de autenticação | Tentar de novo ou usar outro meio |
| `unsupported_brand` | A bandeira não suporta 3DS | Usar outro meio de pagamento |
| `disabled` | 3DS desabilitado para este cartão | Decidir conforme a sua política de risco |

> [!WARNING]
>
> Quando a configuração da sua conta exige 3DS, só `state` `success` permite que a cobrança siga. Uma cobrança enviada com outro estado é recusada, com o motivo em `reason` (por exemplo, `3ds_failed: The cardholder failed to authenticate. Please try again or use a different card`). Quando o 3DS não é obrigatório para a conta, os dados 3DS são repassados sem essa validação.

> [!NOTE]
>
> **Para o negócio:** `unenrolled` e `disabled` são casos em que o banco não autenticou, mas também não recusou. O que fazer nesses casos é uma decisão de risco da sua empresa. Combine a regra com a área responsável antes de liberar o checkout.

| HTTP | Significado | Mensagem (`message`) |
| - | - | - |
| `200` | Resultado obtido | |
| `401` | Chave pública inválida | `Unauthorized` |
| `404` | Nenhum provedor de 3DS configurado para a conta | `No 3DS provider configured for this gateway` |
| `500` | A rota foi chamada antes do fim do desafio | `Authentication challenge not yet completed...` |

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

## Usar o resultado na cobrança

O resultado é obtido no navegador, com a chave pública. A cobrança é criada no **seu servidor**, com a chave secreta. Envie o resultado do front-end para o seu servidor e inclua-o em `paymentMethod.threeDS`:

```json theme={null}
{
  "amount": 100,
  "currency": "BRL",
  "customer": {
    "name": "Joao Silva",
    "email": "joao@email.com",
    "document": { "type": "cpf", "id": "52998224725" }
  },
  "paymentMethod": {
    "type": "credit_card",
    "number": "4111111111111111",
    "holderName": "JOAO SILVA",
    "expirationMonth": "12",
    "expirationYear": "2028",
    "cvv": "123",
    "installments": 1,
    "threeDS": {
      "type": "full",
      "state": "success",
      "cryptogram": "Vt5xwasruB0Q6qRoG9mpzdRPqQs=",
      "eci": "05",
      "version": "2.2.0",
      "directoryServerTransactionId": "607bb317-8d24-45a7-a3c0-7ae1fdca56d0",
      "threeDsServerTransactionId": "59588a8b-955e-4aa8-bae1-338bbfdba8fa",
      "acsTransactionId": "6bf18a7a-3a7b-488f-bce1-3da96c73e746"
    }
  },
  "items": [
    { "title": "Curso online", "type": "digital", "description": "Acesso por 12 meses", "unit_price": 100, "quantity": 1 }
  ]
}
```

> [!TIP]
>
> **Para o desenvolvedor:** repasse a resposta desta rota do jeito que veio, sem alterar valores e sem acrescentar campos. No objeto `threeDS` da cobrança, `type` e `state` são obrigatórios; com `state` `success`, `cryptogram` e `eci` são, na prática, obrigatórios. Nos campos opcionais, omita o campo quando não tiver valor e nunca envie `null`: o `null` é gravado e repassado ao adquirente, e alguns adquirentes recusam. Com 3DS obrigatório, `cryptogram` ou `eci` nulos fazem a cobrança ser recusada com `3ds_incomplete`. Use o mesmo cartão e o mesmo valor da autenticação.

## 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 |
| `500` `Authentication challenge not yet completed...` ou `state` `error` | A rota foi chamada antes do fim do desafio | Espere a mensagem `3ds-authentication-challenge-complete` antes de chamar |
| Cobrança recusada com `3ds_required: Não foi possível completar a autenticação 3DS obrigatória` | A conta exige 3DS e a cobrança foi enviada sem `threeDS` | Inclua o resultado desta rota em `paymentMethod.threeDS` |
| Cobrança recusada com `3ds_incomplete: Required authentication data (cryptogram or ECI) is missing` | `cryptogram` ou `eci` ausentes ou nulos na cobrança | Repasse a resposta completa desta rota, sem trocar campos por `null` |
| Cobrança recusada com `3ds_failed: The cardholder failed to authenticate. Please try again or use a different card` | O comprador não passou na autenticação | Peça nova tentativa ou outro meio de pagamento |

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

{
  "authenticationId": "tdsa_1QmCRMJM0r9zBvr4OVmMRa6X"
}
```

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

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

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

const threeDS = await response.json();

if (threeDS.state === 'success') {
  // Envie threeDS ao seu servidor, que cria a cobrança com a chave secreta
  await fetch('/api/pedidos/finalizar', { method: 'POST', body: JSON.stringify({ threeDS }) });
}
```

```json 200 theme={null}
{
  "type": "full",
  "state": "success",
  "cryptogram": "Vt5xwasruB0Q6qRoG9mpzdRPqQs=",
  "directoryServerTransactionId": "607bb317-8d24-45a7-a3c0-7ae1fdca56d0",
  "threeDsServerTransactionId": "59588a8b-955e-4aa8-bae1-338bbfdba8fa",
  "acsTransactionId": "6bf18a7a-3a7b-488f-bce1-3da96c73e746",
  "eci": "05",
  "version": "2.2.0"
}
```

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

## Veja também

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

> [card] [Retomar cobrança após 3DS](https://docs.fastpaybrasil.com/referencia/3d-secure/retomar-cobranca.md)
>
> Continuação do 3DS gerenciado.

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

> [card] [SDK de 3D Secure](https://docs.fastpaybrasil.com/guias/3d-secure/sdk.md)
>
> O mesmo resultado obtido pelo SDK.


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