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

# Retomar cobrança após 3DS

> Conclui uma cobrança criada com 3DS gerenciado: recebe o resultado da autenticação e processa o pagamento.

No **3DS gerenciado**, a cobrança de cartão é criada com `threeDSMode` `managed` e, quando o banco pede verificação ou desafio, fica no status `authentication_required` até o comprador se autenticar. Esta rota é a continuação: ela recebe o resultado da autenticação, processa a cobrança e dispara os webhooks e o postback. A resposta tem o mesmo formato da resposta de criação de cobrança.

Quem chama esta rota é a página de autenticação aberta pela `authenticationUrl`, depois que o comprador conclui a verificação. No fluxo gerenciado, a sua integração não precisa chamá-la: ela cria a cobrança, abre a `authenticationUrl` e acompanha o resultado por webhook ou por `GET /v1/charges/{id}`. Veja o [guia do 3DS gerenciado](https://docs.fastpaybrasil.com/guias/3d-secure/gerenciado.md).

## Quando usar

| Situação | Caminho |
| - | - |
| Fluxo gerenciado padrão, com a `authenticationUrl` aberta para o comprador | A página de autenticação chama esta rota. Você só acompanha o resultado |
| Cobrança criada sem `threeDSMode` | Não se aplica. Para 3DS feito por você, envie `paymentMethod.threeDS` já na criação |
| Cobrança em qualquer status diferente de `authentication_required` | A rota responde `404` |

> [!NOTE]
>
> **Para o negócio:** no 3DS gerenciado, a cobrança existe desde o início, mas só é processada quando esta rota é chamada com o resultado da autenticação. Enquanto ela estiver em `authentication_required`, o pedido não está pago.

## Antes de chamar

* A cobrança precisa ter sido criada em [`POST /v1/charges`](https://docs.fastpaybrasil.com/referencia/cobrancas/criar) com `paymentMethod.threeDSMode` `managed` e o objeto `browser`, e estar com status `authentication_required`.
* Os dados do cartão da cobrança ficam guardados por 15 minutos. Depois disso, a retomada falha com `422`.
* O resultado da autenticação 3DS vem de [`POST /v1/three-ds/challenge-result`](https://docs.fastpaybrasil.com/referencia/3d-secure/resultado-desafio).
* Use a **chave pública** (`pk_`, ou `pk_test_` no sandbox) como usuário do Basic, com senha vazia.

## Parâmetros de caminho

**id** `string` *required*

ID da cobrança. Ex.: `2vorkDcXyvzifL63YX09S9VqcnI`.

## Corpo da requisição

**threeDS** `object` *required*

Dados da autenticação 3D Secure (schema `CreditCardThreeDS`). O objeto é obrigatório: `threeDS: null` responde `400`. Nos campos opcionais, omita o campo quando não tiver valor. Não envie `null`: um `null` sobrescreve o valor que já estava guardado na cobrança.

**propriedades**

**type** `string` *required*

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

**state** `string` *required*

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

**cryptogram** `string`

CAVV (valor de autenticação), criptograma em Base64 gerado na autenticação. Com `state` `success`, envie sempre. Ex.: `Vt5xwasruB0Q6qRoG9mpzdRPqQs=`.

**eci** `string`

Electronic Commerce Indicator. Valores comuns: `05` (autenticado), `06` (tentativa), `07` (não autenticado). Com `state` `success`, envie sempre. Ex.: `05`.

**version** `string`

Versão do protocolo 3DS (ex.: `2.1.0`, `2.2.0`). Ex.: `2.2.0`.

**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`.

> [!NOTE]
>
> O schema `CreditCardThreeDS` também lista `mode`, `deviceData` e `challenge`. Não envie esses campos: `mode` é de uso interno e `deviceData` e `challenge` não são lidos no 3DS da Finvia.

## Respostas

A resposta `200` tem o formato da cobrança criada (schema `CreatedCharge`).

**id** `string` *required*

Identificador único da cobrança. Ex.: `2vorkDcXyvzifL63YX09S9VqcnI`.

**status** `string` *required*

Status da cobrança depois do processamento: `paid`, `pending`, `refused` ou `failed`. Ex.: `paid`.

**paymentDetails** `object | null` *required*

Detalhes do cartão usado.

**propriedades**

**firstSix** `string` *required*

Seis primeiros dígitos do cartão. Ex.: `411111`.

**lastFour** `string` *required*

Quatro últimos dígitos do cartão. Ex.: `1111`.

**expirationMonth** `string` *required*

Mês de validade. Ex.: `10`.

**expirationYear** `string` *required*

Ano de validade. Ex.: `2028`.

**holderName** `string` *required*

Nome do titular. Ex.: `ANA LIMA`.

**installments** `number` *required*

Número de parcelas usado. Ex.: `2`.

**reason** `string | null` *required*

Motivo do status, principalmente em cobranças recusadas. Quando a autenticação não passou, vem no formato `3ds_<estado>: Authentication did not succeed`.

| HTTP | Significado | Mensagem (`message`) |
| - | - | - |
| `200` | Cobrança retomada e processada | |
| `400` | A cobrança não usa o 3DS gerenciado | `Cobrança não está utilizando 3DS gerenciado` |
| `400` | Corpo inválido (por exemplo, sem `threeDS`, ou `type` ou `state` nulos) | Lista de mensagens de validação |
| `401` | Chave pública inválida | `Unauthorized` |
| `404` | Cobrança inexistente, de outra conta ou fora de `authentication_required` | `Cobrança não encontrada ou não está aguardando autenticação` |
| `422` | Dados do cartão ausentes | `Dados do cartão não encontrados. Crie uma nova cobrança.` |
| `422` | Dados do cartão expirados (mais de 15 minutos) | `Dados do cartão expiraram. Crie uma nova cobrança.` |
| `422` | Dados da autenticação expirados | `Dados de autenticação expiraram. Crie uma nova cobrança.` |

Os erros vêm no formato `{ statusCode, message, error }`. Trate o erro pelo código HTTP, não pelo texto: as mensagens misturam português e inglês e são exibidas aqui exatamente como a API devolve.

> [!WARNING]
>
> Depois de um `422`, a cobrança não é processada e não pode mais ser retomada. Crie uma nova cobrança. Não trate a cobrança antiga como paga.

> [!WARNING]
>
> O código `200` confirma que a cobrança foi processada. Para saber se ela foi paga, leia o `status`: `paid` libera o pedido; `refused` e `failed` encerram a tentativa, com o motivo em `reason`.

## Erros comuns

| Sintoma | Causa | Como resolver |
| - | - | - |
| `404` | A cobrança já saiu de `authentication_required` (foi retomada antes), não existe ou é de outra conta | Consulte `GET /v1/charges/{id}` e use o status atual. Não chame esta rota duas vezes para a mesma cobrança |
| `400` `Cobrança não está utilizando 3DS gerenciado` | A cobrança foi criada sem `threeDSMode` `managed` | Para 3DS feito por você, envie `paymentMethod.threeDS` na criação |
| `422` com "expiraram" | A autenticação terminou depois do prazo de 15 minutos | Crie uma nova cobrança |
| `401` | Chave pública inválida ou de outro ambiente | Use a `pk_` (ou `pk_test_`) da conta que criou a cobrança |
| `200` com `status` `refused` | Autenticação sem sucesso ou recusa do emissor | Leia `reason` e ofereça nova tentativa ou outro meio |

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

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

```bash cURL theme={null}
curl -X POST "https://api-global.fastpaybrasil.com/v1/charges/2vorkDcXyvzifL63YX09S9VqcnI/resume-3ds" \
  -u "$FINVIA_PUBLIC_KEY:" \
  -H "Content-Type: application/json" \
  -d '{
    "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"
    }
  }'
```

```javascript Navegador theme={null}
const response = await fetch(
  `https://api-global.fastpaybrasil.com/v1/charges/${chargeId}/resume-3ds`,
  {
    method: 'POST',
    headers: {
      Authorization: 'Basic ' + btoa(`${FINVIA_PUBLIC_KEY}:`),
      'Content-Type': 'application/json',
    },
    body: JSON.stringify({ threeDS: resultadoDaAutenticacao }),
  },
);

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

```json 200 theme={null}
{
  "id": "2vorkDcXyvzifL63YX09S9VqcnI",
  "status": "paid",
  "paymentDetails": {
    "firstSix": "411111",
    "lastFour": "1111",
    "expirationMonth": "10",
    "expirationYear": "2028",
    "holderName": "ANA LIMA",
    "installments": 2
  },
  "reason": null
}
```

```json 404 theme={null}
{
  "statusCode": 404,
  "message": "Cobrança não encontrada ou não está aguardando autenticação",
  "error": "Not Found"
}
```

```json 422 theme={null}
{
  "statusCode": 422,
  "message": "Dados de autenticação expiraram. Crie uma nova cobrança.",
  "error": "Unprocessable Entity"
}
```

## Veja também

> [card] [3DS gerenciado](https://docs.fastpaybrasil.com/guias/3d-secure/gerenciado.md)
>
> Guia do fluxo gerenciado pela Finvia.

> [card] [Criar uma cobrança](https://docs.fastpaybrasil.com/referencia/cobrancas/criar.md)
>
> Campos `threeDSMode`, `browser` e `authenticationUrl`.

> [card] [Obter resultado do 3DS](https://docs.fastpaybrasil.com/referencia/3d-secure/resultado-desafio.md)
>
> Origem do objeto `threeDS`.

> [card] [Webhooks de cobrança](https://docs.fastpaybrasil.com/guias/webhooks/cobranca.md)
>
> Eventos disparados após a retomada.


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