Embedded Insurance: How to Build It

from datetime import datetime, timedelta
from decimal import Decimal

# STEP 4. THE OFFER.
# The rule is not "get consent", it is "be able to show what they saw".
# Store the RENDERED offer, not the inputs that produced it. Six months from
# now the premium table, the wording and the layout will all have changed, and
# the question in a complaint is always: what did this person actually see.

def render_offer(quote, product):
    return {
        "default_selected": False,          # NEVER pre-tick. Not a growth lever.
        "decline_equally_prominent": True,  # same size, same weight, same row
        "premium_shown_inclusive": quote["premium_paise"],   # no drip pricing
        "gst_shown_separately": quote["gst_paise"],
        "insurer_named": product["insurer_legal_name"],      # not your brand
        "your_role_disclosed": "corporate_agent",            # say what you are
        "cis_url": product["customer_information_sheet_url"],
        "no_countdown": True,
        "main_purchase_blocked_if_declined": False,          # assert, don't hope
    }

def record_consent(session, offer):
    assert offer["default_selected"] is False, "pre-selected cover is a defect"
    return {
        "customer_id": session["customer_id"],
        "at": datetime.utcnow().isoformat(),
        "action": "ACCEPTED",                 # explicit, affirmative, logged
        "offer_snapshot_hash": sha256_of(offer),   # what they saw
        "offer_snapshot_blob": offer,              # keep the blob, not a recipe
        "channel": session["channel"],
    }

# STEP 5. THE PREMIUM. THIS IS THE ONE.
# Section 64VB, Insurance Act 1938: the insurer may not assume risk until the
# premium is received. Sub-section (4): where you collect premium on the
# insurer's behalf you must deposit or dispatch it to the insurer IN FULL,
# WITHOUT DEDUCTING YOUR COMMISSION, WITHIN 24 HOURS of collection, excluding
# bank and postal holidays.
#
# Your PSP settles T+2. Your finance system nets fees. Both are wrong here,
# and both are wrong by default rather than by anyone's decision.

REMIT_HOURS = 24

def remittance_due(collected_at, holidays):
    due, remaining = collected_at, timedelta(hours=REMIT_HOURS)
    while remaining > timedelta(0):
        due += timedelta(hours=1)
        if due.date() not in holidays:       # bank and postal holidays excluded
            remaining -= timedelta(hours=1)
    return due

def build_remittance(collections, commission_ledger):
    """One job: move the gross premium. Commission is settled separately."""
    gross = sum(Decimal(c["premium_paise"]) for c in collections)
    netted = sum(Decimal(c.get("commission_withheld_paise", 0)) for c in collections)
    assert netted == 0, "commission may not be deducted from premium remitted"
    commission_ledger.accrue(collections)    # invoice the insurer, separately
    return {"to": "insurer", "amount_paise": gross, "basis": "gross"}

def cover_status(policy, remittance):
    # What the customer is told must track what is legally true.
    if not remittance or not remittance["confirmed_by_insurer"]:
        return "COVER_PENDING"               # not "Insured". Not a tick.
    return "COVER_ACTIVE"

# WHAT TO CHECK
# [ ] measure remittance age as a QUEUE with an owner, in hours, not as a
#     month-end reconciliation. A regulator sampled 67 policies and found
#     delays beyond 30 days; the same order covered 8,971 policies at 5-24
#     days and roughly 77,033 that simply took longer than three working days,
#     because three working days was the design
# [ ] never net commission out of premium. Accrue it and invoice separately
# [ ] the premium account is not a revenue account. It should not appear in
#     your cash position, your runway, or any sweep
# [ ] do not render "Insured" before the insurer confirms receipt. A tick in
#     your UI does not attach risk; Section 64VB does
# [ ] a payment that succeeds at your PSP and fails to remit is an OPEN
#     obligation, not a resolved transaction
# [ ] reconcile in IST against the insurer's own receipt confirmation, never
#     against your settlement file

# STEP 6. ISSUE AND DELIVER.
# Policies are issued in electronic form. From 1 January 2027 the proposal
# form, the policy and the certificate of insurance must each carry the name
# and functional identity of the person who sold it, plus the mobile number
# and email of the office through which it was sold.
#
# For an embedded product this is a SCHEMA CHANGE, not a compliance task. A
# checkout has no salesperson. You now need a defined, named, resolvable
# identity attached to every sale, and a policy-wise sales record the
# regulator can reach remotely.

def sale_attribution(session, staff_registry):
    """Every policy needs an answer to 'who sold this'. Decide it now."""
    person = staff_registry.resolve(session)     # specified person / POS person
    assert person is not None, "unattributed sale: do not issue"
    assert person["certificate_active"], "seller certificate lapsed"
    return {
        "seller_name": person["name"],
        "functional_identity": person["irdai_role"],  # e.g. specified person
        "office_mobile": person["office"]["mobile"],
        "office_email": person["office"]["email"],
    }

# STEP 7. FREE LOOK, CANCELLATION AND REFUND.
# Free look is 30 days for health, and for life policies with a term of a year
# or more, from receipt of the policy document. Separately, a retail
# policyholder may cancel at any time and receive a refund for the unexpired
# period.
#
# Section 64VB(3): a refund of premium is paid by the INSURER DIRECTLY to the
# INSURED, and shall in no case be credited to the account of the agent.

def cancellation(policy, reason, your_psp):
    route = {"payer": "insurer", "payee": "policyholder_bank_account"}
    # The one line that matters. Your checkout refunds the cart. The insurance
    # line is not part of the cart for this purpose.
    assert route["payer"] != "platform", "premium refunds do not flow through you"
    your_psp.exclude_line(policy["order_line_id"], reason="statutory_refund_route")
    return {"route": route, "clawback": "commission_reversed_via_insurer_ledger"}

# STEP 8. SERVICING. NON-DELEGABLE.
def grievance_channels(config):
    """A generic support queue is not an insurance grievance channel."""
    required = [
        config["insurance_specific_web_page"],   # published, findable
        config["ivr_option_for_insurance"],      # an actual option on the line
        config["named_grievance_officer"],
        config["turnaround_and_escalation_published"],
        config["route_to_insurer_and_ombudsman_published"],
    ]
    assert all(required), "CRM tagging is not a grievance framework"
    return required

# WHAT TO CHECK
# [ ] decide the seller identity model before 1 January 2027, not after. It
#     touches your proposal payload, your policy record and your sales log
# [ ] a lapsed specified-person certificate must block issuance, not warn
# [ ] refunds never leave your accounts. Exclude the insurance line from cart
#     refunds explicitly, in code, with a test
# [ ] renewal notices are an obligation, not a marketing campaign, and their
#     absence has been penalised
# [ ] publish the insurance grievance route on the website AND put it on the
#     phone line. Both have been found missing, in the same order
# [ ] keep policy-wise sales records in a form a regulator can access
#     remotely, including the call or session record where one exists