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

Analytics Metric Catalogue

• Status: Draft — listed definitions approved; remaining peer weighting is open
• Version: 0.2.0
• Last updated: 2026-08-20

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

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

Paid volume

• Canonical id: bank_paid_amount_rial
• Formula: sum session amount 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

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.

Open definition

• Merchant-weighted versus transaction-weighted peer comparisons