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

> Crie a cobrança com threeDSMode managed, leve o comprador à authenticationUrl e acompanhe o resultado por webhook ou consulta.

No 3DS gerenciado, a Finvia conduz a autenticação 3D Secure por você. O seu backend cria a cobrança de cartão com `threeDSMode: "managed"` e os dados do navegador do comprador. Quando o banco emissor pede uma verificação, a resposta traz uma `authenticationUrl`: você abre esse endereço para o comprador, e a página da Finvia faz a verificação do dispositivo, mostra o desafio do banco e conclui a cobrança. O resultado chega pelos webhooks e pela consulta da cobrança.

> [!NOTE]
>
> **Para o negócio:** é a forma de 3DS com menos trabalho no checkout. A cobrança existe desde o início, com um `id` que você grava no pedido, e só é processada depois que o comprador conclui a autenticação. O comprador não volta sozinho para a loja ao final: o seu checkout precisa abrir a página de autenticação e acompanhar o resultado.

## Quando usar

| Situação | Recomendação |
| - | - |
| Você quer delegar à Finvia as telas de verificação e de desafio | 3DS gerenciado |
| Você quer o resultado do 3DS antes de criar a cobrança | [SDK](https://docs.fastpaybrasil.com/guias/3d-secure/sdk.md) ou [3DS via API](https://docs.fastpaybrasil.com/guias/3d-secure/via-api.md) |
| Você precisa que o comprador volte automaticamente para uma página da loja ao final | Use o [SDK](https://docs.fastpaybrasil.com/guias/3d-secure/sdk.md) ou o [3DS via API](https://docs.fastpaybrasil.com/guias/3d-secure/via-api.md), que rodam dentro do seu checkout |
| Apple Pay | Não se aplica |

## Como funciona

O primeiro desenho mostra o que pode voltar na resposta da criação, conforme a política de 3DS da conta e a decisão do banco.

```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}}}%%
flowchart TB
    CRI["POST /v1/charges<br/>threeDSMode managed<br/>+ browser"]:::lojista
    Q1{"A política de 3DS<br/>da conta dispara?"}:::decisao
    Q2{"Veio browser e o<br/>serviço de 3DS<br/>funcionou?"}:::decisao
    Q3{"3DS obrigatório<br/>na conta?"}:::decisao
    Q4{"O banco pede<br/>verificação<br/>ou desafio?"}:::decisao
    SEM(["Segue sem 3DS<br/>status final na resposta"]):::neutro
    REC(["refused<br/>3ds_required"]):::erro
    FIN(["Sem atrito<br/>status final na resposta"]):::ok
    AUT(["authentication_required<br/>com authenticationUrl"]):::alerta
    CRI --> Q1
    Q1 -->|"não"| SEM
    Q1 -->|"sim"| Q2
    Q2 -->|"não"| Q3
    Q3 -->|"sim"| REC
    Q3 -->|"não"| SEM
    Q2 -->|"sim"| Q4
    Q4 -->|"não"| FIN
    Q4 ==>|"sim"| AUT
    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
    classDef neutro fill:#FFFFFF,stroke:#B8C2D1,stroke-width:1.5px,color:#344054
```

Só o caminho que termina em `authentication_required` exige que o comprador abra a página de autenticação. Nos outros, a resposta já traz o status final.

O segundo desenho mostra esse caminho com autenticação, da criação da cobrança ao resultado.

```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 L as Sua loja (front-end e backend)
    end
    box rgb(234,243,255) Finvia
        participant F as Finvia API
        participant P as Página de autenticação
    end
    box rgb(244,240,255) Fora da Finvia
        participant E as Banco emissor
    end
    L->>F: POST /v1/charges · threeDSMode managed · browser
    F-->>L: 201 · authentication_required · authenticationUrl
    L->>P: Abre a authenticationUrl sem alterar (modal, iframe ou aba)
    alt Comprador conclui em até 15 minutos
        P->>E: Verificação do dispositivo do comprador
        P-->>C: Mostra o desafio do banco, quando pedido
        C->>P: Confirma a compra
        P->>F: POST /v1/three-ds/challenge-result
        P->>F: POST /v1/charges/{id}/resume-3ds
        Note over C,P: A página não leva o comprador de volta à loja
        F-)L: charge.paid, pending, refused ou failed
        L->>F: GET /v1/charges/{id}
        F-->>L: Status final da cobrança
        L-->>C: Fecha o modal e mostra o resultado
    else Abandona ou passa de 15 minutos
        Note over L,P: Fica em authentication_required, sem webhook e sem expirar sozinha. Depois de 15 minutos, crie outra cobrança
    end
```

As chamadas `challenge-result` e `resume-3ds` são feitas pela própria página de autenticação. A sua integração só cria a cobrança, abre a página e acompanha o resultado.

**1. Crie a cobrança**

O seu backend chama `POST /v1/charges` com a chave secreta, cartão, `paymentMethod.threeDSMode: "managed"` e `paymentMethod.browser`. Não envie `threeDS`.

**2. A Finvia decide se o 3DS começa**

O 3DS só é iniciado quando a política de 3DS da sua conta dispara: 3DS habilitado e obrigatório, ou valor da cobrança igual ou acima do mínimo configurado para a conta.

**3. Leia a resposta**

Se o banco aprova sem interação (autenticação sem atrito, ou frictionless), a resposta já traz o status final da cobrança. Se o banco pede verificação de dispositivo ou desafio, a resposta é `201` com `status` `authentication_required`, `reason` `Autenticação 3DS gerenciada necessária`, `paymentDetails` `null` e o campo `authenticationUrl`.

**4. Leve o comprador à authenticationUrl**

Abra o endereço recebido em um modal com iframe, em um iframe na página, em uma nova aba ou janela, ou redirecione na mesma aba. Use o valor exatamente como veio.

**5. A página conduz a autenticação**

A página de autenticação faz a verificação do dispositivo e o desafio do banco emissor. Ao final, ela mesma busca o resultado e retoma a cobrança (`POST /v1/three-ds/challenge-result` e `POST /v1/charges/{id}/resume-3ds`). Você não chama essas rotas.

**6. Receba o resultado**

O resultado chega pelos webhooks da cobrança e pelo postback na `postbackUrl`: `charge.paid`, `charge.pending`, `charge.refused` ou `charge.failed`. Você também pode consultar `GET /v1/charges/{id}`.

**7. Trate o abandono**

Se o comprador não concluir, a cobrança continua em `authentication_required`, sem expiração automática e sem webhook. Os dados do cartão ficam guardados por 15 minutos. Depois disso, a cobrança não pode mais ser concluída e é preciso criar outra.

## Regras de negócio

| Regra | Detalhe |
| - | - |
| Campo de ativação | `paymentMethod.threeDSMode` com o valor `managed` |
| Dados do navegador | `paymentMethod.browser` com `userAgent` e `ipAddress` (IP válido do comprador) obrigatórios. Os demais campos são opcionais |
| Quando o 3DS começa | Só quando a política de 3DS da conta dispara (3DS obrigatório, ou valor igual ou acima do mínimo configurado) |
| Quando aparece `authentication_required` | Só quando o banco pede verificação de dispositivo ou desafio. Sem atrito, a resposta já traz o status final |
| Sem `browser` ou com falha do serviço de 3DS | A cobrança segue sem 3DS. Se o 3DS for obrigatório para a conta, ela é recusada com `reason` `3ds_required: Não foi possível completar a autenticação 3DS obrigatória` |
| `authenticationUrl` | Endereço opaco. Não monte, não altere e não guarde para outra cobrança |
| Quem retoma a cobrança | A própria página de autenticação |
| Resultado | Webhooks `charge.paid`, `charge.pending`, `charge.refused`, `charge.failed`, ou `GET /v1/charges/{id}` |
| Autenticação que não passa | Cobrança recusada com `reason` no formato `3ds_<estado>: Authentication did not succeed` |
| Prazo para concluir | 15 minutos, que é o tempo em que os dados do cartão ficam guardados |
| Cobrança abandonada | Fica em `authentication_required`, sem expiração automática e sem webhook |
| Volta para a loja | Não há. A página não redireciona o comprador para o seu site |
| Formas de pagamento | Cartão digitado e cartão salvo |

> [!WARNING]
>
> Uma cobrança em `authentication_required` não foi paga. Não libere o pedido nesse status e não trate como paga uma cobrança abandonada. Libere só quando a cobrança chegar a `paid`, confirmada por webhook ou por `GET /v1/charges/{id}`.

## Passo a passo

### 1. Colete os dados do navegador

| Campo de `browser` | Tipo | Obrigatório | Onde obter (sugestão) |
| - | - | - | - |
| `userAgent` | string | Sim | `navigator.userAgent` |
| `ipAddress` | string | Sim | No seu servidor, a partir da requisição do comprador. Precisa ser um IP válido |
| `acceptHeader` | string | Não | No seu servidor, cabeçalho `Accept` da requisição |
| `language` | string | Não | `navigator.language` (ex.: `pt-BR`) |
| `timezoneOffset` | integer | Não | `new Date().getTimezoneOffset()` (ex.: `-180`, conforme o contrato) |
| `javascriptEnabled` | boolean | Não | `true` quando o script roda |
| `javaEnabled` | boolean | Não | `navigator.javaEnabled()` |
| `screenWidth` | integer | Não | `screen.width` |
| `screenHeight` | integer | Não | `screen.height` |
| `colorDepth` | integer | Não | `screen.colorDepth` |

> [!TIP]
>
> **Para o desenvolvedor:** o contrato dá `-180` como exemplo de `timezoneOffset` para o horário de Brasília (UTC−3). O `getTimezoneOffset()` do JavaScript devolve `180` nesse fuso, com o sinal invertido. Converta antes de enviar.

```javascript theme={null}
// No navegador: colete e envie ao seu backend junto com o pedido
const browser = {
  userAgent: navigator.userAgent,
  language: navigator.language,
  timezoneOffset: -new Date().getTimezoneOffset(),
  javascriptEnabled: true,
  javaEnabled: navigator.javaEnabled(),
  screenWidth: screen.width,
  screenHeight: screen.height,
  colorDepth: screen.colorDepth,
};
// ipAddress e acceptHeader são preenchidos pelo backend
```

### 2. Crie a cobrança no backend

```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": 350,
  "currency": "BRL",
  "customer": {
    "name": "Ana Lima",
    "email": "ana@email.com",
    "document": {
      "type": "cpf",
      "id": "52998224725"
    },
    "ipAddress": "177.128.144.97"
  },
  "paymentMethod": {
    "type": "credit_card",
    "number": "4111111111111111",
    "holderName": "ANA LIMA",
    "expirationMonth": "10",
    "expirationYear": "2028",
    "cvv": "123",
    "installments": 2,
    "threeDSMode": "managed",
    "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
    }
  },
  "items": [
    {
      "title": "Mentoria online",
      "type": "digital",
      "description": "4 encontros",
      "unit_price": 350,
      "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": 350,
    "currency": "BRL",
    "customer": {
      "name": "Ana Lima",
      "email": "ana@email.com",
      "document": { "type": "cpf", "id": "52998224725" },
      "ipAddress": "177.128.144.97"
    },
    "paymentMethod": {
      "type": "credit_card",
      "number": "4111111111111111",
      "holderName": "ANA LIMA",
      "expirationMonth": "10",
      "expirationYear": "2028",
      "cvv": "123",
      "installments": 2,
      "threeDSMode": "managed",
      "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
      }
    },
    "items": [
      { "title": "Mentoria online", "type": "digital", "description": "4 encontros", "unit_price": 350, "quantity": 1 }
    ],
    "postbackUrl": "https://meusite.com.br/webhooks/finvia"
  }'
```

```javascript Node.js theme={null}
const response = await fetch('https://api-global.fastpaybrasil.com/v1/charges', {
  method: 'POST',
  headers: {
    Authorization: 'Basic ' + Buffer.from(`${process.env.FINVIA_API_KEY}:`).toString('base64'),
    'Content-Type': 'application/json',
  },
  body: JSON.stringify(cobranca), // mesmo corpo do exemplo em cURL
});

const charge = await response.json();

if (charge.status === 'authentication_required') {
  // Devolva charge.authenticationUrl ao front-end e grave charge.id no pedido
} else {
  // Sem atrito ou sem 3DS: o status já é o final (paid, refused, failed...)
}
```

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

import requests

payload = {
    "amount": 350,
    "currency": "BRL",
    "customer": {
        "name": "Ana Lima",
        "email": "ana@email.com",
        "document": {
            "type": "cpf",
            "id": "52998224725",
        },
        "ipAddress": "177.128.144.97",
    },
    "paymentMethod": {
        "type": "credit_card",
        "number": "4111111111111111",
        "holderName": "ANA LIMA",
        "expirationMonth": "10",
        "expirationYear": "2028",
        "cvv": "123",
        "installments": 2,
        "threeDSMode": "managed",
        "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,
        },
    },
    "items": [
        {
            "title": "Mentoria online",
            "type": "digital",
            "description": "4 encontros",
            "unit_price": 350,
            "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' => 350,
    'currency' => 'BRL',
    'customer' => [
        'name' => 'Ana Lima',
        'email' => 'ana@email.com',
        'document' => [
            'type' => 'cpf',
            'id' => '52998224725',
        ],
        'ipAddress' => '177.128.144.97',
    ],
    'paymentMethod' => [
        'type' => 'credit_card',
        'number' => '4111111111111111',
        'holderName' => 'ANA LIMA',
        'expirationMonth' => '10',
        'expirationYear' => '2028',
        'cvv' => '123',
        'installments' => 2,
        'threeDSMode' => 'managed',
        '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,
        ],
    ],
    'items' => [
        [
            'title' => 'Mentoria online',
            'type' => 'digital',
            'description' => '4 encontros',
            'unit_price' => 350,
            '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": 350,
              "currency": "BRL",
              "customer": {
                "name": "Ana Lima",
                "email": "ana@email.com",
                "document": {
                  "type": "cpf",
                  "id": "52998224725"
                },
                "ipAddress": "177.128.144.97"
              },
              "paymentMethod": {
                "type": "credit_card",
                "number": "4111111111111111",
                "holderName": "ANA LIMA",
                "expirationMonth": "10",
                "expirationYear": "2028",
                "cvv": "123",
                "installments": 2,
                "threeDSMode": "managed",
                "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
                }
              },
              "items": [
                {
                  "title": "Mentoria online",
                  "type": "digital",
                  "description": "4 encontros",
                  "unit_price": 350,
                  "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": 350,
  "currency": "BRL",
  "customer": {
    "name": "Ana Lima",
    "email": "ana@email.com",
    "document": {
      "type": "cpf",
      "id": "52998224725"
    },
    "ipAddress": "177.128.144.97"
  },
  "paymentMethod": {
    "type": "credit_card",
    "number": "4111111111111111",
    "holderName": "ANA LIMA",
    "expirationMonth": "10",
    "expirationYear": "2028",
    "cvv": "123",
    "installments": 2,
    "threeDSMode": "managed",
    "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
    }
  },
  "items": [
    {
      "title": "Mentoria online",
      "type": "digital",
      "description": "4 encontros",
      "unit_price": 350,
      "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": 350,
	  "currency": "BRL",
	  "customer": {
	    "name": "Ana Lima",
	    "email": "ana@email.com",
	    "document": {
	      "type": "cpf",
	      "id": "52998224725"
	    },
	    "ipAddress": "177.128.144.97"
	  },
	  "paymentMethod": {
	    "type": "credit_card",
	    "number": "4111111111111111",
	    "holderName": "ANA LIMA",
	    "expirationMonth": "10",
	    "expirationYear": "2028",
	    "cvv": "123",
	    "installments": 2,
	    "threeDSMode": "managed",
	    "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
	    }
	  },
	  "items": [
	    {
	      "title": "Mentoria online",
	      "type": "digital",
	      "description": "4 encontros",
	      "unit_price": 350,
	      "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" => 350,
  "currency" => "BRL",
  "customer" => {
    "name" => "Ana Lima",
    "email" => "ana@email.com",
    "document" => {
      "type" => "cpf",
      "id" => "52998224725",
    },
    "ipAddress" => "177.128.144.97",
  },
  "paymentMethod" => {
    "type" => "credit_card",
    "number" => "4111111111111111",
    "holderName" => "ANA LIMA",
    "expirationMonth" => "10",
    "expirationYear" => "2028",
    "cvv" => "123",
    "installments" => 2,
    "threeDSMode" => "managed",
    "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,
    },
  },
  "items" => [
    {
      "title" => "Mentoria online",
      "type" => "digital",
      "description" => "4 encontros",
      "unit_price" => 350,
      "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
```

Resposta `201` quando o banco pede verificação ou desafio:

```json theme={null}
{
  "id": "2vorkDcXyvzifL63YX09S9VqcnI",
  "status": "authentication_required",
  "paymentDetails": null,
  "reason": "Autenticação 3DS gerenciada necessária",
  "authenticationUrl": "https://<endereço recebido na resposta>"
}
```

O valor de `authenticationUrl` no exemplo é ilustrativo. Use sempre o endereço que vier na resposta: o host pode mudar, e a URL carrega parâmetros da autenticação que não devem ser alterados.

> [!NOTE]
>
> Quando o banco aprova sem interação, a mesma chamada devolve direto o status final (por exemplo, `paid`), sem `authenticationUrl`. Trate os dois casos no seu código.

### 3. Abra a página de autenticação

Envie a `authenticationUrl` ao front-end e abra para o comprador. A página aceita ser exibida em iframe.

```html theme={null}
<div id="modal-3ds" hidden>
  <iframe id="iframe-3ds" width="600" height="600" title="Autenticação do banco"></iframe>
  <button id="fechar-3ds" type="button">Fechar</button>
</div>
```

```javascript theme={null}
function abrirAutenticacao(authenticationUrl) {
  document.getElementById('iframe-3ds').src = authenticationUrl;
  document.getElementById('modal-3ds').hidden = false;
  aguardarResultado(); // veja o passo 4
}
```

Se preferir, abra em nova aba (`window.open(authenticationUrl, '_blank')`) ou redirecione a aba atual. No redirecionamento, o comprador não volta sozinho para a loja: ele fica na página de autenticação ao final.

> [!WARNING]
>
> A página de autenticação não leva o comprador de volta ao seu site e não informa o resultado à sua página. Ao final, ela pode mostrar uma mensagem de confirmação ou ficar em branco. Não use o que a página exibe como resultado do pagamento. O resultado vale só pelo webhook ou pela consulta da cobrança.

> [!NOTE]
>
> A página de autenticação ainda exibe o logotipo e o rodapé com o nome anterior da marca. Isso é esperado.

### 4. Acompanhe o resultado

Ao concluir a autenticação, a página retoma a cobrança e a Finvia envia o evento correspondente aos seus endpoints de webhook e à `postbackUrl` da cobrança:

| Evento | Quando |
| - | - |
| `charge.paid` | Cobrança aprovada |
| `charge.pending` | O adquirente deixou a cobrança pendente |
| `charge.refused` | Cobrança recusada. Se a autenticação não passou, `reason` vem no formato `3ds_<estado>: Authentication did not succeed` |
| `charge.failed` | Falha no processamento |

No front-end, enquanto o modal está aberto, consulte o seu backend para saber se o webhook já chegou. No backend, você pode confirmar com a consulta da cobrança:

```bash theme={null}
curl "https://api-global.fastpaybrasil.com/v1/charges/2vorkDcXyvzifL63YX09S9VqcnI" \
  -u "$FINVIA_API_KEY:"
```

Quando o status sair de `authentication_required`, feche o modal e mostre o resultado ao comprador.

### 5. Trate o abandono

| Situação | O que acontece | O que fazer |
| - | - | - |
| O comprador fecha o modal sem concluir | A cobrança continua em `authentication_required` | Não libere o pedido. Ofereça uma nova tentativa com uma nova cobrança |
| O comprador conclui depois de 15 minutos | A retomada falha com `Dados de autenticação expiraram. Crie uma nova cobrança.` e a cobrança não é processada | Crie uma nova cobrança |
| O comprador nunca conclui | A cobrança fica em `authentication_required`, sem expiração automática e sem webhook | Defina no seu sistema um prazo para considerar o pedido abandonado |

## Erros comuns

| Sintoma | Causa | Como resolver |
| - | - | - |
| Resposta sem `authenticationUrl` e com status final | O banco aprovou sem atrito, ou a política de 3DS da conta não disparou | Siga com o status recebido |
| Cobrança `refused` com `3ds_required: Não foi possível completar a autenticação 3DS obrigatória` | 3DS obrigatório na conta e a cobrança foi enviada sem `browser`, ou o serviço de 3DS falhou | Envie `browser` com `userAgent` e `ipAddress` válidos e tente com uma nova cobrança |
| Cobrança `refused` com `3ds_<estado>: Authentication did not succeed` | O comprador não passou na autenticação do banco | Ofereça nova tentativa com outro cartão ou outra forma de pagamento |
| Comprador fica parado na página de autenticação ao final | A página não redireciona para a loja | Abra a página em modal, iframe ou nova aba e acompanhe o resultado pelo seu backend |
| Pedido liberado sem pagamento | O código tratou `authentication_required` como sucesso | Libere só com `paid` confirmado |
| Cobrança presa em `authentication_required` | O comprador abandonou a autenticação | Considere o pedido abandonado depois do seu prazo e crie nova cobrança se o comprador voltar |

## Perguntas frequentes

> [accordion] Preciso chamar resume-3ds ou challenge-result?
>
> Não. No 3DS gerenciado, a página aberta pela `authenticationUrl` faz essas chamadas. A sua integração só cria a cobrança, abre a página e acompanha o resultado.

> [accordion] Toda cobrança com threeDSMode managed vai para authentication\_required?
>
> Não. Isso só acontece quando a política de 3DS da conta dispara e o banco pede verificação de dispositivo ou desafio. Na autenticação sem atrito, a resposta já traz o status final. Sem os dados do navegador ou com falha do serviço de 3DS, a cobrança segue sem 3DS, ou é recusada se o 3DS for obrigatório para a conta.

> [accordion] Posso montar a authenticationUrl no meu código?
>
> Não. Use o valor recebido na resposta, sem alterar. O host e os parâmetros são definidos pela Finvia e podem mudar.

> [accordion] O comprador volta para a minha loja ao final?
>
> Não. A página de autenticação não redireciona para o seu site. Por isso, a recomendação é abrir a página em modal, iframe ou nova aba e acompanhar o resultado por webhook ou consulta.

> [accordion] Quanto tempo o comprador tem para concluir?
>
> Os dados do cartão ficam guardados por 15 minutos. Depois disso, a cobrança não pode mais ser concluída e é preciso criar outra.

> [accordion] Posso usar o 3DS gerenciado com cartão salvo?
>
> Sim. A variante de cartão salvo aceita `threeDSMode` `managed`, com `browser` junto.

## 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: criação com `threeDSMode` `managed` que volte `authentication_required` com `authenticationUrl`, autenticação concluída na página com o webhook `charge.paid` recebido, e o tratamento de uma cobrança abandonada em `authentication_required`.

## Veja também

> [card] [3D Secure: visão geral](https://docs.fastpaybrasil.com/guias/3d-secure/visao-geral.md)
>
> Comparativo das três formas de integrar.

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

> [card] [Webhooks de cobrança](https://docs.fastpaybrasil.com/guias/webhooks/cobranca.md)
>
> Eventos que trazem o resultado.

> [card] [Retomar cobrança](https://docs.fastpaybrasil.com/referencia/3d-secure/retomar-cobranca.md)
>
> Rota usada pela página de autenticação.


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