MerchantGuard Risk Assessment API

AI-powered risk decisioning for agentic commerce. Sub-100ms response time for AI buyer agents.

What This Does

This API provides real-time risk assessment for AI-initiated purchases. When an AI agent (like ChatGPT) wants to buy something on behalf of a user, it calls this API to get instant risk guidance.

Response format:

{
  "session_id": "sess_abc123",
  "risk_score": 0.35,
  "action": "accept",
  "reason_codes": ["high_risk_industry"],
  "advisories": [{
    "code": "industry_compliance",
    "message": "Merchant in CBD - requires enhanced monitoring",
    "severity": "info"
  }],
  "metadata": {
    "processing_ms": 45
  }
}

Quick Start

Local Development

# Install dependencies
pip install -r requirements.txt

# Run server
uvicorn app.main:app --reload

# Test endpoint
curl -X POST http://localhost:8000/api/agentic-commerce/risk-assessment \
  -H "Content-Type: application/json" \
  -d @test_payload.json

Deploy to Google Cloud Run

# Submit build
gcloud builds submit --config=cloudbuild.yaml

# Service will be available at:
# https://mg-risk-api-810654658669.us-central1.run.app

API Endpoints

POST /api/agentic-commerce/risk-assessment

Main risk assessment endpoint.

Request:

{
  "session_id": "sess_abc123",
  "currency": "usd",
  "total_amount": 19900,
  "items": [{
    "sku": "cbd-oil-1000mg",
    "quantity": 1,
    "unit_price": 19900,
    "name": "Premium CBD Oil",
    "category": "cbd"
  }],
  "buyer": {
    "email": "buyer@example.com",
    "country": "US",
    "ip_address": "1.2.3.4"
  },
  "payment_method": {
    "type": "card",
    "card_brand": "visa",
    "card_country": "US"
  },
  "merchant": {
    "merchant_id": "mch_xyz789",
    "business_name": "CBD Wellness Co",
    "industry": "cbd",
    "country": "US"
  },
  "created_at_ms": 1735689600000
}

Response:

{
  "session_id": "sess_abc123",
  "risk_score": 0.35,
  "action": "accept",
  "reason_codes": ["high_risk_industry"],
  "advisories": [],
  "ttl_ms": 30000,
  "version": "mg-risk-agent/0.1",
  "metadata": {
    "processing_ms": 45,
    "merchant_id": "mch_xyz789",
    "industry": "cbd"
  }
}

GET /api/agentic-commerce/merchant/{merchant_id}/status

Get merchant compliance status and risk indicators.

Response:

{
  "merchant_id": "mch_xyz789",
  "status": "active",
  "compliance_passport": {
    "tier": "verified",
    "checks": ["pci_dss", "kyc", "vamp_compliant"],
    "last_updated": "2025-01-15T00:00:00Z"
  },
  "risk_indicators": {
    "chargeback_rate": 0.3,
    "fraud_rate": 0.1,
    "avg_processing_time_ms": 45
  }
}

GET /api/agentic-commerce/health

Health check endpoint.

Decision Actions

• accept - Transaction approved, proceed normally
• require_3ds - Request 3D Secure authentication before processing
• decline - Soft decline, may retry with different payment method
• hard_decline - Hard decline, do not retry

Risk Heuristics

The engine evaluates:

1. Industry Risk - CBD, gaming, crypto = higher risk
2. Transaction Amount - Large transactions flagged
3. Geographic Mismatch - Buyer country ≠ merchant country
4. Card Origin - High-risk issuing countries
5. Buyer Identity - Email patterns, velocity checks
6. Cart Composition - Unusual item counts or patterns

Performance

Target: <100ms response time Actual: ~45ms average (measured in metadata.processing_ms)

Integration Example

// TypeScript client example
const response = await fetch('https://mg-risk-api.run.app/api/agentic-commerce/risk-assessment', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'X-ACP-Signature': signature, // HMAC signature
    'Idempotency-Key': uuid()
  },
  body: JSON.stringify(checkoutSession)
});

const decision = await response.json();

if (decision.action === 'accept') {
  // Proceed with payment
} else if (decision.action === 'require_3ds') {
  // Request 3D Secure authentication
} else {
  // Decline transaction
}

Security

• All requests should include X-ACP-Signature header with HMAC-SHA256 signature
• Use Idempotency-Key header to prevent duplicate processing
• Signatures verified against shared secret

Environment Variables

None required for basic operation. In production:

• ACP_SHARED_SECRET - Secret for signature verification
• BIGQUERY_PROJECT - GCP project for merchant data lookups

Next Steps

1. Pilot with 3 merchants - Test in production with real traffic
2. Add BigQuery integration - Real merchant risk profiles
3. Enhance heuristics - ML model for fraud detection
4. Partner integrations - Connect with Stripe, OpenAI, Mercury