API Integration Guide

Audience: IT, Integration Engineers Last updated: March 2026 API Version: v3

FraudShield AI Engine exposes a REST API for real-time transaction scoring, alert webhook delivery, and case feedback submission. Integrate the Scoring API inline within your payment authorization flow so every transaction is evaluated before it's approved or posted.

API version This guide covers API v3, released in February 2026. API v2 remains supported until December 2026. Migrate to v3 before that date. The primary change in v3 is the expanded score_contributors array and the new step_up response object.

Base URL and versioning

# Production
https://fraudshield.yourbank.internal/api/v3/

# Staging / UAT
https://fraudshield-uat.yourbank.internal/api/v3/
  

The API is only accessible from within your institution's internal network or via the approved API gateway. It's not exposed directly to the internet.

Authentication

All API requests must include a bearer token in the Authorization header. Tokens are issued per integration client (one token per calling system) and carry the permissions and tenant context for that client.

Header	Value	Required
`Authorization`	`Bearer {api_token}`	Required
`Content-Type`	`application/json`	Required
`X-Correlation-ID`	Client-generated UUID for request tracing	Recommended
`X-Tenant-ID`	Tenant identifier (required for multi-tenant deployments)	Conditional

Protect API tokens Store tokens in a secrets manager — never in code, configuration files, or version control. Rotate tokens every 90 days. If a token is compromised, revoke it immediately in the FraudShield Administration console and issue a new one.

API endpoints

POST /api/v3/score Real-time transaction scoring

Submit a transaction for real-time risk scoring. Call this endpoint synchronously before authorizing or posting any payment. The response contains the risk score, decision, and score contributors.

Request — POST /api/v3/score

POST /api/v3/score
Authorization: Bearer {api_token}
Content-Type: application/json
X-Correlation-ID: a3f2c1d9-8e4b-4f71-b0c3-7e91d2a5f6b8

{
  "transaction_id":    "TXN-20260301-004821",
  "transaction_type":  "WIRE",
  "channel":           "WEB",
  "amount":            24500.00,
  "currency":          "USD",
  "timestamp":         "2026-03-01T14:33:07Z",
  "memo":              "Invoice #4821 payment",
  "originator": {
    "account_id":       "ACC-0012938847",
    "customer_id":      "CIF-00984321",
    "account_open_date":"2019-06-15"
  },
  "beneficiary": {
    "account_number":   "7841029384",
    "routing_number":   "021000021",
    "name":             "Acme Corp LLC",
    "country":          "US"
  },
  "behavioral": {
    "session_id":           "sess-d82f1c9a",
    "session_duration_s":   342,
    "copy_paste_detected":  false
  }
}
  

Response — 200 OK (APPROVE)

{
  "transaction_id":    "TXN-20260301-004821",
  "correlation_id":    "a3f2c1d9-8e4b-4f71-b0c3-7e91d2a5f6b8",
  "risk_score":        214,
  "risk_level":        "LOW",
  "decision":          "APPROVE",
  "alert_generated":   false,
  "bta_id":            "WEB_WIRE_TRANSFER",
  "model_id":          "MDL_WIRE_ATO",
  "model_version":     "4.2.1",
  "score_contributors": [
    { "ri_id": "RI_NEW_PAYEE_FIRST_TXN",     "sub_score": 55, "display": "First transaction to this payee" },
    { "ri_id": "RI_VELOCITY_TRANSFER_1H",     "sub_score": 0,  "display": "Normal velocity (1 transfer in last hour)" },
    { "ri_id": "RI_DEVICE_FINGERPRINT_CHANGE", "sub_score": 0,  "display": "Known device" }
  ],
  "processing_time_ms": 87,
  "scored_at":         "2026-03-01T14:33:07.312Z"
}
  

Response — 200 OK (STEP-UP / HIGH)

{
  "transaction_id":    "TXN-20260301-005193",
  "risk_score":        621,
  "risk_level":        "HIGH",
  "decision":          "STEP-UP",
  "alert_generated":   true,
  "alert_id":          "ALT-20260301-009977",
  "step_up": {
    "required":         true,
    "methods":          ["SMS_OTP", "PUSH_NOTIFICATION"],
    "challenge_token":  "chk-f9a2b3d1-7c44-4e98-ab21",
    "token_expires":    "2026-03-01T14:43:07Z"
  },
  "score_contributors": [
    { "ri_id": "RI_VELOCITY_TRANSFER_1H",  "sub_score": 80, "display": "12 transfers in last hour (elevated)" },
    { "ri_id": "RI_NEW_PAYEE_FIRST_TXN",    "sub_score": 90, "display": "First transaction to this payee" },
    { "ri_id": "RI_AMOUNT_SPIKE_3SD",       "sub_score": 75, "display": "Amount 3.4 std deviations above 30D mean" }
  ],
  "processing_time_ms": 102
}
  

POST /api/v3/score/step-up-result Submit step-up challenge result

After presenting the step-up challenge to the customer, submit the challenge outcome. FraudShield re-evaluates the decision based on the result.

Request body — step-up result

{
  "transaction_id":  "TXN-20260301-005193",
  "challenge_token": "chk-f9a2b3d1-7c44-4e98-ab21",
  "challenge_result":"PASSED",   // PASSED | FAILED | TIMED_OUT
  "method_used":     "SMS_OTP"
}
  

POST /api/v3/feedback Submit case disposition feedback

Submit analyst dispositions programmatically from an external case management system. Dispositions feed into the model feedback loop.

Request body — feedback

{
  "alert_id":       "ALT-20260301-009977",
  "transaction_id": "TXN-20260301-005193",
  "disposition":    "FALSE_POSITIVE",  // CONFIRMED_FRAUD | SUSPICIOUS | FALSE_POSITIVE | DUPLICATE
  "analyst_id":     "analyst-jsmith",
  "notes":          "Customer called in — confirmed this was their own transfer. Regular payee."
}
  

GET /api/v3/health Engine health check

Returns the current health status of all engine components. Use for integration monitoring and alerting.

Error codes

HTTP status	Error code	Description	Action
400	`INVALID_REQUEST`	Request body is missing required fields or contains invalid values.	Fix the request payload. Check required fields in Model Input Features.
401	`AUTH_INVALID_TOKEN`	API token is missing, expired, or revoked.	Reissue the token from the Administration console.
409	`DUPLICATE_TRANSACTION`	A request with this `transaction_id` was already processed. Idempotency protection triggered.	Don't re-submit the same transaction ID. The original response is returned.
429	`RATE_LIMIT_EXCEEDED`	The calling client has exceeded the rate limit.	Back off and retry after the duration specified in the `Retry-After` header.
503	`ENRICHMENT_UNAVAILABLE`	One or more enrichment providers are unavailable. Scoring continues without that enrichment (fail-open behavior).	No action required if fail-open is acceptable. Monitor enrichment provider uptime.
504	`SCORING_TIMEOUT`	Scoring pipeline exceeded the `request_timeout_ms` limit. A fail-open APPROVE decision is returned.	Check engine latency metrics. Consider increasing timeout or investigating enrichment provider latency.

Rate limits

Endpoint	Default limit	Burst allowance
`POST /api/v3/score`	500 requests/second per token	Up to 1,000 req/s for 5 seconds
`POST /api/v3/score/step-up-result`	200 requests/second per token	—
`POST /api/v3/feedback`	50 requests/second per token	—
`GET /api/v3/health`	10 requests/minute per token	—

Rate limit increases If your transaction volume requires higher limits, contact your FraudShield implementation team. Rate limits are configurable per API token and are not shared across tokens.