Dokumentacja API

API antyfraudowe: oceń każdą płatność przed operatorem płatności

API antyfraudowe przyjmuje dane o płatności, kliencie i urządzeniu i w czasie rzeczywistym zwraca ocenę ryzyka z rekomendacją. W RiskCogs ładujesz SDK przeglądarki w checkoucie, wysyłasz sesję i zamówienie z serwera do POST /v1/risk-score, działasz zgodnie z rekomendacją i zgłaszasz wynik.

Zacznij za darmo w trybie shadow

1. Załaduj SDK przeglądarki w checkoucie

SDK zbiera za zgodą użytkownika kontekst urządzenia i sesji i zwraca ID sesji dla serwera. Endpoint i klucz znajdziesz w konsoli 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. Oceń płatność po stronie serwera

Wywołaj API, zanim wyślesz płatność do operatora. Node 18 lub nowszy nie wymaga bibliotek.

// 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. Albo przetestuj przez 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. Odczytaj odpowiedź i działaj

Pole recommendation kieruje płatność: akceptuj, sprawdź lub odrzuć. W trybie shadow zapisuj rekomendację bez zmiany przepływu.

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

Klucze, kwoty i informacja zwrotna

Dwa klucze: pub_ dla SDK przeglądarki, pr_ dla serwera. Klucz tajny nigdy nie trafia do przeglądarki.
Kwoty jako ciąg dziesiętny z walutą, np. "49.00" EUR.
Odpowiedź zawiera riskId, risk_score, level, recommendation, shadowMode, flags i signals.
Zachowaj riskId i wyślij wynik do POST /v1/risk-feedback.
Domyślne progi: poniżej 40 akceptuj, 40–69 sprawdź, od 70 odrzuć.

Diagram sekwencji: SDK w checkoucie, wywołanie serwera do POST /v1/risk-score, wynik i powody, potem informacja zwrotna do POST /v1/risk-feedback

Najczęstsze pytania

Czym jest API antyfraudowe?

Usługą sieciową, która przyjmuje dane płatności, konta lub logowania i zwraca ocenę z zalecaną akcją.

Gdzie wywołać API?

Na serwerze po złożeniu zamówienia, a przed wysłaniem do operatora płatności, z ID sesji z SDK.

Po co zgłaszać wyniki?

Żeby ocena uczyła się, które płatności były dobre, zwrócone lub zakwestionowane.

Czy działa z kilkoma operatorami?

Tak, ocena powstaje przed jakimkolwiek operatorem.

Czytaj także

Najpierw zmierz. Potem blokuj.

Uruchom RiskCogs w trybie shadow obok obecnego dostawcy płatności i sprawdź decyzje, zanim dotkną choćby jednego klienta.

Zacznij za darmo w trybie shadow