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-режиме рядом с вашим текущим платёжным провайдером и проверьте решения до того, как они затронут хоть одного клиента.