API reference — Fraud Command Center Docs

Base URL

https://api.fraudcommandcenter.com

Authentication

Every request is authenticated with an API key plus an HMAC signature over the request body. API keys and HMAC secrets are issued per store in the dashboard.

Required headers on signed endpoints:

Authorization: Bearer <api_key>
X-Fraudshield-Key: <api_key>
X-Fraudshield-Timestamp: <unix_seconds>
X-Fraudshield-Nonce: <uuid_v4>
X-Fraudshield-Signature: <hex_hmac_sha256>

Computing the signature

canonical = f"{timestamp}.{nonce}.{body}"
signature = hmac_sha256(hmac_secret, canonical).hexdigest()

Timestamp skew: requests older than 300 seconds are rejected.
Nonces: Redis-backed atomic replay protection. Reusing a nonce within the skew window returns 401.

POST /v1/analyze

Score a single order. This is the core endpoint.

Request body

{
  "order_id": "shopify-12345",
  "customer": {
    "email": "[email protected]",
    "phone": "+14155551234",
    "first_name": "Jane",
    "last_name": "Doe"
  },
  "amount": 248.50,
  "currency": "USD",
  "billing_address": { "country": "US", "city": "Austin", "postal_code": "78701" },
  "shipping_address": { "country": "US", "city": "Austin", "postal_code": "78701" },
  "payment": {
    "avs_result": "Y",
    "cvv_result": "M",
    "card_bin": "411111"
  },
  "line_items": [
    { "sku": "SHIRT-XL", "quantity": 1, "price": 248.50 }
  ],
  "ip_address": "203.0.113.42",
  "user_agent": "Mozilla/5.0 ..."
}

Response

{
  "transaction_id": "01HZX0...",
  "risk_score": 82,
  "risk_level": "critical",
  "recommended_action": "hold",
  "confidence": 0.91,
  "reason_codes": [
    "avs_mismatch",
    "ship_bill_country_mismatch",
    "high_amount"
  ],
  "explanation": "Order amount is in the top decile for this store and...",
  "scored_at": "2026-05-12T15:23:18Z",
  "duration_ms": 247
}

Status codes

Code	Meaning
200	Scored. See body.
401	Bad signature, expired timestamp, or replayed nonce.
402	Free plan reached the view-only limit. Upgrade to score.
409	Order already scored (idempotent — original score returned).
429	Per-store rate limit (default 100/min) exceeded.
5xx	Server error. Retries with the same nonce/body are safe.

GET /v1/transactions

List transactions for the authenticated store. Cookie-based JWT auth (dashboard).

Query parameters:

limit — default 50, max 200
cursor — opaque pagination cursor
risk_level — filter (low, medium, high, critical)
from, to — ISO8601 timestamps

GET /v1/transactions/{id}

Return a full transaction with all assessment versions, score breakdown, and audit trail.

POST /v1/transactions/{id}/reanalyze

Re-score an existing transaction (e.g., after a rule change). Creates a new assessment version.

POST /v1/transactions/{id}/review

Record a merchant review decision (approve, reject, hold). Decisions feed back into the history analyzer and (on Growth and above) auto-rule recalibration.

Errors

All errors return a JSON envelope:

{ "detail": "Invalid signature" }

Never log raw bodies on signed routes — the API redacts them internally and you should too.