Fraud Detection

SDK methods for the Fraud Detection Engine — decide, screen, rules, lists, devices, cases, terms.

The client.fraud namespace covers the full Phase 6 Detection Engine surface — decisions, rules, screening, devices, cases, and T&Cs. Available in TypeScript, Python, and Go SDKs.

SDK	Install	Namespace
TypeScript	npm install @caldera/platformxe-sdk	client.fraud
Python	pip install platformxe	client.fraud
Go	go get github.com/calderax/platformxe-go	client.Fraud

Decisions

Render production verdicts (allow / review / step_up / block), shadow-evaluate rules without enforcement, and audit historical decisions.

const verdict = await client.fraud.decisions.decide({
  subject: { id: 'user_123', kind: 'user' },
  action: 'withdraw',
  resource: { kind: 'transaction' },
  context: { amount: { value: 75000, currency: 'NGN' }, ip: '102.89.10.1' },
});
console.log(verdict.verdict, verdict.score, verdict.reasons);

// Shadow-evaluate (does NOT enforce; useful for testing rules pre-publish)
await client.fraud.decisions.shadowDecide({ /* same shape */ });

// Audit
const decisions = await client.fraud.decisions.list({ verdict: 'block', limit: 50 });
const one = await client.fraud.decisions.get('dec_abc');

verdict = client.fraud.decisions.decide(
    subject={"id": "user_123", "kind": "user"},
    action="withdraw",
    resource={"kind": "transaction"},
    context={"amount": {"value": 75000, "currency": "NGN"}},
)

verdict, err := client.Fraud.Decisions.Decide(px.FraudDecideRequest{
    Subject: px.FraudDecideSubject{ID: "user_123", Kind: "user"},
    Action: "withdraw",
    Resource: px.FraudDecideResource{Kind: "transaction"},
})

Rules

CRUD + lifecycle transitions for tenant-authored rules. Rules move through draft → shadow → published → archived. Use shadowReport to see how a candidate rule WOULD have performed before promoting it.

const rule = await client.fraud.rules.create({
  name: 'High-value withdrawal in NG',
  weight: 25,
  appliesTo: { actions: ['withdraw'], resourceKinds: ['transaction'] },
  condition: {
    all: [
      { 'amount.value': { gte: 50000 } },
      { 'context.geoHint': { equals: 'NG' } },
    ],
  },
});

// Promote draft → shadow to ride along on production calls
await client.fraud.rules.transition(rule.id, { target: 'shadow' });

// Inspect 7d shadow performance
const report = await client.fraud.rules.shadowReport(rule.id);

// Then publish
await client.fraud.rules.transition(rule.id, { target: 'published' });

Screening

One-shot sanctions / PEP / blocklist screening. Tenants can also manage their own blocklists / allowlists.

// Screen a name (single call)
const hits = await client.fraud.screening.screen({
  name: 'John Doe',
  kinds: ['sanctions', 'pep', 'tenant_blocklist'],
  threshold: 0.65,
});

// Tenant blocklist
const list = await client.fraud.screening.createTenantList({
  source: 'internal-2026', name: 'Internal blocklist 2026', kind: 'tenant_blocklist',
});

await client.fraud.screening.appendEntries(list.id, {
  entries: [
    { name: 'John Doe', dob: '1980-01-15', country: 'NG' },
    { name: 'Jane Roe', identifiers: { bvn: '12345678901' } },
  ],
});

Devices

Submit a tenant-computed fingerprint hash and receive structured device signals (new device, shared across subjects, impossible travel, etc).

const observation = await client.fraud.devices.seen({
  fingerprint: 'sha256:abcd...',
  subjectId: 'user_123',
  ip: '102.89.10.1',
  geo: 'NG',
});
console.log(observation.signals.impossibleTravel);
console.log(observation.ipIntel);

Cases

Manual reviewer workflow over flagged decisions. block verdicts auto-open a case with a 24h SLA — your reviewers transition through triaging → escalated → resolved.

// List overdue cases (SLA breach window passed)
const overdue = await client.fraud.cases.list({ status: 'escalated', overdueOnly: true });

// Open a case manually
const c = await client.fraud.cases.open({
  decisionId: 'dec_abc',
  severity: 75,
  assignedTo: 'reviewer@example.com',
});

// Move through lifecycle
await client.fraud.cases.transition(c.id, { target: 'triaging' });
await client.fraud.cases.transition(c.id, {
  target: 'resolved',
  resolution: 'confirmed_fraud',
  note: { by: 'reviewer@example.com', text: 'BVN matched 3 prior block verdicts.' },
});

Terms & Conditions

The Detection Engine is gated behind a click-through T&Cs acceptance. Until accepted at the current version, the cases UI + identity verification endpoints return 403.

const status = await client.fraud.terms.status();
if (!status.accepted || status.staleAcceptance) {
  await client.fraud.terms.accept({
    acceptedBy: 'admin@org.example',
    version: status.currentVersion,
  });
}

Scopes required

Method group	Scope
fraud.decisions.*	fraud:decide (decide / shadowDecide), fraud:audit (list / get)
fraud.rules.*	fraud:manage
fraud.screening.*	fraud:screen (screen), fraud:manage (lists / entries)
fraud.devices.*	fraud:devices
fraud.cases.*	fraud:cases
fraud.terms.*	fraud:audit (status), fraud:manage (accept)