Integrate Radar

Before you begin

• A sign-in or sign-up flow already running through Paycux. Radar scores attempts it can see, so it sits behind AuthKit or the User Management API rather than beside them.
• A view of your current abuse pattern. Blocking is cheap; blocking the wrong people is expensive, so start from what you actually see in your logs.
• A step-up factor to challenge with. MFA or an email verification loop both work.
• If you run behind a proxy or CDN, correct client IP forwarding. A blocked signal is worthless if every request arrives from your own load balancer.

Install

Every example on this page uses the Node.js client. The same calls exist in the Python, Go, Ruby, PHP and Java SDKs, following the naming conventions of each language.

1npm i @paycux/node

Configure

Radar needs no keys of its own. It reads from the same environment as the rest of your integration; the only new value is the webhook secret used to verify risk events if you subscribe to them.

1PAYCUX_API_KEY=sk_example_7f4c1b9ad2e84c6f
2PAYCUX_CLIENT_ID=client_01HQZX8N4T
3PAYCUX_WEBHOOK_SECRET=whsec_example_2b6d9f31

Then, in the dashboard:

1. 1Open Radar and switch it into observe mode. Nothing is blocked; every attempt is scored so you can see what a rule would have done.
2. 2Turn on the detections that match your problem: credential stuffing, brute force, disposable email domains, impossible travel, or repeat trial sign-ups.
3. 3Set the action per detection. Challenge is the right default for anything that can produce a false positive; block belongs to signals you are certain about.
4. 4Add your own team's addresses and office ranges to the allow list so an internal test never trips a rule.
5. 5After a few days of observing, switch the rules you trust into enforce mode one at a time.

Implement

In enforce mode Radar acts before your callback runs, so a blocked attempt simply never reaches you. The code below covers the two cases where you want the decision yourself: scoring an action of your own, and reacting to a risk event after the fact.

1import { Paycux } from "@paycux/node";
2 
3const paycux = new Paycux(process.env.PAYCUX_API_KEY);
4 
5export async function POST(request: Request) {
6  const { userId, amount } = await request.json();
7 
8  const assessment = await paycux.radar.evaluate({
9    action: "checkout",
10    userId,
11    ipAddress: request.headers.get("x-forwarded-for")?.split(",")[0],
12    userAgent: request.headers.get("user-agent"),
13    context: { amount },
14  });
15 
16  if (assessment.verdict === "block") {
17    return Response.json({ error: "blocked", reason: assessment.reasons }, { status: 403 });
18  }
19 
20  if (assessment.verdict === "challenge") {
21    return Response.json({ challenge: "mfa", assessmentId: assessment.id }, { status: 202 });
22  }
23 
24  return Response.json({ ok: true });
25}

1import { Paycux } from "@paycux/node";
2 
3const paycux = new Paycux(process.env.PAYCUX_API_KEY);
4 
5export async function POST(request: Request) {
6  const { assessmentId, factorId, code } = await request.json();
7 
8  const challenge = await paycux.mfa.verifyFactor({ factorId, code });
9 
10  await paycux.radar.resolve({
11    assessmentId,
12    outcome: challenge.valid ? "passed" : "failed",
13  });
14 
15  return Response.json({ ok: challenge.valid });
16}

1import { Paycux } from "@paycux/node";
2 
3const paycux = new Paycux(process.env.PAYCUX_API_KEY);
4 
5export async function POST(request: Request) {
6  const payload = await request.text();
7  const signature = request.headers.get("paycux-signature");
8 
9  const event = paycux.webhooks.verify({
10    payload,
11    signature,
12    secret: process.env.PAYCUX_WEBHOOK_SECRET,
13  });
14 
15  if (await alreadyProcessed(event.id)) {
16    return new Response("ok", { status: 200 });
17  }
18 
19  if (event.event === "radar.attempt_blocked") {
20    await flagAccount(event.data.userId, event.data.reasons);
21  }
22 
23  await markProcessed(event.id);
24  return new Response("ok", { status: 200 });
25}

Verify

Radar is one of the few features where the interesting test is the negative one. Confirm that a legitimate person still gets through before you confirm that an abusive one does not.

1. 1With observe mode on, sign in normally several times and check that every attempt is scored as allowed.
2. 2Sign up with an address on a disposable domain and confirm the attempt is flagged, not silently accepted.
3. 3Fail a password ten times in a row from the same address and confirm the brute-force rule fires at the threshold you set.
4. 4Turn one rule into enforce mode and repeat the abusive case. The response should be a clean rejection, not a stack trace.
5. 5Open Radar in the dashboard and read the attempt timeline: each entry names the rule, the signals and the action taken.

Reference

Request and response shapes for each of these live in the API reference. Paths are relative to https://api.paycux.com.

Next steps