Documentação da API

API antifraude: avalie cada pagamento antes do intermediador

Uma API antifraude recebe dados do pagamento, do cliente e do aparelho e devolve em tempo real um score de risco e uma recomendação. Com a RiskCogs, você carrega o SDK no checkout, envia sessão e pedido do servidor para POST /v1/risk-score, age conforme a recomendação e informa o resultado final.

Comece grátis no modo shadow

1. Carregue o SDK no checkout

O SDK coleta, com consentimento do usuário, contexto de aparelho e sessão e devolve um ID de sessão para o servidor. Endpoint e chave ficam no console da RiskCogs.

import { RiskCogs } from '@fraud/sdk-browser';

const risk = await RiskCogs.init({ endpoint: 'https://YOUR_RISKCOGS_INTAKE_HOST', publicKey: 'pub_YOUR_PUBLISHABLE_KEY' });
// On checkout submit: pass the session to your server score request.
const { sessionId } = await risk.getContext();

2. Avalie o pagamento no servidor

Chame a API antes de enviar o pagamento ao intermediador. Node 18 ou superior dispensa bibliotecas.

// Server only: the secret (pr_*) key never reaches a browser.
const res = await fetch('https://YOUR_RISKCOGS_API_HOST/v1/risk-score', {
  method: 'POST',
  headers: { 'X-API-Key': process.env.RISKCOGS_SECRET_KEY, 'Content-Type': 'application/json' },
  body: JSON.stringify({
    requestId: order.id, flowType: 'checkout',
    email: order.email, ip: clientIp, sessionId: order.riskcogsSessionId,
    money: { amount: order.total, currency: order.currency }, // decimal string, major units
  }),
});
const { riskId, risk_score, level, recommendation, shadowMode } = await res.json();
// Keep riskId: send it with the outcome to POST /v1/risk-feedback later.

3. Ou teste com curl

curl -X POST https://YOUR_RISKCOGS_API_HOST/v1/risk-score \
  -H "X-API-Key: $RISKCOGS_SECRET_KEY" \
  -H "Content-Type: application/json" \
  -d '{"requestId":"quickstart-test-1","flowType":"checkout","email":"[email protected]","ip":"203.0.113.45","money":{"amount":"49.00","currency":"EUR"}}'

4. Leia a resposta e aja

Use recommendation para direcionar o pagamento: aprovar, revisar ou recusar. No modo shadow, registre a recomendação sem mudar o fluxo.

{
  "riskId": "0190f3c2-…",
  "risk_score": 18,
  "level": "low",
  "recommendation": "allow",
  "shadowMode": true,
  "flags": [],
  "signals": { "email": { … }, "ip": { … } }
}

Chaves, valores e retorno

Duas chaves: pub_ para o SDK, pr_ para o servidor. A chave secreta nunca chega ao navegador.
Valores como string decimal com moeda, por exemplo "49.00" EUR.
A resposta traz riskId, risk_score, level, recommendation, shadowMode, flags e signals.
Guarde o riskId e envie o resultado para POST /v1/risk-feedback.
Faixas padrão: abaixo de 40 aprovar, 40 a 69 revisar, 70 ou mais recusar.

Diagrama de sequência: SDK no checkout, chamada do servidor a POST /v1/risk-score, score e motivos, depois retorno a POST /v1/risk-feedback

Perguntas frequentes

O que é uma API antifraude?

Um serviço web que recebe dados de pagamento, conta ou login e devolve um score com a ação recomendada.

Onde chamar no checkout?

No servidor, depois do envio do pedido e antes do intermediador, passando o ID de sessão do SDK.

Por que enviar resultados?

Para o score aprender quais pagamentos foram bons, estornados ou contestados.

Funciona com vários intermediadores?

Sim, o score é calculado antes de qualquer um deles.

Meça primeiro. Bloqueie depois.

Rode o RiskCogs em modo shadow ao lado do seu provedor de pagamentos atual e revise as decisões antes que afetem um único cliente.