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

# Cancelar autenticação 3DS

> Cancela uma autenticação 3D Secure que ainda espera envio ou desafio, quando o comprador desiste ou troca de cartão.

Esta rota encerra uma autenticação 3DS que ficou pela metade. Use quando o comprador fecha o desafio do banco, volta para trocar de cartão ou desiste da compra. Cancelar deixa claro que aquela autenticação não será usada e evita confusão entre tentativas.

## Quando usar

| Situação | Como usar esta rota |
| - | - |
| Comprador fechou a janela do desafio | Cancele o `authenticationId` e permita uma nova tentativa |
| Comprador voltou para trocar de cartão | Cancele a autenticação do cartão anterior antes de iniciar a do novo |
| Seu checkout atingiu o tempo limite do desafio (o SDK usa cerca de 10 minutos) | Cancele e mostre uma mensagem de nova tentativa |
| A autenticação já terminou (`succeeded`, `failed`) | Esta rota não se aplica. Só cancela autenticações em `requires_submission` ou `requires_challenge` |

## Antes de chamar

* Tenha o `authenticationId` devolvido por [`POST /v1/three-ds/authenticate`](https://docs.fastpaybrasil.com/referencia/3d-secure/iniciar).
* A autenticação precisa estar em `requires_submission` ou `requires_challenge`.
* 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 a cancelar, exatamente como veio em `POST /v1/three-ds/authenticate`. O valor é opaco: não valide prefixo nem tamanho. Ex.: `tdsa_1QmCRMJM0r9zBvr4OVmMRa6X`.

## Respostas

**authenticationId** `string`

ID da autenticação cancelada. Ex.: `tdsa_1QmCRMJM0r9zBvr4OVmMRa6X`.

**status** `string`

Status da autenticação depois do cancelamento. Ex.: `canceled`.

| HTTP | Significado | Mensagem (`message`) |
| - | - | - |
| `200` | Autenticação cancelada | |
| `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.

> [!NOTE]
>
> O contrato não documenta a resposta para o cancelamento de uma autenticação que já está em estado final (por exemplo, `succeeded`). Chame esta rota só nos estados `requires_submission` e `requires_challenge`.

> [!NOTE]
>
> **Para o negócio:** cancelar uma autenticação não cria nem cancela cobrança. A cobrança só existe depois de `POST /v1/charges`. Se o comprador desistiu antes disso, nada foi cobrado.

## Exemplo: comprador fechou o desafio

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

async function aoFecharDesafio(authenticationId) {
  await fetch('https://api-global.fastpaybrasil.com/v1/three-ds/cancel', {
    method: 'POST',
    headers: {
      Authorization: `Basic ${credentials}`,
      'Content-Type': 'application/json',
    },
    body: JSON.stringify({ authenticationId }),
  });

  mostrarMensagem('Autenticação cancelada. Tente de novo ou use outro cartão.');
}
```

> [!TIP]
>
> **Para o desenvolvedor:** para uma nova tentativa depois do cancelamento, inicie uma nova autenticação em [`POST /v1/three-ds/authenticate`](https://docs.fastpaybrasil.com/referencia/3d-secure/iniciar). Use o novo `authenticationId` devolvido por ela nas etapas seguintes.

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

```http REST (JSON) theme={null}
POST /v1/three-ds/cancel 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/cancel" \
  -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/cancel', {
  method: 'POST',
  headers: {
    Authorization: `Basic ${credentials}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({ authenticationId: 'tdsa_1QmCRMJM0r9zBvr4OVmMRa6X' }),
});

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

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

```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)
>
> Comece uma nova tentativa.

> [card] [Enviar autenticação](https://docs.fastpaybrasil.com/referencia/3d-secure/enviar.md)
>
> Etapa anterior ao desafio.

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

> [card] [Visão geral do 3D Secure](https://docs.fastpaybrasil.com/guias/3d-secure/visao-geral.md)
>
> Os três caminhos de 3DS.


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