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

# 3DS via API

> Conduza a autenticação 3D Secure etapa por etapa pelas rotas de 3DS e envie o resultado na criação da cobrança.

No 3DS via API, a sua aplicação conduz cada etapa da autenticação 3D Secure. Ela inicia a autenticação, exibe o iframe de coleta de dados do navegador e envia o resultado. Depois, exibe o desafio do banco quando ele é pedido e, no fim, busca o resultado com o criptograma. Com esse resultado, o seu backend cria a cobrança informando o objeto `threeDS`. É o mesmo fluxo que o SDK faz por dentro, com controle total sobre cada tela.

> [!NOTE]
>
> **Para o negócio:** esta forma dá ao seu time controle completo sobre a experiência do checkout durante a autenticação, ao custo de mais desenvolvimento. Se esse controle não for necessário, o [SDK](https://docs.fastpaybrasil.com/guias/3d-secure/sdk.md) entrega o mesmo resultado com menos código.

## Quando usar

| Situação | Recomendação |
| - | - |
| Você precisa controlar cada tela e cada etapa do 3DS | 3DS via API |
| Seu checkout não pode carregar bibliotecas externas | 3DS via API |
| Você quer menos código no front-end | [SDK](https://docs.fastpaybrasil.com/guias/3d-secure/sdk.md) |
| Você quer que a Finvia conduza a autenticação depois de criar a cobrança | [3DS gerenciado](https://docs.fastpaybrasil.com/guias/3d-secure/gerenciado.md) |

## As rotas

Todas as rotas de 3DS usam a **chave pública** (`pk_`) no cabeçalho Basic, porque são chamadas a partir do navegador.

| Rota | Para que serve |
| - | - |
| `POST /v1/three-ds/authenticate` | Inicia a autenticação. Pode devolver `fingerprintingUrl` ou `challengeUrl` |
| `POST /v1/three-ds/submit` | Envia a autenticação depois do fingerprinting. Pode devolver `challengeUrl` |
| `POST /v1/three-ds/cancel` | Cancela uma autenticação em `requires_submission` ou `requires_challenge` |
| `POST /v1/three-ds/challenge-result` | Busca o resultado final, com o criptograma e os IDs da transação |

## Como funciona

O desenho abaixo mostra a sequência completa de chamadas, com os dois passos que só acontecem quando o emissor pede: a verificação do dispositivo e o desafio.

```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 (navegador, pk_)
        participant L as Seu backend (sk_)
    end
    box rgb(234,243,255) Finvia
        participant F as Finvia API
    end
    box rgb(244,240,255) Fora da Finvia
        participant P as Provedor de 3DS e emissor
    end
    N->>F: POST /v1/three-ds/authenticate · amount, currency, card, browser
    F-->>N: authenticationId · status · fingerprintingUrl ou challengeUrl
    opt status requires_submission
        opt Veio fingerprintingUrl
            N->>P: Carrega a fingerprintingUrl em iframe oculto
            P-)N: postMessage · fingerprinting-complete · fingerprintingResult
        end
        N->>F: POST /v1/three-ds/submit · authenticationId (+ fingerprintingResult)
        F-->>N: requires_challenge, succeeded, failed, error ou processing
    end
    opt requires_challenge (do authenticate ou do submit)
        N->>P: Mostra a challengeUrl em iframe visível, em até 30 s
        C->>P: Confirma a compra na tela do banco
        P-)N: postMessage · challenge-complete
    end
    N->>F: POST /v1/three-ds/challenge-result · authenticationId
    F-->>N: state · cryptogram · eci · version · IDs da transação
    N->>L: Envia o resultado como veio
    L->>F: POST /v1/charges · paymentMethod.threeDS
    F-->>L: 201 · paid, refused ou failed
```

As mensagens `postMessage` chegam com o `type` completo (`3ds-authentication-fingerprinting-complete` e `3ds-authentication-challenge-complete`). O `status` da mensagem de fim do desafio é só informativo: o resultado que vale é o de `challenge-result`.

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

O navegador chama `POST /v1/three-ds/authenticate` com valor, moeda, dados do cartão e dados do navegador. A resposta traz o `authenticationId` e o `status`.

**2. Verificação do dispositivo em iframe oculto**

Se o `status` for `requires_submission` com `fingerprintingUrl`, carregue essa URL em um iframe oculto e aguarde a mensagem `3ds-authentication-fingerprinting-complete`, com o `fingerprintingResult`. Se ela não chegar em cerca de 60 segundos, siga sem ele.

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

Chame `POST /v1/three-ds/submit` com o `authenticationId` e, se houver, o `fingerprintingResult`. Se o `status` era `requires_submission` sem `fingerprintingUrl`, chame o `submit` direto. A resposta traz o novo `status`.

**4. Desafio em iframe visível**

Se o `status` for `requires_challenge` (vindo do `authenticate` ou do `submit`), carregue a `challengeUrl` em um iframe visível em até 30 segundos. O cliente confirma a compra na tela do banco, e a página avisa o fim com a mensagem `3ds-authentication-challenge-complete`.

**5. Busque o resultado**

Depois da mensagem de fim do desafio, ou quando `authenticate` ou `submit` já devolveram status final, chame `POST /v1/three-ds/challenge-result` com o `authenticationId`. A resposta traz `state`, `cryptogram`, `eci`, `version` e os IDs da transação.

**6. Crie a cobrança com threeDS**

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

### Status da autenticação

| `status` | Significado | Próximo passo |
| - | - | - |
| `requires_submission` | Aguardando o envio (depois do fingerprinting, se houver) | `submit` |
| `requires_challenge` | O emissor pede desafio | Mostrar `challengeUrl` em iframe visível |
| `processing` | Em processamento | Aguardar |
| `succeeded` | Autenticação concluída com sucesso | `challenge-result` |
| `failed` | Autenticação falhou | `challenge-result` para obter o `state` e decidir |
| `error` | Erro na autenticação | `challenge-result` para obter o `state`; tentar de novo ou usar outra forma de pagamento |
| `canceled` | Autenticação cancelada | Recomeçar, se o cliente quiser |

Em estados finais, a resposta pode trazer `outcome`, com um destes valores: `authenticated`, `informational`, `attempt_acknowledged`, `rejected`, `denied`, `abandoned`, `not_supported`, `processing_error`, `internal_error` ou `canceled`.

> [!NOTE]
>
> Os `status` acima são da **autenticação**, não da cobrança. A cobrança só é criada no fim, com o `state` devolvido por `challenge-result`.

O desenho abaixo mostra qual rota chamar a partir de cada `status` da autenticação.

```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": {"defaultRenderer": "elk", "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
    AUTH["POST<br/>/v1/three-ds/authenticate"]:::lojista
    Q1{"Veio<br/>fingerprintingUrl?"}:::decisao
    FP["Iframe oculto<br/>espera a mensagem até ~60 s"]:::lojista
    SUB["POST<br/>/v1/three-ds/submit"]:::lojista
    CH["Desafio: challengeUrl em<br/>iframe visível, aberto em<br/>até 30 s, espera ~10 min"]:::alerta
    CANC(["POST /v1/three-ds/cancel<br/>status canceled"]):::erro
    RES["POST /v1/three-ds/<br/>challenge-result<br/>devolve o state"]:::lojista
    Q2{"state é<br/>success?"}:::decisao
    COB(["Backend cria a cobrança<br/>com threeDS"]):::ok
    OUT(["Com 3DS obrigatório:<br/>nova tentativa<br/>ou outro meio"]):::erro
    AUTH -->|"requires_submission"| Q1
    Q1 -->|"sim"| FP
    Q1 -->|"não"| SUB
    FP -->|"com ou sem<br/>fingerprintingResult"| SUB
    AUTH -->|"requires_challenge"| CH
    SUB -->|"requires_challenge<br/>depois do envio"| CH
    AUTH -->|"status final"| RES
    SUB -->|"succeeded, failed<br/>ou error"| RES
    CH ==>|"mensagem de fim<br/>do desafio"| RES
    CH -.->|"cliente desiste<br/>ou o tempo acaba"| CANC
    RES --> Q2
    Q2 ==>|"sim"| COB
    Q2 -->|"não"| OUT
    classDef lojista fill:#F3F5F8,stroke:#475467,stroke-width:1.5px,color:#101828
    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
```

Se `authenticate` ou `submit` devolverem `processing`, aguarde antes de seguir. O cancelamento só vale para autenticações em `requires_submission` ou `requires_challenge`.

## Regras de negócio

| Regra | Detalhe |
| - | - |
| Chave nas rotas de 3DS | Pública (`pk_`) |
| Chave na cobrança | Secreta (`sk_`), no backend |
| Obrigatórios em `authenticate` | `amount`, `currency`, `card` (com `number`, `expirationMonth`, `expirationYear`) e `browser` (com `userAgent` e `ipAddress`) |
| Obrigatório em `submit`, `cancel` e `challenge-result` | `authenticationId` |
| `fingerprintingResult` | Opcional em `submit`. Omita se não houve fingerprinting ou se a mensagem não chegou em cerca de 60 segundos |
| Ordem das chamadas | `authenticate`, iframe de verificação, `submit`, desafio, `challenge-result` e, no backend, `POST /v1/charges` |
| Tempo do desafio | Exiba a `challengeUrl` em até 30 segundos e espere no máximo cerca de 10 minutos. Para desistir, use `cancel` |
| `authenticationId` | Texto opaco gerado pelo provedor de 3DS. Repasse sem validar prefixo nem tamanho |
| Cancelamento | Só para autenticações em `requires_submission` ou `requires_challenge` |
| Cobrança | Só `state` `success` permite seguir quando o 3DS é exigido pela configuração da conta |
| Erro `404` | `No 3DS provider configured for this gateway`: a conta não tem provedor de 3DS configurado |
| Erro `401` | `Unauthorized`: chave pública inválida |

## Passo a passo

Os exemplos usam `fetch` no navegador com a chave pública. Defina uma função auxiliar:

```javascript theme={null}
const FINVIA_PUBLIC_KEY = 'pk_sua_chave_publica';
const API = 'https://api-global.fastpaybrasil.com';

async function chamar3ds(rota, corpo) {
  const response = await fetch(`${API}${rota}`, {
    method: 'POST',
    headers: {
      Authorization: 'Basic ' + btoa(`${FINVIA_PUBLIC_KEY}:`),
      'Content-Type': 'application/json',
    },
    body: JSON.stringify(corpo),
  });
  if (!response.ok) throw new Error(`3DS ${rota} respondeu ${response.status}`);
  return response.json();
}
```

### 1. Inicie a autenticação

```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": "2028"
  },
  "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": "2028"
    },
    "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}
const inicio = await chamar3ds('/v1/three-ds/authenticate', {
  amount: 100,
  currency: 'BRL',
  card: {
    number: cartao.numero,
    holderName: cartao.nome,
    expirationMonth: cartao.mes,
    expirationYear: cartao.ano,
  },
  browser: {
    userAgent: navigator.userAgent,
    ipAddress: ipDoCliente, // obtido pelo seu backend
    language: navigator.language,
    timezoneOffset: -new Date().getTimezoneOffset(),
    javascriptEnabled: true,
    screenWidth: screen.width,
    screenHeight: screen.height,
    colorDepth: screen.colorDepth,
  },
});
```

Resposta `200`:

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

> [!TIP]
>
> **Para o desenvolvedor:** o `cvv` não faz parte da autenticação. Ele vai só na criação da cobrança, feita pelo backend.

### 2. Faça a verificação do dispositivo em um iframe oculto

Se o `status` for `requires_submission` e vier `fingerprintingUrl`, carregue a URL em um iframe oculto. Quando a coleta termina, a página do provedor de 3DS envia à sua janela, por `postMessage`, esta mensagem:

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

O `fingerprintingResult` é um texto em Base64 que você repassa ao `submit` sem alterar.

```javascript theme={null}
function esperarMensagem(iframe, tipo, tempoLimiteMs) {
  return new Promise((resolve) => {
    function aoReceber(event) {
      // Aceite só mensagens do iframe que você criou e do tipo esperado
      if (event.source !== iframe.contentWindow) return;
      if (event.data?.type !== tipo) return;
      encerrar(event.data);
    }

    function encerrar(dados) {
      window.removeEventListener('message', aoReceber);
      clearTimeout(timer);
      resolve(dados);
    }

    window.addEventListener('message', aoReceber);
    const timer = setTimeout(() => encerrar(null), tempoLimiteMs);
  });
}

let fingerprintingResult;

if (inicio.status === 'requires_submission' && inicio.fingerprintingUrl) {
  const iframe = document.createElement('iframe');
  iframe.style.display = 'none';
  const mensagem = esperarMensagem(iframe, '3ds-authentication-fingerprinting-complete', 60000);
  iframe.src = inicio.fingerprintingUrl;
  document.body.appendChild(iframe);

  const dados = await mensagem;
  iframe.remove();
  fingerprintingResult = dados?.fingerprintingResult; // undefined se o tempo acabou
}
```

> [!WARNING]
>
> Quem envia a mensagem é a página do provedor de 3DS carregada no iframe, e o host dela pode mudar. Valide `event.source === iframe.contentWindow` e `event.data.type`. Não fixe um domínio de provedor em `event.origin`.

> [!TIP]
>
> **Para o desenvolvedor:** se a mensagem não chegar em cerca de 60 segundos (o padrão do SDK), chame o `submit` sem `fingerprintingResult`. O campo é opcional. Se o `status` for `requires_submission` sem `fingerprintingUrl`, chame o `submit` direto.

### 3. Envie a autenticação

```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}
// O submit só é necessário quando o status inicial é requires_submission
const envio =
  inicio.status === 'requires_submission'
    ? await chamar3ds('/v1/three-ds/submit', {
        authenticationId: inicio.authenticationId,
        ...(fingerprintingResult ? { fingerprintingResult } : {}),
      })
    : inicio;
```

Resposta `200`:

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

O `submit` devolve um destes status: `requires_challenge`, `succeeded`, `failed`, `error` ou `processing`.

### 4. Mostre o desafio em um iframe visível

Quando o `status` é `requires_challenge`, a `challengeUrl` (que pode vir tanto do `authenticate` quanto do `submit`) precisa ser exibida ao cliente em um iframe visível, em até 30 segundos.

* Não use o atributo `sandbox` no iframe. Alguns emissores falham com ele.
* Tamanhos recomendados: 250×400, 390×400, 500×600, 600×400 ou tela cheia.
* Espere no máximo cerca de 10 minutos. Depois disso, cancele a autenticação.

```html theme={null}
<div id="desafio-3ds" hidden>
  <p>Confirme a compra com o seu banco.</p>
  <iframe id="iframe-3ds" width="500" height="600" title="Autenticação do banco"></iframe>
  <button id="cancelar-3ds" type="button">Cancelar</button>
</div>
```

Quando o cliente termina, a página do desafio envia esta mensagem por `postMessage`:

```json theme={null}
{
  "type": "3ds-authentication-challenge-complete",
  "status": "succeeded"
}
```

O `status` da mensagem pode ser `succeeded`, `failed`, `error` ou `canceled`. Ele é só informativo: o resultado que vale é o devolvido por `challenge-result` no passo 5.

```javascript theme={null}
const challengeUrl = envio.challengeUrl || inicio.challengeUrl;
if (envio.status === 'requires_challenge' && challengeUrl) {
  const iframe = document.getElementById('iframe-3ds');
  const fim = esperarMensagem(iframe, '3ds-authentication-challenge-complete', 10 * 60 * 1000);
  iframe.src = challengeUrl;
  document.getElementById('desafio-3ds').hidden = false;

  const dados = await fim;
  document.getElementById('desafio-3ds').hidden = true;

  if (!dados) {
    // Tempo esgotado: cancele a autenticação (veja abaixo)
  }
}
```

> [!NOTE]
>
> Neste fluxo não há redirecionamento: o fim do desafio é avisado só pela mensagem `postMessage`. Os campos `challenge.returnUrl` e `deviceData` do objeto `threeDS` não se aplicam ao 3DS da Finvia (SDK, via API ou gerenciado) e são ignorados. Não é preciso enviá-los.

Se o cliente desistir, cancele a autenticação:

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

Resposta `200`:

```json theme={null}
{ "authenticationId": "tdsa_1QmCRMJM0r9zBvr4OVmMRa6X", "status": "canceled" }
```

### 5. Busque o resultado

Depois da mensagem de fim do desafio, ou quando `authenticate` ou `submit` já devolveram status final (`succeeded`, `failed`, `error` ou `canceled`), busque o resultado:

```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 resultado = await chamar3ds('/v1/three-ds/challenge-result', {
  authenticationId: inicio.authenticationId,
});

if (resultado.state !== 'success') {
  // Mostre a mensagem adequada e ofereça outra forma de pagamento
}
```

Resposta `200`:

```json 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"
}
```

| Campo | O que é |
| - | - |
| `type` | Tipo de autenticação (ex.: `full`) |
| `state` | `success`, `failure`, `unenrolled`, `error`, `unsupported_brand` ou `disabled` |
| `cryptogram` | CAVV, o valor de autenticação |
| `eci` | Electronic Commerce Indicator (`05` autenticado, `06` tentativa, `07` não autenticado) |
| `version` | Versão do protocolo 3DS |
| `directoryServerTransactionId`, `threeDsServerTransactionId`, `acsTransactionId` | IDs da transação na bandeira, no 3DS Server e no emissor |

> [!WARNING]
>
> Não chame `challenge-result` antes do fim do desafio. Nesse caso, a rota responde `500` com a mensagem `Authentication challenge not yet completed...` ou devolve `state` `error`.

### 6. Crie a cobrança com o objeto threeDS

O navegador envia o resultado ao seu backend, que cria a cobrança com a chave secreta. O objeto devolvido por `challenge-result` vai em `paymentMethod.threeDS`.

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

{
  "amount": 100,
  "currency": "BRL",
  "customer": {
    "name": "Joao Silva",
    "email": "joao@email.com",
    "document": {
      "type": "cpf",
      "id": "52998224725"
    },
    "ipAddress": "177.128.144.97"
  },
  "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": "Produto XYZ",
      "type": "digital",
      "description": "Descrição do produto",
      "unit_price": 100,
      "quantity": 1
    }
  ],
  "postbackUrl": "https://meusite.com.br/webhooks/finvia"
}
```

```bash cURL theme={null}
curl -X POST "https://api-global.fastpaybrasil.com/v1/charges" \
  -u "$FINVIA_API_KEY:" \
  -H "Content-Type: application/json" \
  -d '{
    "amount": 100,
    "currency": "BRL",
    "customer": {
      "name": "Joao Silva",
      "email": "joao@email.com",
      "document": { "type": "cpf", "id": "52998224725" },
      "ipAddress": "177.128.144.97"
    },
    "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": "Produto XYZ", "type": "digital", "description": "Descrição do produto", "unit_price": 100, "quantity": 1 }
    ],
    "postbackUrl": "https://meusite.com.br/webhooks/finvia"
  }'
```

```python Python theme={null}
import os

import requests

payload = {
    "amount": 100,
    "currency": "BRL",
    "customer": {
        "name": "Joao Silva",
        "email": "joao@email.com",
        "document": {
            "type": "cpf",
            "id": "52998224725",
        },
        "ipAddress": "177.128.144.97",
    },
    "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": "Produto XYZ",
            "type": "digital",
            "description": "Descrição do produto",
            "unit_price": 100,
            "quantity": 1,
        },
    ],
    "postbackUrl": "https://meusite.com.br/webhooks/finvia",
}

response = requests.request(
    "POST",
    "https://api-global.fastpaybrasil.com/v1/charges",
    auth=(os.environ["FINVIA_API_KEY"], ""),
    json=payload,
    timeout=30,
)

print(response.status_code)
if response.content:
    print(response.json())
```

```php PHP theme={null}
<?php

$payload = [
    'amount' => 100,
    'currency' => 'BRL',
    'customer' => [
        'name' => 'Joao Silva',
        'email' => 'joao@email.com',
        'document' => [
            'type' => 'cpf',
            'id' => '52998224725',
        ],
        'ipAddress' => '177.128.144.97',
    ],
    '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' => 'Produto XYZ',
            'type' => 'digital',
            'description' => 'Descrição do produto',
            'unit_price' => 100,
            'quantity' => 1,
        ],
    ],
    'postbackUrl' => 'https://meusite.com.br/webhooks/finvia',
];

$ch = curl_init('https://api-global.fastpaybrasil.com/v1/charges');

curl_setopt_array($ch, [
    CURLOPT_CUSTOMREQUEST => 'POST',
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_USERPWD => getenv('FINVIA_API_KEY') . ':',
    CURLOPT_HTTPHEADER => ['Content-Type: application/json'],
    CURLOPT_POSTFIELDS => json_encode($payload),
]);

$body = curl_exec($ch);
$status = curl_getinfo($ch, CURLINFO_HTTP_CODE);
curl_close($ch);

echo $status, PHP_EOL;
print_r(json_decode($body, true));
```

```java Java theme={null}
import java.net.URI;
import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;
import java.util.Base64;

public class Exemplo {
    public static void main(String[] args) throws Exception {
        String credentials = Base64.getEncoder()
            .encodeToString((System.getenv("FINVIA_API_KEY") + ":").getBytes());

        String payload = """
            {
              "amount": 100,
              "currency": "BRL",
              "customer": {
                "name": "Joao Silva",
                "email": "joao@email.com",
                "document": {
                  "type": "cpf",
                  "id": "52998224725"
                },
                "ipAddress": "177.128.144.97"
              },
              "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": "Produto XYZ",
                  "type": "digital",
                  "description": "Descrição do produto",
                  "unit_price": 100,
                  "quantity": 1
                }
              ],
              "postbackUrl": "https://meusite.com.br/webhooks/finvia"
            }
            """;

        HttpRequest request = HttpRequest.newBuilder()
            .uri(URI.create("https://api-global.fastpaybrasil.com/v1/charges"))
            .header("Authorization", "Basic " + credentials)
            .header("Content-Type", "application/json")
            .method("POST", HttpRequest.BodyPublishers.ofString(payload))
            .build();

        HttpResponse<String> response = HttpClient.newHttpClient()
            .send(request, HttpResponse.BodyHandlers.ofString());

        System.out.println(response.statusCode());
        System.out.println(response.body());
    }
}
```

```csharp C# theme={null}
using System.Net.Http.Headers;
using System.Text;

var apiKey = Environment.GetEnvironmentVariable("FINVIA_API_KEY");
var credentials = Convert.ToBase64String(Encoding.UTF8.GetBytes($"{apiKey}:"));

using var client = new HttpClient();
client.DefaultRequestHeaders.Authorization = new AuthenticationHeaderValue("Basic", credentials);

var payload = """
{
  "amount": 100,
  "currency": "BRL",
  "customer": {
    "name": "Joao Silva",
    "email": "joao@email.com",
    "document": {
      "type": "cpf",
      "id": "52998224725"
    },
    "ipAddress": "177.128.144.97"
  },
  "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": "Produto XYZ",
      "type": "digital",
      "description": "Descrição do produto",
      "unit_price": 100,
      "quantity": 1
    }
  ],
  "postbackUrl": "https://meusite.com.br/webhooks/finvia"
}
""";

var request = new HttpRequestMessage(HttpMethod.Post, "https://api-global.fastpaybrasil.com/v1/charges");
request.Content = new StringContent(payload, Encoding.UTF8, "application/json");

var response = await client.SendAsync(request);
Console.WriteLine((int)response.StatusCode);
Console.WriteLine(await response.Content.ReadAsStringAsync());
```

```go Go theme={null}
package main

import (
	"fmt"
	"io"
	"net/http"
	"os"
	"strings"
)

func main() {
	payload := strings.NewReader(`{
	  "amount": 100,
	  "currency": "BRL",
	  "customer": {
	    "name": "Joao Silva",
	    "email": "joao@email.com",
	    "document": {
	      "type": "cpf",
	      "id": "52998224725"
	    },
	    "ipAddress": "177.128.144.97"
	  },
	  "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": "Produto XYZ",
	      "type": "digital",
	      "description": "Descrição do produto",
	      "unit_price": 100,
	      "quantity": 1
	    }
	  ],
	  "postbackUrl": "https://meusite.com.br/webhooks/finvia"
	}`)

	req, err := http.NewRequest("POST", "https://api-global.fastpaybrasil.com/v1/charges", payload)
	if err != nil {
		panic(err)
	}
	req.SetBasicAuth(os.Getenv("FINVIA_API_KEY"), "")
	req.Header.Set("Content-Type", "application/json")

	res, err := http.DefaultClient.Do(req)
	if err != nil {
		panic(err)
	}
	defer res.Body.Close()

	body, _ := io.ReadAll(res.Body)
	fmt.Println(res.StatusCode)
	fmt.Println(string(body))
}
```

```ruby Ruby theme={null}
require "json"
require "net/http"
require "uri"

uri = URI("https://api-global.fastpaybrasil.com/v1/charges")
request = Net::HTTP::Post.new(uri)
request.basic_auth(ENV.fetch("FINVIA_API_KEY"), "")
request["Content-Type"] = "application/json"
request.body = JSON.generate({
  "amount" => 100,
  "currency" => "BRL",
  "customer" => {
    "name" => "Joao Silva",
    "email" => "joao@email.com",
    "document" => {
      "type" => "cpf",
      "id" => "52998224725",
    },
    "ipAddress" => "177.128.144.97",
  },
  "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" => "Produto XYZ",
      "type" => "digital",
      "description" => "Descrição do produto",
      "unit_price" => 100,
      "quantity" => 1,
    },
  ],
  "postbackUrl" => "https://meusite.com.br/webhooks/finvia",
})

response = Net::HTTP.start(uri.hostname, uri.port, use_ssl: true) do |http|
  http.request(request)
end

puts response.code
puts response.body
```

> [!NOTE]
>
> A resposta de `challenge-result` nunca traz campos com `null`: quando não há valor (por exemplo, `cryptogram` numa autenticação sem sucesso), o campo fica ausente. Repasse o objeto como veio. O objeto `threeDS` da cobrança exige `type` e `state`; 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 não envie `null`. Não envie `mode`, que é de uso interno.

A resposta da cobrança é a de sempre: `id`, `status` (`paid`, `refused` ou `failed`), `paymentDetails` e `reason`.

## Erros comuns

| Sintoma | Causa | Como resolver |
| - | - | - |
| `404` `No 3DS provider configured for this gateway` | Nenhum provedor de 3DS configurado para a conta | 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 |
| Verificação do dispositivo não termina | Mensagem não recebida, filtro pelo `type` errado ou listener registrado depois do iframe | Filtre por `3ds-authentication-fingerprinting-complete`, registre o listener antes e, depois de cerca de 60 segundos, siga sem `fingerprintingResult` |
| Desafio não carrega ou falha no emissor | Iframe com o atributo `sandbox` | Remova o atributo `sandbox` |
| `500` em `challenge-result` | Chamada antes do fim do desafio | Espere a mensagem `3ds-authentication-challenge-complete` |
| Tentativa de cancelar uma autenticação já concluída | O cancelamento só vale para `requires_submission` e `requires_challenge` | Consulte o resultado com `challenge-result` |
| Cobrança `refused` com `3ds_required: Não foi possível completar a autenticação 3DS obrigatória` | Cobrança criada sem `threeDS` numa conta com 3DS obrigatório | Envie o resultado em `paymentMethod.threeDS` |
| Cobrança `refused` com `3ds_incomplete: Required authentication data (cryptogram or ECI) is missing` | `cryptogram` ou `eci` ausentes ou nulos | Envie o objeto completo devolvido por `challenge-result`, sem `null` |

## Perguntas frequentes

> [accordion] Sempre vai ter fingerprinting e desafio?
>
> Não. A resposta de `authenticate` pode trazer `fingerprintingUrl`, `challengeUrl` ou nenhum dos dois, conforme o emissor. Trate cada caso pelo `status`.

> [accordion] Qual a diferença entre status, outcome e state?
>
> `status` mostra em que etapa a autenticação está. `outcome` aparece nos estados finais e detalha como ela terminou. `state` é o resultado devolvido por `challenge-result`, usado no objeto `threeDS` da cobrança.

> [accordion] Posso chamar as rotas de 3DS pelo backend?
>
> As rotas usam a chave pública e foram desenhadas para o navegador, que exibe os iframes. A criação da cobrança, essa sim, é sempre feita pelo backend, com a chave secreta.

> [accordion] Para que serve challenge.returnUrl?
>
> No 3DS da Finvia, esse campo não tem uso. O fim do desafio é avisado pela mensagem `postMessage`, sem redirecionamento. Os campos `challenge.returnUrl` e `deviceData` são ignorados; não é preciso enviá-los.

> [accordion] Uso o mesmo resultado em mais de uma cobrança?
>
> A documentação não prevê isso. Faça uma autenticação para cada 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). Inclua no teste os caminhos com e sem fingerprinting, com e sem desafio, o cancelamento e a cobrança com `state` `success`.

## Veja também

> [card] [Iniciar autenticação](https://docs.fastpaybrasil.com/referencia/3d-secure/iniciar.md)
>
> Referência de `POST /v1/three-ds/authenticate`.

> [card] [Resultado do desafio](https://docs.fastpaybrasil.com/referencia/3d-secure/resultado-desafio.md)
>
> Referência de `POST /v1/three-ds/challenge-result`.

> [card] [SDK de segurança](https://docs.fastpaybrasil.com/guias/3d-secure/sdk.md)
>
> O mesmo fluxo com menos código.

> [card] [3D Secure: visão geral](https://docs.fastpaybrasil.com/guias/3d-secure/visao-geral.md)
>
> Estados, ECI e comparativo.


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