Antifraude

1. O que é o Antifraude?

O Antifraude é uma camada de segurança utilizada para analisar o risco das transações com cartão antes da continuidade do processamento.

A análise considera informações relacionadas ao comprador, dispositivo, pagamento e contexto da compra, permitindo identificar comportamentos ou características associados a um possível risco de fraude.

Os sistemas de antifraude integrados são o da Konduto e o da ClearSale.

2. Qual problema o Antifraude resolve?

Reduz o risco de fraudes ao adicionar uma etapa de análise antes da continuidade do pagamento. Para o seu negócio e seus estabelecimentos, isso contribui para:

reduzir a exposição a transações potencialmente fraudulentas;
adicionar inteligência à análise de risco das compras;
apoiar a prevenção de perdas relacionadas a fraude;
utilizar informações da jornada de compra para avaliar o contexto da transação.

3. Como funciona?

Durante a criação da cobrança ou assinatura, você envia as informações disponíveis para a análise antifraude no objeto Antifraud da requisição.

🚧
O campo Antifraud.ip (IP do cliente) é o único campo obrigatório. Os demais são opcionais, mas recomendamos preencher o maior conjunto possível de informações: quanto maior o contexto, melhor é a análise de risco.

🚫
Se a transação for negada pelo Antifraude, ela não segue para autorização na adquirente e fica com o status "negada por recomendação do antifraude". Apenas as transações aprovadas na análise de risco continuam o processamento.

Recorrência

Você pode enviar o objeto Antifraud em todas as transações recorrentes. Internamente, a Celcoin identifica se a transação é a primeira da recorrência ou uma das seguintes e define se ela seguirá para a análise antifraude.

4. Endpoints que recebem o objeto Antifraud

Você continua utilizando os mesmos endpoints, sem mudança de autenticação. A única diferença é incluir o objeto Antifraud dentro de PaymentMethodCreditCard no corpo da requisição.

Fluxo	Método	Referência
Cobrança avulsa	POST	Criar cobrança
Assinatura com ou sem plano	POST	Criar assinatura

Os campos do Antifraud são os mesmos nos dois fluxos.

5. Como operar o Antifraude

Para clientes que utilizam chekout próprio, antes de enviar os dados na requisição, prepare o seu front-end.

5.1 Instalar o script de identificação

Implemente em todas as páginas do seu e-commerce o script do antifraude contratado. Ele identifica o ambiente em que a transação é originada e coleta informações para a análise de risco. Cole o código imediatamente abaixo da tag <body>.

Konduto

A chave pública (PUBLIC_KEY) é enviada por e-mail pela Konduto.

var __kdt = __kdt || [];
__kdt.push({"public_key": "<PUBLIC_KEY_KONDUTO>"}); // A chave pública identifica a sua loja

(function() {
  var kdt = document.createElement('script');
  kdt.id = 'kdtjs'; kdt.type = 'text/javascript';
  kdt.async = true; kdt.src = 'https://i.k-analytix.com/k.js';
  var s = document.getElementsByTagName('body')[0];
  s.parentNode.insertBefore(kdt, s);
})();

5.2 Obter o `sessionId` no checkout

Na página de checkout, recupere o sessionId com o código abaixo. O valor de visitorID é o que deve ser enviado no campo Antifraud.sessionId.

window.onload = function() {
  var period = 300;
  var limit = 20 * 1e3;
  var nTry = 0;
  var intervalID = setInterval(function() {
    var clear = limit / period <= ++nTry;
    if ((typeof(Konduto) !== "undefined") &&
        (typeof(Konduto.getVisitorID) !== "undefined")) {
      visitorID = window.Konduto.getVisitorID(); // valor do sessionId a ser enviado via API

      // Exemplo: cria um input hidden no formulário com o sessionId (opcional)
      var element = document.createElement("input");
      element.type = "hidden";
      element.name = "sessionId";
      element.value = visitorID;
      document.getElementById("idDoSeuFormulario").appendChild(element);

      clear = true;
    }
    if (clear) {
      clearInterval(intervalID);
    }
  }, period);
};

5.3 Meta tags (opcional, recomendado)

Para aumentar a eficiência do antifraude, adicione as meta tags abaixo:

<!-- Todas as páginas do checkout -->
<meta name="kdt:page" content="checkout">

<!-- Detalhe de produto -->
<meta name="kdt:page" content="product">
<meta name="kdt:product" content="sku=123, name=Camiseta Verde">

<!-- Página de 'Esqueci minha senha' -->
<meta name="kdt:page" content="password-reset">

6. Enviar os dados na transação

Com os scripts implementados e o sessionId obtido, envie o objeto Antifraud na requisição de cobrança ou assinatura.

Fluxo de operação

Instalar script de identificação no front-end
        ↓
Configurar a chave pública
        ↓
Implementar o script de sessionId no checkout
        ↓
Obter o sessionId
        ↓
Enviar sessionId + IP + demais dados na cobrança/assinatura
        ↓
Análise Antifraude

7. Campos do objeto `Antifraud`

Objeto: PaymentMethodCreditCard.Antifraud

Identificação da transação

Campo	Descrição	Tipo	Obrigatório
`ip`	IPv4/IPv6 do cliente	string	Sim
`sessionId`	Identificador da sessão, obtido pelo script do checkout	string	Não

Cliente (`Customer`)

Campo	Descrição	Tipo	Obrigatório
`id`	Identificador único do cliente. Deve ser mantido em compras futuras	string	Não
`dateOfBirth`	Data de nascimento (`YYYY-MM-DD`)	string	Não
`documentType`	Tipo de documento: `CPF`, `CNPJ`, `RG`, `PASSPORT`, `OTHER`, `CPF_CNPJ`	string	Não
`phone1` / `phone2`	Telefones do cliente	string	Não
`new`	Indica conta recém-criada para esta compra	boolean	Não
`vip`	Indica cliente VIP ou comprador frequente	boolean	Não
`type`	Tipo do cliente	string	Não
`riskLevel`	Nível de risco	string	Não
`riskScore`	Score de risco	string	Não
`motherName`	Nome da mãe	string	Não

Dispositivo (`Device`)

Campo	Descrição	Tipo	Obrigatório
`fingerprint`	Identificação do navegador (mín. 3, máx. 255)	string	Não
`provider`	Provedor	string	Não
`model`	Modelo	string	Não
`platform`	Plataforma/dispositivo utilizado	string	Não
`manufacturer`	Fabricante	string	Não
`os`	Sistema operacional	string	Não
`browser`	Navegador	string	Não
`language`	Idioma (ex.: `pt-BR`)	string	Não

Endereço de cobrança (`Billing`)

Campo	Descrição	Tipo	Obrigatório
`name`	Nome do comprador	string	Não
`address1`	Endereço principal	string	Não
`address2`	Complemento/endereço secundário	string	Não
`city`	Cidade	string	Não
`state`	Estado	string	Não
`zip`	CEP	string	Não
`country`	País (ISO 3166-2)	string	Não

Pagamento (`Payment`)

Campo	Descrição	Tipo	Obrigatório
`bin`	Identificação do cartão: primeiros 6 a 10 números	string	Não
`last4`	Últimos 4 dígitos do cartão	string	Não
`expirationDate`	Validade do cartão (`MMAAAA`)	string	Não
`description`	Alguma informação referente ao desconto	string	Não
`taxId`	CPF do titular	string	Não
`cvvResult`	Código do resultado da verificação do CVV	string	Não
`avsResult`	Código do resultado da verificação de endereço (AVS)	string	Não
`sha1`	Código de pagamento de integridade (HMAC-SHA-256 dos campos da notificação)	string	Não
`name`	Nome do comprador	string	Não
`holder`	Nome do titular do cartão	string	Não
`amount`	Valor total do pedido	number	Não

Compra (`Cart`)

Campo	Descrição	Tipo	Obrigatório
`sku`	SKU do produto	string	Não
`productCode`	Código do produto	string	Não
`name`	Nome do produto	string	Não
`description`	Descrição do produto	string	Não
`unitCost`	Valor unitário	number	Não
`quantity`	Quantidade	number	Não
`discount`	Desconto	number	Não
`createdAt`	Data de criação	string	Não
`deliveryType`	Tipo de entrega	string	Não
`deliverySlaInMinutes`	SLA de entrega em minutos	number	Não
`sellerId`	Identificador do vendedor	string	Não

📌
Somente o campo ip é obrigatório. Todos os demais são opcionais, mas quanto mais dados você enviar, melhor será a análise de risco.

8. Exemplos de payload

Apenas o corpo da requisição é exibido. Endpoint e autenticação permanecem inalterados. Os valores abaixo são fictícios: substitua pelos dados reais da transação.

8.1 Cobrança avulsa

POST Criar cobrança

curl --request POST \
     --url 'https://sandbox.openfinance.celcoin.dev/baas/v1/cash/charges?account=1234' \
     --header 'accept: application/json' \
     --header 'content-type: application/json' \
     --data '
{
  "Customer": {
    "name": "Maria Exemplo",
    "document": "12345678909",
    "emails": ["[email protected]"]
  },
  "payday": "2026-10-01",
  "mainPaymentMethodId": "creditcard",
  "value": 12999,
  "PaymentMethodCreditCard": {
    "Antifraud": {
      "ip": "203.0.113.10",
      "sessionId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
      "Customer": {
        "id": "cliente-0001",
        "dateOfBirth": "1990-01-31",
        "documentType": "CPF",
        "phone1": "11999990000",
        "phone2": "1133330000",
        "new": false,
        "vip": false,
        "type": "PF",
        "riskLevel": "low",
        "riskScore": "10",
        "motherName": "Ana Exemplo"
      },
      "Device": {
        "fingerprint": "f3a9c1d27b5e4a60",
        "provider": "Vivo",
        "model": "Galaxy S23",
        "platform": "Mobile",
        "manufacturer": "Samsung",
        "os": "Android 14",
        "browser": "Chrome",
        "language": "pt-BR"
      },
      "Billing": {
        "name": "Maria Exemplo",
        "address1": "Rua Exemplo, 100",
        "address2": "Apto 12",
        "city": "São Paulo",
        "state": "SP",
        "zip": "01000000",
        "country": "BR"
      },
      "Payment": {
        "bin": "411111",
        "last4": "1111",
        "expirationDate": "122030",
        "holder": "MARIA EXEMPLO",
        "amount": 12999
      },
      "Cart": {
        "sku": "SKU-0001",
        "productCode": "PROD-0001",
        "name": "Produto Exemplo",
        "description": "Descrição do produto exemplo",
        "unitCost": 12999,
        "quantity": 1,
        "createdAt": "2026-10-01",
        "deliveryType": "digital",
        "deliverySlaInMinutes": 0,
        "sellerId": "seller-0001"
      }
    }
  }
}

📘
Os demais campos de PaymentMethodCreditCard (dados do cartão) continuam sendo enviados exatamente como você já faz hoje. O exemplo acima destaca apenas o Antifraud.

8.2 Assinatura (com ou sem plano)

POST Criar assinatura

Mantenha o corpo da assinatura como já utiliza e inclua o Antifraud dentro de PaymentMethodCreditCard, com os mesmos campos da cobrança avulsa:

curl --request POST \
     --url 'https://sandbox.openfinance.celcoin.dev/baas/v1/cash/subscriptions?account=1234' \
     --header 'accept: application/json' \
     --header 'content-type: application/json' \
     --data '
{
  "firstPayDayDate": "2026-10-01",
  "mainPaymentMethodId": "creditcard",
  "Customer": {
    "name": "Maria Exemplo",
    "document": "12345678909",
    "emails": [
      "[email protected]"
    ]
  },
  "PaymentMethodCreditCard": {
    "Antifraud": {
      "ip": "203.0.113.10",
      "sessionId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
      "Customer": {
        "id": "cliente-0001",
        "dateOfBirth": "1990-01-31",
        "documentType": "CPF",
        "phone1": "11999990000",
        "phone2": "1133330000",
        "new": false,
        "vip": false,
        "type": "PF",
        "riskLevel": "low",
        "riskScore": "10",
        "motherName": "Ana Exemplo"
      },
      "Device": {
        "fingerprint": "f3a9c1d27b5e4a60",
        "provider": "Vivo",
        "model": "Galaxy S23",
        "platform": "Mobile",
        "manufacturer": "Samsung",
        "os": "Android 14",
        "browser": "Chrome",
        "language": "pt-BR"
      },
      "Billing": {
        "name": "Maria Exemplo",
        "address1": "Rua Exemplo, 100",
        "address2": "Apto 12",
        "city": "São Paulo",
        "state": "SP",
        "zip": "01000000",
        "country": "BR"
      },
      "Payment": {
        "bin": "411111",
        "last4": "1111",
        "expirationDate": "122030",
        "holder": "MARIA EXEMPLO",
        "amount": 12999
      },
      "Cart": {
        "sku": "SKU-0001",
        "productCode": "PROD-0001",
        "name": "Produto Exemplo",
        "description": "Descrição do produto exemplo",
        "unitCost": 12999,
        "quantity": 1,
        "createdAt": "2026-10-01",
        "deliveryType": "digital",
        "deliverySlaInMinutes": 0,
        "sellerId": "seller-0001"
      }
    }
  }
}
'

Caso a transação seja negada pelo Antifraude, a transação não segue para autorização na adquirente e é retornada no endpoint com o status "negada por recomendação do antifraude".

Updated about 21 hours ago

Did this page help you?

1. O que é o Antifraude?

2. Qual problema o Antifraude resolve?

3. Como funciona?

Recorrência

4. Endpoints que recebem o objeto Antifraud

5. Como operar o Antifraude

5.1 Instalar o script de identificação

5.2 Obter o sessionId no checkout

5.3 Meta tags (opcional, recomendado)

6. Enviar os dados na transação

7. Campos do objeto Antifraud

Identificação da transação

Cliente (Customer)

Dispositivo (Device)

Endereço de cobrança (Billing)

Pagamento (Payment)

Compra (Cart)

8. Exemplos de payload

8.1 Cobrança avulsa

8.2 Assinatura (com ou sem plano)

5.2 Obter o `sessionId` no checkout

7. Campos do objeto `Antifraud`

Cliente (`Customer`)

Dispositivo (`Device`)

Endereço de cobrança (`Billing`)

Pagamento (`Payment`)

Compra (`Cart`)