zarinpal-analytics-backend/docs/METRIC-CATALOGUE.md

Analytics Metric Catalogue

• Status: Draft — definitions are approved individually
• Version: 0.1.0
• Last updated: 2026-08-20

Every merchant-facing number must identify its grain, formula, source fields, filters, time basis, unit, missing-data behavior, trace path, and definition version.

Confirmed successful sessions

• Canonical id: confirmed_successful_sessions
• Grain: distinct payment session
• Formula: count payment sessions where source session_status = 'Verified'
• Unit: sessions
• Time attribution: session created_at, converted to Asia/Tehran local reporting date
• Missing behavior: session_status is required; unknown values are not counted and trigger quality evidence
• Traceability: drill down to eligible session identifiers and their attempt histories within the authenticated merchant
• Approved decision: Paid is not included; it remains a separate state until ZarinPal provides an authoritative definition

Paid but not confirmed as verified

• Canonical id: paid_unverified_sessions
• Grain: distinct payment session
• Formula: count payment sessions where source session_status = 'Paid'
• Unit: sessions
• Presentation: separate operational state; never label as confirmed success or failure
• Traceability: same merchant-scoped session/attempt drill-down

Open definitions

• Success-rate denominator and treatment of Failed/Reversed/Paid
• Amount metric inclusion by session status
• Retry and recovery definitions
• Timing percentile definitions and missing coverage
• Fee-ratio terminology for obfuscated adjusted_fee
• Merchant-weighted versus transaction-weighted peer comparisons