APIドキュメント

不正検知 API：決済代行会社に送る前にすべての決済をスコアリング

不正検知APIは、決済・顧客・端末の情報を受け取り、リスクスコアと推奨アクションをリアルタイムで返します。RiskCogsでは、決済画面でブラウザSDKを読み込み、サーバーからセッションと注文をPOST /v1/risk-scoreに送り、推奨に従って処理し、最終結果を返します。

シャドーモードで無料で始める

1. 決済画面でブラウザSDKを読み込む

SDKはユーザーの同意のもとで端末とセッションの情報を集め、サーバーに渡すセッションIDを返します。エンドポイントとキーは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": { … } }
}

キー、金額、フィードバック

キーは2種類：ブラウザSDK用のpub_とサーバー用のpr_。秘密鍵がブラウザに渡ることはありません。
金額は通貨コード付きの10進文字列で送ります（例："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とは？

決済、アカウント、ログインの情報を受け取り、スコアと推奨アクションを返すWebサービスです。

決済フローのどこで呼ぶ？

注文確定後、決済代行会社に送る前にサーバーから呼びます。SDKのセッションIDも渡します。

なぜ結果を返す？

どの決済が正常、返金、チャージバックだったかをスコアが学べるようにするためです。

複数の決済代行会社でも使える？

はい。どの会社に送る前でもスコアを計算できます。

まず測定し、それから止める。

既存の決済代行会社の横でRiskCogsをシャドーモードで動かし、顧客に影響が出る前に判定結果を確認できます。