Fraud detection API: score every payment before you send it to your provider

A fraud detection API takes details about a payment, customer and device and returns a risk score and a recommendation in real time. With RiskCogs you load the browser SDK at checkout, send the session and order to POST /v1/risk-score from your server, act on the recommendation, and report the final outcome back.

Updated 1 November 2026 · RiskCogs team

Key facts

Two keys: a publishable key (pub_) for the browser SDK and a secret key (pr_) for server calls. The secret key never reaches a browser.
Money is sent as a decimal string in major units with a currency code, for example "49.00" EUR.
The response includes riskId, risk_score, level, recommendation, shadowMode, flags and the signals behind the score.
Keep riskId and send the final outcome to POST /v1/risk-feedback so future scores learn from it.

Sequence diagram: the browser SDK runs at checkout, your server calls POST /v1/risk-score, RiskCogs returns risk_score and reason codes, your server applies the decision, and later reports the outcome to POST /v1/risk-feedback with the riskId. — The integration sequence covered in the steps below.

1. Load the browser SDK at checkout

The SDK collects device and session context with user consent and returns a session ID to pass to your server. Replace the endpoint and key with the values from your RiskCogs console.

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. Score the payment from your server

Call the API before you send the payment to your payment provider. Node 18 or later needs no extra client library.

// 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. Or test with 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. Read the response and act on it

Use recommendation to route the payment: allow it, send it to review, or block it. In shadow mode, log the recommendation and keep your current flow unchanged.

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

Fraud detection API integration options

Approach	What you get	Trade-off
Built-in tool of one payment provider	No extra integration for that provider	Sees only that provider’s traffic
Device-intelligence API	Device ID and browser signals	You still build scoring and rules
Risk scoring API (RiskCogs)	Score, recommendation, signals and rules	One server call per payment
In-house rules	Full control	Ongoing engineering and data work

Start in shadow mode

New projects can run in shadow mode: every payment is scored and logged, but your current flow decides. When you are happy with what RiskCogs would have blocked, switch the recommendation into your payment flow.

Endpoints and field names on this page come from the RiskCogs quickstart. Confirm the hosts and keys in your console before going live.

See what you would have blocked — free shadow mode

Frequently asked questions

What is a fraud detection API?

A fraud detection API is a web service that receives details about a payment, account or login and returns a risk assessment, usually a score and a suggested action. Merchants call it from their server during checkout or signup, then allow, review or block the event based on the answer and their own rules.

Where should I call the fraud detection API in my checkout?

Call it from your server after the customer submits the order and before you send the payment to your payment provider. That way you can stop or challenge risky payments before authorization. Pass the browser session ID from the SDK so device signals are part of the score.

Why send outcomes back to the API?

Outcome feedback tells the system which scored payments turned out to be good, refunded or charged back. Without it, the score cannot learn from your traffic. Store the riskId returned by the score call and post the final outcome to the feedback endpoint once you know it.

Can I use the API with more than one payment provider?

Yes. RiskCogs scores the payment before it reaches any provider, so the same risk logic and history apply whether the payment then goes to one acquirer or several. This is useful for merchants and platforms that route payments across multiple providers.

Sources and related reading

Measure first. Enforce when ready.

Run RiskCogs in shadow mode next to your existing payment setup and review the decisions before they affect a single customer.

Start free in shadow mode See pricing