AI_INTEGRATION — payment-gateway-service

Sibling: APPLICATION_LOGIC · SECURITY_MODEL

Strategic anchors: 08 AI Architecture

payment-gateway-service integrates with ai-orchestrator-service for two narrow, asynchronous, advisory capabilities. AI is never in the synchronous authorize/capture path and never unilaterally blocks a payment. Every AI decision is logged with full provenance (aiProvenanceId).

1. Capabilities

Capability	Mode	Blocks payment?	HITL gate
Fraud anomaly detection (post-authorize)	async, fire-and-forget event	no	required if outcome ≥ medium
Chargeback narrative drafting	sync request, advisory output	no	always (operator must approve before submission)

Future, out of scope today: dynamic adapter routing by ML, real-time issuer reason-code triage. Both require an evaluation harness and risk register update before enablement.

2. Fraud anomaly detection

2.1 Trigger

After every melmastoon.payment.transaction.authorized.v1, the AuthorizePayment use case emits a fraud_score_request to ai-orchestrator-service via Pub/Sub topic melmastoon.ai.fraud_score.requested.v1. The payload contains no PAN, no CVV, no token — only the engineered features needed for scoring:

{
  "scoringRequestId": "scr_01HZX…",
  "tenantId":   "tnt_01H…",
  "paymentId":  "pay_01HZX…",
  "features": {
    "amountMicroNormalized": 0.62,
    "amountVsGuestP95":      1.81,
    "guestVelocity1h":       3,
    "guestVelocity24h":      4,
    "ipCountry":             "AE",
    "billingCountry":        "AF",
    "geoMismatch":           true,
    "deviceFingerprintAgeDays": 0,
    "processor":             "stripe",
    "fxQuoteCurrency":       "AFN",
    "newPaymentMethod":      true,
    "guestTenureDays":       2
  },
  "requestedAt": "2026-04-22T18:31:01.502Z"
}

2.2 Response

ai-orchestrator-service posts back to melmastoon.ai.fraud_score.completed.v1:

{
  "scoringRequestId": "scr_01HZX…",
  "paymentId":        "pay_01HZX…",
  "tenantId":         "tnt_01H…",
  "score":            0.82,
  "tier":             "high",                 // 'low' | 'medium' | 'high'
  "topSignals": [
    { "name": "geo_mismatch", "weight": 0.34 },
    { "name": "guest_velocity_24h", "weight": 0.21 },
    { "name": "amount_vs_guest_p95", "weight": 0.18 }
  ],
  "modelId":           "gm-fraud-v3-2025-Q4",
  "aiProvenanceId":    "dec_01HZX…",
  "completedAt":       "2026-04-22T18:31:02.114Z"
}

2.3 Reaction

• low → annotate transactions.metadata.fraud_score; no further action.
• medium → annotate, plus emit melmastoon.payment.fraud.review_requested.v1 for a human reviewer queue in bff-backoffice-service. Capture proceeds normally.
• high → as medium, plus auto-flag the transaction for enhanced review before subsequent auto-captures (the next capture requires explicit operator approval). Adds the pm_… to a soft watchlist for the next 24 h.
• A high score never voids or refunds automatically; that decision is always the operator's.

3. Chargeback narrative drafting

3.1 Trigger

Operator clicks "Draft narrative with AI" inside the chargeback evidence workflow. The use case SubmitChargebackEvidenceUseCase (APPLICATION_LOGIC §2.10) calls ai-orchestrator-service with a structured request:

{
  "tenantId":     "tnt_01H…",
  "chargebackId": "cbk_01HZX…",
  "context": {
    "reservation":  { "id": "rsv_01H…", "checkIn": "2026-04-15", "checkOut": "2026-04-18", "ratePlan": "non_refundable" },
    "lockAccessLog": [{ "at": "2026-04-15T20:11:00Z", "deviceId": "lck_01H…", "result": "granted" }],
    "folio":        { "totalsMicro": "560000000", "currency": "USD" },
    "guestComms":   ["2026-04-12T09:01Z guest confirmed booking", "2026-04-19T08:00Z guest checked out"],
    "chargebackReason": "fraudulent"
  },
  "outputFormat": "structured_narrative"
}

3.2 Response

{
  "draftNarrative": "On 2026-04-15 the guest checked into Property Kabul Riverside and used the room lock at 20:11 UTC (device lck_01H…), which provides physical evidence of presence…",
  "supportingExhibits": ["lockAccessLog", "folio", "guestComms"],
  "modelId":          "gm-disputes-v2-2025-Q4",
  "aiProvenanceId":   "dec_01HZX…",
  "warnings":         []
}

3.3 HITL gate

The operator must review and edit the draft. The submission API requires aiProvenanceId plus a reviewedByUserId and a reviewedAt timestamp; the server rejects submissions where the narrative was not modified at all (anti-rubber-stamp guard) unless the operator clicks "Approve as-is" which is logged distinctly.

4. PII and PCI in AI prompts

• No PAN, no CVV, no full processor token ever leaves this service into AI prompts.
• Tokens, when referenced, are represented as opaque IDs (pm_…) without metadata that could re-identify card.
• last4 and brand are the only card-derived attributes ever passed; the security review approved this as PCI-acceptable for fraud features.
• All AI requests are logged into ai-orchestrator-service with full provenance; this service stores only the aiProvenanceId on the relevant aggregate row.

5. Failure & timeout policy

• Fraud scoring is fire-and-forget. If ai-orchestrator-service is unhealthy, transactions proceed with fraud_score = null. A separate metric (payments_fraud_score_missing_total) is tracked; if it exceeds 5% over 1 h, an alert pages the AI team — not the payments team.
• Chargeback drafting timeout is 8 s; on timeout the operator sees a "AI assistance unavailable, please draft manually" message. Submission is unaffected.

6. Evaluation & rollout

• Each model version is gated behind a feature flag per tenant. New versions are rolled out at 5% → 25% → 100% with shadow scoring (the new model runs in parallel and its score is logged but not acted upon for 14 days).
• The eval harness in ai-orchestrator-service measures per-tenant precision/recall against operator-confirmed outcomes; below tenant-specific thresholds, the model is auto-rolled back for that tenant.

7. Audit & compliance

Every AI invocation produces an immutable record in audit-log-service keyed by aiProvenanceId, including: model id, prompt hash, response hash, reviewer id (for HITL), final action taken. This is sufficient for PCI auditors to confirm AI is advisory and never autonomous on payment decisions.