API-документація

Антифрод API: оцінюйте кожен платіж до платіжного провайдера

Антифрод API приймає дані про платіж, клієнта й пристрій і в реальному часі повертає ризик-скор і рекомендацію. У RiskCogs ви підключаєте браузерний SDK у чекауті, надсилаєте сесію та замовлення із сервера в POST /v1/risk-score, дієте за рекомендацією й повідомляєте підсумок.

Почати безкоштовно в shadow-режимі

1. Підключіть браузерний SDK у чекауті

SDK за згодою користувача збирає контекст пристрою та сесії й повертає ID сесії для сервера. Endpoint і ключ — у консолі 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. Оцініть платіж на сервері

Викликайте API до надсилання платежу платіжному провайдеру. Для Node 18 і новіших бібліотеки не потрібні.

// 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. Або перевірте через 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. Прочитайте відповідь і ухваліть рішення

Поле recommendation визначає маршрут: пропустити, перевірити чи відхилити. У тіньовому режимі записуйте рекомендацію, не змінюючи потік.

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

Ключі, суми та зворотний зв’язок

Два ключі: pub_ для браузерного SDK, pr_ для сервера. Секретний ключ ніколи не потрапляє в браузер.
Суми — десятковим рядком із валютою, наприклад "49.00" EUR.
Відповідь містить riskId, risk_score, level, recommendation, shadowMode, flags і signals.
Збережіть riskId і надішліть підсумок у POST /v1/risk-feedback.
Пороги за замовчуванням: менше 40 — пропустити, 40–69 — перевірити, від 70 — відхилити.

Діаграма послідовності: SDK у чекауті, виклик сервера POST /v1/risk-score, скор і причини, потім зворотний зв’язок у POST /v1/risk-feedback

Часті запитання

Що таке антифрод API?

Вебсервіс, який приймає дані платежу, акаунту чи входу й повертає скор із рекомендованою дією.

Де викликати API в чекауті?

На сервері після надсилання замовлення й до передачі платіжному провайдеру, разом з ID сесії з SDK.

Навіщо повідомляти результати?

Щоб скор навчався, які платежі були добрими, поверненими чи пішли в чарджбек.

Чи працює з кількома провайдерами?

Так, скор рахується до будь-якого провайдера.

Читайте також

Спершу виміряйте. Потім блокуйте.

Запустіть RiskCogs у shadow-режимі поруч із вашим поточним платіжним провайдером і перевірте рішення до того, як вони торкнуться бодай одного клієнта.

Почати безкоштовно в shadow-режимі