Fraud Detection API

Synchronous fraud decision engine — rules, block/allow lists, and review queue

The Fraud Detection Service is the platform's synchronous risk evaluation layer. It is called by the payments-service at authorization time and is also exposed publicly via the api.* aggregator at /v1/fraud/. The rules engine is implemented in Go; ML scoring via a Python sidecar is wired in Phase 2+.

Base URLs

Environment	Hostname
Sandbox	`https://sandbox.505pay.link`
Production (505pay.link)	`https://api.505pay.link`
Production (straventa.com)	`https://api.straventa.com`

Authentication

All fraud API endpoints require a Bearer JWT issued by the auth-service. The tenant_id claim is extracted server-side — callers do not include it in the request body.

Decision verdicts

Verdict	Meaning
`allow`	Passes all checks; proceed normally.
`review`	Suspicious; flag for manual review, do not block.
`decline`	High-confidence fraud; block the action.
`unavailable`	Service temporarily unable to evaluate; apply your own fallback policy.

Flag-only launch (P0)

At launch the service never hard-declines. Every decision is flagged for human review; the decline verdict is reserved for Phase 2+ when the ML sidecar is wired in and confidence calibration is complete.

Idempotency

Pass an Idempotency-Key header (UUID or opaque string, up to 64 characters) on POST /v1/fraud/decisions. Duplicate submissions within the replay window return the original decision with HTTP 200.

Reason codes

Code	Meaning
`velocity_ip_exceeded`	Payer IP exceeded per-(IP, merchant) attempt threshold within window
`velocity_card_exceeded`	Payment card fingerprint seen across too many distinct merchants in 24h
`velocity_fingerprint_exceeded`	Device fingerprint seen across too many distinct merchants in 24h
`high_risk_score`	Computed risk score exceeds review threshold (no single rule tripped)
`list_block_ip`	Payer IP appears on a block list
`list_block_card`	Card fingerprint appears on a block list
`list_block_fingerprint`	Device fingerprint appears on a block list
`ml_high_score`	ML sidecar score above decline threshold (Phase 2+; not emitted in P0)

P0 scope

Only event_type=payment is implemented in P0. Other event_type values return 400 event_type_unsupported.

Endpoint reference

Fraud decisions

Synchronous fraud evaluation — submit a platform event and receive a verdict, risk score, and reason codes. Called by the payments-service at authorization time and available directly via the api.* aggregator.

GET/v1/fraud/decisions

List fraud decisions (decisions log)

GET/v1/fraud/decisions/{id}

Get a fraud decision

GET/v1/fraud/decisions/{id}/dispositions

List a decision's disposition trail

GET/v1/fraud/decisions/queue

Review queue (decisions needing review)

POST/v1/fraud/decisions

Create a fraud decision

POST/v1/fraud/decisions/{id}/disposition

Record a review disposition

Configurable rules

Manage per-tenant fraud rules expressed as condition/action definitions. Each PATCH that supplies a definition appends an immutable version snapshot.

GET/v1/fraud/rules

List configurable fraud rules

GET/v1/fraud/rules/{id}

Get a fraud rule

GET/v1/fraud/rules/{id}/versions

List a rule's version history

POST/v1/fraud/rules

Create a configurable fraud rule

PATCH/v1/fraud/rules/{id}

Update a fraud rule

DELETE/v1/fraud/rules/{id}

Delete a fraud rule

Block / allow lists

Manage per-tenant block and allow lists keyed by IP, device fingerprint, card fingerprint, email, or customer ID. Allow overrides block when both match.

GET/v1/fraud/lists

List block/allow lists

GET/v1/fraud/lists/{id}

Get a block/allow list

GET/v1/fraud/lists/{id}/entries

List entries in a list

POST/v1/fraud/lists

Create a block/allow list

POST/v1/fraud/lists/{id}/entries

Add an entry to a list

DELETE/v1/fraud/lists/{id}

Delete a block/allow list