{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "name": "score_transaction",
  "description": "Score a payment transaction with MaiGuard and receive riskScore, decision (ALLOW/REVIEW/BLOCK), and matched rules.",
  "inputSchema": {
    "type": "object",
    "required": ["userId", "amount", "currency"],
    "properties": {
      "userId": {
        "type": "string",
        "description": "Stable customer ID matching onboarding records"
      },
      "amount": {
        "type": "number",
        "minimum": 0,
        "description": "Transaction amount (positive number)"
      },
      "currency": {
        "type": "string",
        "description": "ISO 4217 currency code (e.g. NGN, USD, GHS)"
      },
      "occurredAt": {
        "type": "string",
        "format": "date-time",
        "description": "Transaction timestamp (ISO 8601)"
      },
      "ipAddress": { "type": "string" },
      "userAgent": { "type": "string" },
      "deviceSessionId": {
        "type": "string",
        "description": "From MaiGuard Browser SDK (CDN); must start with ds_"
      },
      "metadata": {
        "type": "object",
        "description": "Optional business context; include counterparty fields for AML screening"
      }
    },
    "additionalProperties": true
  },
  "outputSchema": {
    "type": "object",
    "properties": {
      "success": { "type": "boolean" },
      "data": {
        "type": "object",
        "properties": {
          "transactionId": { "type": "string", "format": "uuid" },
          "riskScore": { "type": "integer", "minimum": 0, "maximum": 100 },
          "decision": { "type": "string", "enum": ["ALLOW", "REVIEW", "BLOCK"] },
          "matchedRules": { "type": "array" },
          "shadowEvaluation": { "type": "object" }
        }
      }
    }
  },
  "endpoint": {
    "method": "POST",
    "url": "https://api.maiguard.com/v1/transactions/score",
    "authentication": {
      "type": "http",
      "scheme": "bearer",
      "description": "Set MAIGUARD_API_KEY environment variable to your pk_live_* or pk_test_* key"
    }
  },
  "documentation": {
    "openapi": "https://maiguard.com/openapi.yaml",
    "apiReference": "https://maiguard.com/en/api-reference#score-transaction",
    "aiContext": "https://maiguard.com/ai-context.json"
  }
}