Skip to content

Fraud report callback contract

What the client backend must expose so Fraud can deliver investigator reports.

Endpoint you expose

Item Contract
Method / path POST {backend_api}/transaction/create-report (path used by Fraud checks today)
Auth header Authorization: ApiKey <jwt> signed by AI (iss=ai-service, aud=software-service, ~5 min exp)
Tenant x-tenant-id — must match the scoring tenant
Body JSON matching Fraud output contract / FraudDashboardReport

Authentication verification (your side)

  1. Reject missing header or non-ApiKey scheme (401).
  2. Verify RS256 with the environment’s AI public key.
  3. Enforce iss / aud / exp.
  4. Authorise that x-tenant-id is allowed for your deployment.

See Auth tutorial.

Request schema (summary)

Required conceptual fields: aiSummary, fraudScore, riskCategory, decision, escalations, reasonCodes, indicatorRecords, aiChecks, provenance, plus dashboard-compatible views (fraudIndicators, aiRecommendation).

decision is provisional under fraud-decision-v1 until compliance GA.

Idempotency expectation

Expectation Guidance
At-least-once delivery Your endpoint may receive the same logical report more than once
Dedupe key Prefer provenance.predictionHash + transaction identity your platform stores + tenant
Safe handler Upsert by business key; do not create duplicate investigator work items blindly

Exact transaction id field placement on the wire may include envelope fields from your backend DTO — confirm against the payload you receive in staging.

Response semantics

Your response Fraud platform expectation
2xx Treat delivery as success
4xx (auth) Fix keys; platform should not spin forever on bad auth
5xx / timeout Eligible for retry / redelivery per environment configuration

Return a small JSON ack if your API requires a body; do not require Fraud to store your internal case id unless you have a separate agreed contract.

Retry behaviour

  • Platform may retry failed deliveries when messaging/HTTP retry is configured for the environment (confirm with MasteryHive for your deploy — behaviour is environment-specific).
  • Your handler must be idempotent.
  • Do not treat a missing report as low risk if scoring succeeded — TM lifecycle.