Reward Computation Logic

The Reward Computation Logic is the intelligence engine of Credit Card Co-Pilot. It ensures that whenever you are at a checkout counter or an online payment gateway, the app doesn't just guess which card is best—it calculates the precise monetary value you will receive back.

The engine processes real-time transaction data against your specific card portfolio to provide an "apples-to-apples" comparison of cashback, points, and miles.

The Multi-Layered Calculation Engine

The system evaluates rewards through a hierarchical "Waterfall" logic. It starts with the most specific rules and falls back to general rules only if a specialized match isn't found.

1. Match Hierarchy

The engine identifies the reward rate by looking for matches in this order:

• Merchant Matrix: High-affinity matches for specific brands (e.g., 5% back on Amazon using an Amazon Pay ICICI card).
• Category/Channel Match: Specific rates for spending types (e.g., "Dining") combined with how you pay (e.g., "Online").
• Category-Only Match: Rewards for the merchant type regardless of the payment channel.
• Base Rate: The standard reward rate for any transaction not covered by specialized rules.

2. The Reward Formula

For every card in your wallet, the engine calculates the Effective Rate using the following formula:

Effective Rate = (Base Rate + Category Bonus) × Channel Multiplier

The system then converts the reward into a standardized Cash Value (INR):

Total Value = (Transaction Amount × Effective Rate) + Milestone Proximity Bonus

Key Factors in Computation

Reward Normalization

Since different cards offer different currencies (Reward Points, Air Miles, or direct Cashback), the engine uses a pointValue conversion factor. This allows the system to compare a card offering "5 points per ₹100" with a "1.5% cashback" card accurately.

Channel Sensitivity

The logic distinguishes between Online, Offline (POS), and UPI transactions. Many modern cards offer accelerated rewards (e.g., 3x points) for online spending while providing only base rewards for physical swipes. The engine automatically detects this "Channel Multiplier" to refine its recommendation.

Reward Capping & Limits

To prevent users from missing out on rewards due to hidden bank limits, the engine tracks:

• Usage Caps: Monitors if you have reached a monthly or statement-cycle limit for a specific category.
• "Near Cap" Alerts: Identifies if a transaction will put you within 20% of your reward limit, potentially suggesting a secondary card to maximize total gains.

Milestone Integration

One of the most powerful features of the computation logic is the inclusion of Milestone Proximity. The engine doesn't just look at the 1% or 2% you get today; it looks at what that spend unlocks tomorrow.

• Progress Tracking: The engine calculates how much closer a transaction brings you to a spend threshold (e.g., "Spend ₹1 Lakh to get a ₹2,000 voucher").
• Bonus Valuation: If a transaction helps you cross a milestone, the "Bonus Value" is factored into the card's ranking, often making a lower-rate card the "Best" choice because it unlocks a large lump-sum reward.

Real-Time Transparency (Explainability)

Every recommendation comes with a breakdown so you can trust the math. The engine provides:

• Rule Source: Tells you if the recommendation is based on a specific merchant deal or a general category rule.
• Confidence Score: A high/medium/low indicator of how certain the engine is about the merchant's categorization.
• Reasoning: Short, human-readable strings like "5% cashback on online shopping. Best rate in your wallet."

Developer Reference: Reward Breakdown Shape

The resulting computation for each card follows this structure:

interface RewardBreakdown {
  baseRate: number;        // e.g., 0.01 for 1%
  effectiveRate: number;   // Final rate after multipliers
  rewardType: string;      // "cashback" | "points" | "miles"
  cashValue: number;       // The final INR value of the reward
  isAtCap: boolean;        // Whether this card has hit its reward limit
  milestoneProgressPct: number; // 0-100% progress toward the next big bonus
}