BNPL Checkout: How to Build It

# You have roughly 300ms at checkout. You also have a rule: do not show an
# offer you cannot honour. A declined customer at the payment screen is a lost
# sale AND a complaint, and "pre-approved" is a word with consequences.

def checkout_offer(customer, cart, limits):
    # 1. HARD GATES first. Cheap, deterministic, no model involved.
    if customer["age"] < 18:                    return decline("underage")
    if not customer["kyc_complete"]:            return decline("kyc_required")
    if cart["amount_paise"] > limits["max_ticket_paise"]:
        return decline("above_max_ticket")
    if customer["active_loans"] >= limits["max_concurrent"]:
        return decline("concurrent_limit")
    if customer["dpd"] > 0:                     return decline("existing_arrears")

    # 2. Only now, the risk decision -- INSIDE what the gates permit.
    score = risk_model(customer, cart)
    if score < limits["min_score"]:             return decline("risk")

    # 3. Language matters. "Eligible to apply" is a fact you can support.
    #    "Pre-approved" implies a sanction you have not made yet.
    return {
        "show": True,
        "wording": "Eligible to apply",          # NOT "pre-approved"
        "tenures": [t for t in limits["tenures"] if cart["amount_paise"] >= t["min_paise"]],
        "indicative_apr": indicative_apr(score),  # INDICATIVE. The KFS is binding.
        "quote_id": new_quote_id(),               # everything downstream ties to this
        "expires_at": now() + minutes(15),
    }

def decline(reason):
    # A decline at checkout is a product event, not an error. Never show the
    # reason to the customer at this point -- but always store it.
    return {"show": False, "reason": reason}

# WHAT TO CHECK
# [ ] hard gates run BEFORE the model. They are cheap, they are auditable, and
#     they keep the model out of decisions that were never its to make
# [ ] the word on the button is a compliance decision. "Pre-approved" before a
#     sanction is a promise. Get the wording signed off, not chosen by design
# [ ] indicative APR is labelled indicative EVERYWHERE, including in analytics.
#     The KFS number is the binding one and they can differ
# [ ] quote_id threads through KFS, sanction, disbursal and repayment. When
#     something goes wrong at step 7 you will reconstruct from this
# [ ] decline reasons are STORED even though they are not shown. The
#     distribution is your best early signal that a gate is mis-set
# [ ] the offer expires. An indicative rate from three hours ago is not an offer
# [ ] latency budget is real: at 300ms, a model that takes 400ms is a decline

from decimal import Decimal, ROUND_HALF_UP

# The KFS is shown BEFORE sanction and it is the single source of truth. If an
# interface says 10% and the KFS says 14% APR, the KFS is what binds. EVERY fee
# goes in it -- processing, platform, insurance premium, anything.

def build_kfs(quote, loan, fees, tenure):
    P = Decimal(loan["principal_paise"])
    total_fees = sum(Decimal(f["paise"]) for f in fees)

    # APR must include the fees. A rate quoted on principal alone while fees are
    # charged separately is the oldest trick in consumer credit and it is
    # exactly what the KFS exists to stop.
    apr = compute_apr(principal=P, fees=total_fees,
                      instalments=tenure["instalments"],
                      frequency=tenure["frequency"])

    return {
        "quote_id": quote["quote_id"],
        "lender_name": loan["regulated_entity"],   # the RE, not your brand
        "lsp_name": loan.get("lsp"),               # named separately if there is one
        "principal": P,
        "fees": [{"name": f["name"], "amount": f["paise"]} for f in fees],
        "total_fees": total_fees,
        "apr_percent": apr.quantize(Decimal("0.01"), ROUND_HALF_UP),
        "instalments": tenure["instalments"],
        "instalment_amount": instalment_amount(P, total_fees, apr, tenure),
        "total_repayable": P + total_fees + interest_total(P, apr, tenure),
        "cooling_off_days": loan["cooling_off_days"],
        "cooling_off_terms": "Exit by paying principal plus proportionate APR. "
                             "No prepayment penalty.",
        "grievance_officer": loan["grievance_contact"],
        "recovery_agent_policy_url": loan["recovery_policy_url"],
        "issued_at": now_ist(),
    }

# WHAT TO CHECK
# [ ] the KFS is rendered and ACKNOWLEDGED before sanction, not alongside it.
#     Order matters and it is checkable from your own logs
# [ ] APR includes every fee. If a fee exists anywhere in the journey and is not
#     in the KFS, the KFS is wrong
# [ ] the REGULATED ENTITY is named as the lender. A borrower who thinks your
#     brand lent them the money cannot exercise their rights against the RE
# [ ] store the exact rendered KFS, not the inputs. "What did they see" is the
#     question, and re-rendering from today's fee table will not answer it
# [ ] a changed credit limit or changed terms needs a FRESH KFS
# [ ] integer paise. Never floats. Rounding on an APR is a regulatory number
# [ ] the grievance route and the recovery-agent policy are on the document,
#     not one click away

# THE RULE: disbursal and repayment flow between the BORROWER'S BANK ACCOUNT
# and the REGULATED ENTITY. Not through the LSP. Not through a platform account.
# Not through any intermediary "pool" account. There is no clever structure.

def disburse(sanction, merchant, re_client):
    # The lender pays the merchant. You instruct; you do not hold.
    instruction = {
        "from": "REGULATED_ENTITY_ACCOUNT",      # the RE's own account
        "to": merchant["settlement_account"],
        "amount_paise": sanction["principal_paise"],
        "reference": sanction["loan_id"],
        "idempotency_key": f"disb:{sanction['loan_id']}",   # intent, not attempt
    }
    assert instruction["from"] != "PLATFORM_ACCOUNT", \
        "money must not pass through the platform"
    return re_client.disburse(instruction)

def collect(loan, instalment, re_client):
    # Repayment goes borrower -> RE. An e-mandate on the borrower's account,
    # presented by the RE. Again: you instruct, you do not receive.
    return re_client.present_mandate({
        "mandate_id": loan["mandate_id"],
        "amount_paise": instalment["amount_paise"],
        "due_date": instalment["due_date"],
        "idempotency_key": f"coll:{loan['loan_id']}:{instalment['seq']}",
    })

# WHAT TO CHECK
# [ ] there is NO account in your architecture that briefly holds borrower money.
#     If one exists "for reconciliation convenience", that is the finding
# [ ] idempotency keys derive from the loan and instalment, never from a uuid4
#     per attempt. Paying a merchant twice is recoverable; collecting twice from
#     a borrower is a complaint and a refund and a trust problem
# [ ] a timeout on disbursal is UNKNOWN, not failed. Query by your own reference
# [ ] the merchant settlement account is verified before the first disbursal,
#     not after the first misdirected payment
# [ ] mandate failures are a FIRST-CLASS path with their own state machine, not
#     an exception. They are routine, not exceptional
# [ ] reconcile disbursals against sanctions daily. A disbursal with no sanction
#     is the most serious break available here

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

# A failed instalment is routine. How you behave in the next 48 hours is where
# BNPL firms get into regulatory trouble.

def on_mandate_failure(loan, instalment, reason):
    # 1. Distinguish CANNOT PAY from DID NOT PAY. They need opposite responses
    #    and the same dashboard treats them identically.
    if reason in ("insufficient_funds",):
        path = "retry_with_notice"       # tell them BEFORE re-presenting
    elif reason in ("mandate_revoked", "account_closed"):
        path = "contact_required"
    else:
        path = "technical_retry"         # our problem, not theirs

    return {"path": path, "notify_before_retry": True,
            "retry_not_before": datetime.now(IST) + timedelta(days=1)}

# Contact rules are HARD GATES, not guidance. Same shape as Build Sheet 06.
WINDOW = (time(8, 0), time(19, 0))

def may_contact(account, channel, now=None):
    now = now or datetime.now(IST)
    t = now.timetz().replace(tzinfo=None)
    if not (WINDOW[0] <= t <= WINDOW[1]):
        return {"allow": False, "why": "outside_0800_1900_IST"}   # DIGITAL TOO
    if account.grievance_open:
        return {"allow": False, "why": "recovery_suspended_grievance_pending"}
    if account.hardship_flag:
        return {"allow": False, "why": "hardship", "action": "human_review"}
    if account.contacts_today(channel) >= account.cap(channel):
        return {"allow": False, "why": "frequency_cap"}
    return {"allow": True, "must_record": channel == "voice"}

# WHAT TO CHECK
# [ ] the window covers SMS, WhatsApp and push, not just calls. The scheduler is
#     where this is usually missing, because the dialler is the obvious place
# [ ] NEVER access contacts, call logs or media files. Prohibited outright.
#     Camera, microphone and location need explicit consent and nothing else
# [ ] no social shaming, ever. Contacting anyone other than the borrower about
#     the debt is where this stops being a compliance matter
# [ ] outsourcing collections does not outsource liability. Audit the agency's
#     logs; an assurance is not evidence
# [ ] a hardship flag raised anywhere -- including in support -- pauses
#     collections. Different vendors and different databases is the usual cause
#     of a technically compliant message that is indefensible in substance
# [ ] all digital lending data stored EXCLUSIVELY IN INDIA