Risk Intelligence API: Operational Overview

This document provides technical and operational clarity for the PayFlux Risk Intelligence layer.

Authentication & Quotas

Use the x-payflux-key header to authenticate and access higher-tier rate limits.

| Tier | Header | Rate Limit | Capacity | |------|--------|------------|----------| | ANONYMOUS | (None) | 1 req / min | 3 | | FREE | x-payflux-key: pf_test_... | 5 req / min | 10 | | PRO | x-payflux-key: pf_live_... | 60 req / min | 100 |

Core Endpoints

1. Risk Scan (POST /api/v1/risk)

Perform a real-time risk assessment of a merchant URL.

• Request: {"url": "...", "industry": "...", "processor": "..."}
• Headers: x-payflux-key (optional), x-trace-id (returned)
• Response: ResponseSchema (Standard risk snapshot)

2. Audit History (GET /api/v1/risk/history?url=...)

Returns the full timeline of scans performed for a given host.

• Payload: Includes raw snapshots of every previous scan.

3. Intelligence Trend (GET /api/v1/risk/trend?url=...)

Returns deterministic behavioral signals for a merchant.

• Trend Logic:
  • DEGRADING: Risk tier increased in the latest scan (risk drift).
  • IMPROVING: Risk tier decreased in the latest scan.
  • STABLE: No change in risk tier.
• Policy Surface: Current counts of Present/Weak/Missing compliance policies.

4. System Health (GET /api/v1/risk/health)

Returns real-time in-memory counters for SSRF blocks, rate limit denials, and scan success rates.

Caching & Performance

• Fresh Scans: 24 hours (CACHE_TTL.URL_CRAWL)
• Negative Caching: 1 hour (for scan failures)
• DNS/SSRF Safety: 5 seconds
• Deduplication: In-flight concurrent requests for the same URL are deduped (leader/follower pattern).

Observability

Check x-trace-id in every response header. This ID maps to a structured JSON log entry in our internal telemetry with the event type:

• risk_request_start / risk_request_complete
• risk_ssrf_block
• risk_rate_limit_deny
• risk_cache_hit / risk_cache_miss
• risk_history_read / risk_trend_read