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

Analytics Metric Catalogue

• Status: Approved specification — implementation authorized 2026-08-20
• Version: 0.5.0
• Last updated: 2026-08-22

Every merchant-facing number identifies its grain, formula, source fields, filters, Tehran-local period, unit, missing-data behavior, trace path, and definition version.

Physical source mapping

• Session-grain metrics read payment_sessions, scoped by merchant_id and the approved half-open created_at period.
• Attempt-grain diagnostics and timings join payment_attempts.payment_session_id to the already merchant-scoped session set.
• Money uses payment_sessions.amount_rial and payment_sessions.fee_amount_rial exactly once per session.
• Terminal filters join the session's terminal_id; peer cohorts join the merchant's category_id and exclude the active merchant.
• The sole completed import_runs row identifies the immutable MVP dataset snapshot included in cache/result metadata.
• calendar_dates defines Saturday–Friday weeks, Jalali months, and Persian seasons; it intentionally has no holiday dimension. Growth reports use their own reviewed, versioned event-evidence catalog under ADR 0015.

Bank-paid sessions

• Canonical id: bank_paid_sessions
• Grain: distinct payment session
• Formula: count sessions where session_status IN ('Paid', 'Verified')
• Meaning: the buyer completed the bank payment and funds were deducted
• Unit: sessions
• Time attribution: session created_at in Asia/Tehran
• Traceability: merchant-scoped session identifiers and attempt histories

Payment success rate

• Canonical id: payment_success_rate
• Numerator: bank_paid_sessions
• Denominator: sessions where session_status IN ('Paid', 'Verified', 'Failed', 'Reversed')
• Formula: numerator / denominator; undefined when denominator is zero
• Unknown statuses: excluded from both sides and disclosed as coverage/quality evidence until classified
• Unit: percentage

Verified sessions

• Canonical id: verified_sessions
• Formula: count sessions where session_status = 'Verified'
• Meaning: bank payment and merchant verification are complete; the payment is finalized
• Unit: sessions

Unverified paid sessions

• Canonical id: unverified_paid_sessions
• Formula: count sessions where session_status = 'Paid'
• Meaning: bank payment succeeded and funds were deducted, but merchant verification is incomplete
• Presentation: actionable verification gap; never label as failure
• Unit: sessions

Verification completion rate

• Canonical id: verification_completion_rate
• Formula: verified_sessions / bank_paid_sessions; undefined when no bank-paid sessions exist
• Unit: percentage

Transaction status analytics

• total_sessions: count all merchant-scoped sessions in the selected half-open reporting period.
• bank_success_rate: sessions with status Paid or Verified divided by total_sessions; undefined when the total is zero.
• failure_rate: sessions with status Failed divided by total_sessions; undefined when the total is zero.
• Status distribution reports Paid, Verified, Failed, and Reversed separately as count and share of total_sessions.
• Trend grain is hourly for a day, daily for a week or Jalali month, and Saturday-aligned weekly for a Persian season. Empty buckets are returned as zeroes.

Paid volume

• Canonical id: bank_paid_amount_rial
• Formula: sum session amount_rial once where session_status IN ('Paid', 'Verified')
• Unit: Rial
• Subsets: verified_amount_rial uses Verified; unverified_paid_amount_rial uses Paid

Retried sessions and eventual payment

• retried_sessions: count sessions containing more than one payment attempt
• eventually_paid_after_retry_sessions: count retried sessions whose final session status is Paid or Verified and which contain a lower-try_seq attempt whose status is neither Paid nor Verified
• retry_recovery_rate: eventually_paid_after_retry_sessions / retried_sessions; undefined when no retried sessions exist
• Grain/unit: distinct sessions
• Traceability: ordered merchant-scoped attempt history; never depend on CSV row order

Payment-stage diagnostics

• no_attempt_sessions: count sessions with zero normalized payment attempts. During challenge bootstrap this corresponds to the source marker try_seq = 0 AND try_status = 'NoAttempt'; the marker itself is not an attempt.
• reached_bank_sessions: count distinct sessions containing at least one attempt with try_status IN ('InBank', 'Paid', 'Verified', 'Reversed').
• in_bank_without_result_sessions: count sessions whose latest positive-sequence attempt is InBank and which have no later Paid, Verified, Failed, or Reversed attempt.
• failed_sessions: count sessions with final session_status = 'Failed'; drill-down may distinguish zero-attempt, reached-bank, and other observable stages without inventing undocumented failure causes.
• Grain/unit: distinct payment sessions; attempt-stage counts must deduplicate by session when presented as sessions.

Processing time

• Report median (p50) and p95 separately for init_time_ms and verify_time_ms
• Include only non-null values for the relevant field
• Always show contributing sample count and coverage percentage
• Do not replace missing timing with zero
• Unit: milliseconds, with human-readable seconds allowed as an additional presentation

Merchant fee

• Canonical field: fee_amount_rial, sourced from CSV adjusted_fee and stored once per session
• paid_fee_amount_rial: sum session fee once where session_status IN ('Paid', 'Verified')
• paid_fee_rate: paid_fee_amount_rial / bank_paid_amount_rial; undefined when paid amount is zero
• Meaning/presentation: real merchant fee in Rial; do not label it obfuscated or relative-only in the product
• Retry rule: never sum the repeated source value per attempt

Common behavior

• Rates are recomputed from summed numerator/denominator components for every selected day, Saturday–Friday week, Jalali month, and Persian season.
• Zero, undefined, missing, suppressed peer value, and calculation failure remain distinct states.
• Paid and Verified are both bank-payment successes, but only Verified is finalized.
• Reversed is not in the success numerator; display it separately when non-zero.
• NoAttempt is a source session marker, not a failed payment attempt. InBank means the user reached a bank gateway but no later outcome was recorded for that attempt; do not call it a bank rejection.

Peer comparison

• Cohort: eligible merchants in the active merchant's category for the same selected reporting period; always exclude the active merchant.
• Availability: return a typed suppressed state unless at least 10 other merchants and 1,000 combined peer payment sessions contribute. Suppression never hides the active merchant's own metrics.
• Weighting: calculate each eligible peer merchant's metric independently, then use the median of those merchant values. Every merchant contributes one value regardless of payment volume.
• Rationale: merchant volume is extremely skewed (median 78 attempts, p95 8,915, maximum 1,138,592). A transaction-weighted average would mostly describe the largest merchants, while a merchant-weighted median represents a typical peer and resists extreme values.
• Output: expose the cohort median and the active merchant's performance percentile; never expose an individual peer's identity, value, or rank.
• Percentile direction: a higher displayed percentile always means better performance. Use the natural direction for payment success, verification completion, and retry recovery; invert the ranking direction for processing time and paid fee rate, where lower is better.
• Benchmarked metrics: payment_success_rate, verification_completion_rate, retry_recovery_rate, init_time_ms p50/p95, verify_time_ms p50/p95, and paid_fee_rate.
• Periods: calculate benchmarks for the same selected day, Saturday–Friday week, Jalali month, or Persian season as the active merchant value. Never compare unlike periods.