Pedido com 3DS (3D Secure)

Este guia descreve o fluxo completo para criação de pedidos utilizando 3D Secure (3DS), incluindo a criação da sessão, coleta de dados do navegador e, quando necessário, o desafio de autenticação (Ste

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

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

Response

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

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

Response

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

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

{
  "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": "[email protected]",
      "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": "[email protected]",
      "mobilePhone": "34999991111"
    }
  },
  "uuidBuyer": "1ee849a4-6bb3-47f0-b32a-293a8f0e811c"
}

Response (resumo)

{
  "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": "[email protected]",
    "phone": "34999991111",
    "alternativeEmail": "[email protected]",
    "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": "[email protected]",
        "phone": "34999991111",
        "alternativeEmail": "[email protected]"
      }
    }
  ],
  "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

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

O status da transação é atualizado na Barte
Um webhook é disparado para o seu sistema
Seu sistema deve validar o evento recebido
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.

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.

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

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

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

PreviousPedido com Cartão Tokenizado NextLinks de Pagamento

Last updated 20 days ago

Was this helpful?

Good afternoon

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

hashtagEndpoint

hashtagBody

hashtagResponse

hashtag2. Criar sessão 3DS

hashtagEndpoint

hashtagBody

hashtagResponse

hashtag3. Coletar dados do navegador (Browser Data Collection)

hashtagObjetivo

hashtagScript de coleta

hashtag4. Criar pedido com 3DS

hashtagEndpoint

hashtagBody (exemplo)

hashtagResponse (resumo)

hashtag5. Desafio 3DS (Step Up Challenge)

hashtagScript de Step Up

hashtagResumo de decisão

hashtag🔔 Confirmação do pagamento

hashtagrotate Fluxo resumido

hashtagCampos importantes no 3DS

hashtagthumbtack-angle Importante sobre 3DS

hashtaglightbulb Boas práticas

hashtaghexagon-xmark O que não fazer

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

Endpoint

Body

Response

2. Criar sessão 3DS

Endpoint

Body

Response

3. Coletar dados do navegador (Browser Data Collection)

Objetivo

Script de coleta

4. Criar pedido com 3DS

Endpoint

Body (exemplo)

Response (resumo)

5. Desafio 3DS (Step Up Challenge)

Script de Step Up

Resumo de decisão

🔔 Confirmação do pagamento

Fluxo resumido

Campos importantes no 3DS

Importante sobre 3DS

Boas práticas

O que não fazer