Recurring Payments: How to Build It

from decimal import Decimal

# AFA (Additional Factor of Authentication -- usually OTP or UPI PIN) is
# ALWAYS required for: registration, modification, withdrawal, the FIRST
# transaction, a customer opt-out, and any debit above the threshold.
#
# After registration, recurring debits run without AFA UP TO A LIMIT.

GENERAL_LIMIT = Decimal("15000")      # per recurring transaction

# The higher limit applies to EXACTLY THREE CATEGORIES. This is the most
# misreported rule in the whole framework.
ENHANCED_LIMIT = Decimal("100000")
ENHANCED_CATEGORIES = {
    "INSURANCE_PREMIUM",
    "MUTUAL_FUND_SIP",
    "CREDIT_CARD_BILL",
}
# NOT INCLUDED: loan EMIs. Not personal loans, not BNPL instalments, not auto
# loans. An EMI above Rs 15,000 needs AFA on every single debit, and a lending
# product built on the assumption of Rs 1 lakh headroom will fail at collection
# for exactly the customers whose instalments matter most.

def needs_afa(mandate, amount: Decimal, is_first: bool) -> dict:
    if is_first:
        return {"afa": True, "why": "first_transaction"}
    limit = (ENHANCED_LIMIT if mandate["category"] in ENHANCED_CATEGORIES
             else GENERAL_LIMIT)
    if amount > limit:
        return {"afa": True, "why": "above_threshold", "limit": limit}
    if amount > mandate["max_amount"]:
        # The CUSTOMER's own cap, set at registration for variable amounts.
        # Separate from the regulatory limit and often lower.
        return {"afa": False, "blocked": True, "why": "exceeds_customer_cap"}
    return {"afa": False}

# WHAT TO CHECK
# [ ] ENHANCED_CATEGORIES is a closed set in code, not a config someone can
#     widen. Adding "LOAN_EMI" to it is a one-line compliance breach
# [ ] the customer's own cap is enforced separately from the regulatory limit,
#     and a debit exceeding it is BLOCKED, not escalated to AFA
# [ ] amounts in Decimal or integer paise. Never float
# [ ] "first transaction" means first under THIS mandate, not first ever for
#     this customer. A re-registered mandate has a new first transaction
# [ ] validity period is stored and enforced. A debit after expiry is
#     unauthorised, and customer liability rules then apply to you
# [ ] issuers may NOT charge the customer for the e-mandate facility. If a fee
#     appears anywhere in your flow, it is yours to absorb, not theirs

from datetime import datetime, timedelta, timezone
IST = timezone(timedelta(hours=5, minutes=30))

# 24 hours before EVERY debit. Not a courtesy -- a condition of debiting.
# It must carry the amount, the debit date and the merchant name, and it goes
# on the channel the customer chose at registration.

NOTIFY_LEAD = timedelta(hours=24)
# The only carve-out: auto-replenishment of FASTag and NCMC balances.
EXEMPT = {"FASTAG_REPLENISH", "NCMC_REPLENISH"}

def schedule_pre_debit(mandate, instalment):
    if mandate["category"] in EXEMPT:
        return {"required": False}
    send_at = instalment["debit_at"] - NOTIFY_LEAD
    return {
        "required": True,
        "send_at": send_at,
        "channel": mandate["notify_channel"],        # chosen at registration
        "content": {
            "amount": instalment["amount"],
            "debit_date": instalment["debit_at"].astimezone(IST).date().isoformat(),
            "merchant_name": mandate["merchant_display_name"],
            "opt_out_url": opt_out_link(mandate, instalment),   # AFA-protected
        },
    }

def may_debit(instalment) -> dict:
    # The gate. A debit whose notification did not go out 24h earlier is not
    # a debit you are entitled to present.
    n = instalment.get("pre_debit_notification")
    if instalment["category"] in EXEMPT:
        return {"allow": True}
    if not n or n["status"] != "delivered":
        return {"allow": False, "why": "pre_debit_notification_not_delivered"}
    if instalment["debit_at"] - n["delivered_at"] < NOTIFY_LEAD:
        return {"allow": False, "why": "notification_too_late"}
    if instalment.get("customer_opted_out"):
        return {"allow": False, "why": "opted_out_for_this_debit"}
    return {"allow": True}

# WHAT TO CHECK
# [ ] may_debit() runs at PRESENTATION time, not at scheduling time. A
#     notification that failed to deliver overnight must stop the debit
# [ ] "delivered", not "sent". A queued SMS is not a notification
# [ ] the opt-out link is AFA-protected and works for a SINGLE debit as well as
#     the whole mandate. Both are required and teams usually build only the second
# [ ] the merchant name in the notification is the name the customer RECOGNISES,
#     not your legal entity. Unrecognised names drive chargebacks and complaints
# [ ] a moved debit date needs a fresh 24-hour notification. Rescheduling does
#     not inherit the old one
# [ ] notification delivery is logged per instalment. In a dispute this is the
#     evidence that you were entitled to debit at all

# A mandate failure is NOT a retryable soft decline. Retrying it is pointless:
# the mandate itself is the problem, and only the customer can fix it.
#
# THREE FAILURE MODES, THREE DIFFERENT CUSTOMER ACTIONS. Sending the same
# "update your payment method" email to all three routes people to the wrong
# action and collapses recovery.

RECOVERY = {
    "mandate_missing_or_cancelled": {
        "customer_action": "re-register the mandate",
        "how": {"CARD": "3DS authentication", "UPI": "approve in your UPI app",
                "ENACH": "re-authorise with your bank"},
        "retryable_without_customer": False,
    },
    "above_threshold": {
        "customer_action": "approve this one payment",
        "how": {"CARD": "OTP for this transaction", "UPI": "UPI PIN for this transaction",
                "ENACH": "authorise this debit"},
        "retryable_without_customer": False,
        "note": "the mandate is fine; this single amount needs AFA",
    },
    "pre_debit_notification_failed": {
        "customer_action": "confirm in your banking app before the next attempt",
        "retryable_without_customer": False,
    },
    "insufficient_funds": {
        "customer_action": "add funds",
        "retryable_without_customer": True,        # the ONLY genuinely retryable one
        "retry_after_days": 3,
    },
}

def recovery_plan(failure, mandate):
    plan = RECOVERY.get(failure["code"])
    if not plan:
        return {"path": "human_review", "code": failure["code"]}
    msg = plan["customer_action"]
    how = plan.get("how", {}).get(mandate["rail"])
    return {"tell_customer": f"{msg}" + (f" — {how}" if how else ""),
            "auto_retry": plan["retryable_without_customer"],
            # If card re-registration goes unanswered, offer UPI AutoPay. It is
            # a lower-friction registration and recovers subscribers that a
            # second 3DS attempt will not.
            "fallback_rail": "UPI" if mandate["rail"] == "CARD" else None}

# WHAT TO CHECK
# [ ] mandate failures are a DISTINCT failure class in your dunning logic, not
#     lumped in with card declines. They behave nothing alike
# [ ] the message names the specific action. "Update your payment method" is
#     wrong for two of the three modes
# [ ] auto-retry ONLY on insufficient funds, and with notice before re-presenting
# [ ] offer UPI AutoPay as a fallback when card re-registration goes unanswered.
#     Different friction, different success rate, same framework
# [ ] measure recovery rate PER FAILURE MODE. A blended number hides that one of
#     the three is broken
# [ ] a failure never silently stops the subscription. It starts a defined
#     sequence with an end state