# Pedido com 3DS (3D Secure)

***

### 1. Criar Card Token (Tokenização de Cartão)

A tokenização permite armazenar o cartão de forma segura para uso posterior.

#### Endpoint

```
POST /payment/v1/cards
https://api.barte.com/payment/v1/cards
```

#### Body

```json
{
  "holderName": "JOSE DAS NEVES TEST",
  "number": "5383638854440891",
  "cvv": "220",
  "expiration": "12/2025",
  "checkZeroDollar": true,
  "buyerUuid": "1ee849a4-6bb3-47f0-b32a-293a8f0e811c"
}
```

#### Response

```json
{
  "uuid": "80efb136-e65e-4fa3-b76a-6ee5a1953c4c",
  "status": "ACTIVE",
  "cardId": "83d353d2-716f-45cf-837f-50c18f10efa0"
}
```

⚠️ **Importante**

* O **cardToken** utilizado na transação é o campo **uuid**
* O campo **cardId** será utilizado **apenas na criação da sessão 3DS**
* Caso `checkZeroDollar` seja `false`, o token pode iniciar com status `PENDING` e será atualizado para `ACTIVE` após a primeira transação bem-sucedida

***

### 2. Criar sessão 3DS

A sessão 3DS é necessária para iniciar o processo de autenticação.

#### Endpoint

```
POST /v1/3ds/session
https://api.barte.com/v1/3ds/session
```

#### Body

```json
{
  "sourceType": "card",
  "cardId": "3fa85f64-5717-4562-b3fc-2c963f66afa6"
}
```

#### Response

```json
{
  "id": "701d8f14-9b5f-40b0-8013-422e0020c522",
  "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "collectUrl": "https://centinelapistag.cardinalcommerce.com/V1/Cruise/Collect",
  "providerType": "CYBERSOURCE"
}
```

📌 Guarde:

* **id** → será enviado como `setupId` na criação do pedido
* **token** e **collectUrl** → usados na coleta de dados do navegador

***

### 3. Coletar dados do navegador (Browser Data Collection)

Antes de criar o pedido, é obrigatório coletar os dados do navegador do cliente.

#### Objetivo

Enviar informações de background do navegador para o provedor 3DS.

#### Script de coleta

```html
<div style="display: none;">
  <iframe id="cardinal_collection_iframe" name="collectionIframe" height="1" width="1"></iframe>
  <form id="cardinal_collection_form" method="POST" target="collectionIframe">
    <input id="cardinal_collection_form_input" type="text" name="JWT" value="">
  </form>
</div>

<script>
  const collectUrl = '<collectUrl>';
  const token = '<token>';

  const docFormCardinal = document.getElementById('cardinal_collection_form');
  const docInputCardinal = document.getElementById('cardinal_collection_form_input');

  docFormCardinal.action = collectUrl;
  docInputCardinal.value = token;
  docFormCardinal.submit();

  window.addEventListener("message", function (event) {
    const origin = new URL(collectUrl).origin;
    if (event.origin === origin) {
      const data = JSON.parse(event.data);
      console.log('COLETA FINALIZADA:', data);
    }
  });
</script>
```

⚠️ **Importante**

* O seller deve aguardar a finalização da coleta antes de criar o pedido
* A coleta é rápida (≈ 1 segundo)

***

### 4. Criar pedido com 3DS

Após a coleta, o pedido pode ser criado informando os dados de 3DS.

#### Endpoint

```
POST /v2/orders
https://api.barte.com/v2/orders
```

#### Body (exemplo)

```json
{
  "startDate": "2026-01-30",
  "value": 100,
  "installments": 1,
  "urlCallBack": "https://webhook.site/unique-id",
  "title": "Compra Exemplo",
  "description": "Descrição da compra",
  "payment": {
    "method": "CREDIT_CARD_EARLY_SELLER",
    "card": {
      "cardToken": "80efb136-e65e-4fa3-b76a-6ee5a1953c4c",
      "cvv": "220"
    },
    "fraudData": {
      "document": "48637879012",
      "name": "John Doe",
      "email": "johndoe@barte.com",
      "phone": "34999991111",
      "billingAddress": {
        "country": "BR",
        "state": "Minas Gerais",
        "city": "Uberlândia",
        "district": "Jardim Europa",
        "street": "Rua Orleans",
        "zipCode": "38414552",
        "number": "100",
        "complement": "Bloco A"
      }
    }
  },
  "threeDSecure": {
    "dataOnly": false,
    "requiresLiabilityShift": false,
    "setupId": "701d8f14-9b5f-40b0-8013-422e0020c522",
    "redirectURL": "https://meudominio.com/checkout.html",
    "requestorURL": "https://meudominio.com",
    "browser": {
      "ip": "127.0.0.1",
      "userAgent": "Mozilla/5.0 (X11; Linux x86_64) AppleWebKit/537.36",
      "acceptHeader": "text/html,application/xhtml+xml,application/xml;q=0.9,image/webp,image/apng,*/*;q=0.8",
      "language": "pt-BR",
      "colorDepth": 24,
      "screenHeight": 1080,
      "screenWidth": 1920,
      "timeZoneOffset": "-180",
      "javaEnabled": false,
      "javaScriptEnabled": true
    },
    "billingAddress": {
      "country": "BR",
      "state": "Minas Gerais",
      "city": "Uberlândia",
      "district": "Jardim Europa",
      "street": "Rua Orleans",
      "zipCode": "38414552",
      "streetNumber": "100"
    },
    "shippingAddress": {
      "city": "Uberlândia",
      "country": "BR",
      "streetNumber": "123",
      "zipCode": "38411999",
      "state": "MG",
      "street": "Rua Exemplo"
    },
    "cardHolder": {
      "email": "johndoe@barte.com",
      "mobilePhone": "34999991111"
    }
  },
  "uuidBuyer": "1ee849a4-6bb3-47f0-b32a-293a8f0e811c"
}
```

#### Response (resumo)

```json
{
  "uuid": "4668ab70-39c3-4ab3-8770-995f6333e200",
  "status": "SENT",
  "title": "Compra Exemplo",
  "description": "Descrição da compra",
  "value": 100,
  "installments": 1,
  "startDate": "2026-01-30",
  "payment": "CREDIT_CARD_EARLY_SELLER",
  "customer": {
    "document": "48637879012",
    "type": "CPF",
    "documentCountry": "BR",
    "name": "John Doe",
    "email": "johndoe@barte.com",
    "phone": "34999991111",
    "alternativeEmail": "johndoealt@barte.copm",
    "integrationCustomerId": "1ee849a4-6bb3-47f0-b32a-293a8f0e811c"
  },
  "idempotencyKey": "5e643a79-3b3f-4db9-95a3-a998caf914ff",
  "subSellerPaymentResponse": [
    {}
  ],
  "charges": [
    {
      "uuid": "27dccdbb-73a9-4799-93c9-e30e2c71cc75",
      "title": "Compra Exemplo",
      "expirationDate": "2026-01-30",
      "value": 100,
      "paymentMethod": "CREDIT_CARD_EARLY_SELLER",
      "status": "SCHEDULED",
      "customer": {
        "document": "48637879012",
        "type": "CPF",
        "name": "John Doe",
        "email": "johndoe@barte.com",
        "phone": "34999991111",
        "alternativeEmail": "johndoealt@barte.com"
      }
    }
  ],
  "threeDSResponse": {
    "dataOnly": false,
    "requiresLiabilityShift": false,
    "redirectURL": "http://meudominio.com/checkout.html",
    "browser": {
      "ip": "127.0.0.1",
      "userAgent": "Mozilla/5.0 (X11; Linux x86_64) AppleWebKit/537.36",
      "acceptHeader": "text/html,application/xhtml+xml,application/xml;q=0.9,image/webp,image/apng,*/*;q=0.8",
      "language": "pt-BR",
      "screenHeight": 1080,
      "screenWidth": 1920,
      "javaEnabled": false,
      "javaScriptEnabled": true
    },
    "auth": {
      "action": "REDIRECT",
      "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
      "stepUrl": "https://centinelapistag.cardinalcommerce.com/V2/Cruise/StepUp"
    },
    "challenged": true,
    "authenticated": false,
    "offeredType": "Challenge",
    "liabilityShift": false
  }
}
```

***

### 5. Desafio 3DS (Step Up Challenge)

O desafio só é necessário quando:

```
threeDSResponse.challenged = true
```

#### Script de Step Up

```html
<div style="display: none;">
  <form id="step_up_form" method="POST">
    <input id="step_up_form_jwt_input" type="text" name="JWT">
  </form>
  <iframe id="step_up_iframe" name="stepUpIframe" height="800px" width="400px"></iframe>
</div>

<script>
  const stepUrl = '<stepUrl>';
  const token = '<token>';

  const docFormStep = document.getElementById('step_up_form');
  const docInputStepJwt = document.getElementById('step_up_form_jwt_input');

  docFormStep.action = stepUrl;
  docInputStepJwt.value = token;
  docFormStep.submit();
</script>
```

⚠️ Observações importantes:

* O iframe apresenta o desafio do banco emissor
* Ao finalizar, o cliente é redirecionado para o `redirectURL`
* O **status final da transação** será enviado via **webhook**

***

### Resumo de decisão

* `challenged = false` → pagamento segue normalmente (PAID / FAILED)
* `challenged = true` → exige Step Up Challenge
* Resultado final sempre confirmado via webhook

### 🔔 Confirmação do pagamento

Após o cliente realizar o pagamento:

1. O status da transação é atualizado na Barte
2. Um webhook é disparado para o seu sistema
3. Seu sistema deve validar o evento recebido
4. A confirmação do pagamento deve ser feita **exclusivamente via webhook**

📌 Isso se aplica a **cartão, PIX e boleto**, inclusive quando o cartão retorna `PAID` de forma síncrona.

***

### <i class="fa-rotate">:rotate:</i> Fluxo resumido

```
Criar pedido
     ↓
Cliente realiza pagamento
     ↓
Status atualizado na Barte
     ↓
Webhook enviado
     ↓
Seu sistema confirma o pagamento
```

***

#### Campos importantes no 3DS

**`threeDSecure.setupId`**

ID da sessão 3DS criada previamente.

**`threeDSResponse.challenged`**

* `true` → exige desafio (Step Up)
* `false` → fluxo segue normalmente

**`threeDSResponse.auth.action`**

* `REDIRECT` → redirecionamento para autenticação

📌 **O resultado final do 3DS nunca deve ser inferido no frontend.**

***

### <i class="fa-thumbtack-angle">:thumbtack-angle:</i> Importante sobre 3DS

* O cliente pode ser autenticado com sucesso **e ainda assim** o pagamento falhar
* O redirecionamento não confirma o pagamento
* **Somente o webhook indica o estado final da transação**

***

### <i class="fa-lightbulb">:lightbulb:</i> Boas práticas

* Sempre utilize webhooks para confirmar pagamento
* Armazene:
  * `uuid` do pedido
  * `uuid` da charge
* Trate webhooks de forma idempotente
* Use `metadata` para rastreabilidade interna
* Aguarde a finalização da coleta de navegador no 3DS

***

### <i class="fa-hexagon-xmark">:hexagon-xmark:</i> O que não fazer

* Confirmar pagamento sem webhook
* Reutilizar pedidos para novas cobranças
* Assumir sucesso após retorno síncrono do cartão
* Criar pedido 3DS antes da coleta de navegador
* Expor sua chave de API no frontend


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.barte.com/guias/passo-a-passo-do-vendedor/2o-criando-pedidos-or-links-de-pagamento-or-assinaturas/pedidos/pedido-com-3ds-3d-secure.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.