# 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