Merchant Onboarding: How to Build It

# STEP 4. WHAT THEY SELL -- AND WHO SELLS THROUGH THEM.
# The requirement most integration guides omit entirely:
#
#   "A PA shall ensure that a marketplace onboarded by it does not accept
#    payments for a seller not onboarded on to the marketplace's platform."
#
# You are answerable for people you never onboarded. If your merchant is a
# marketplace, its sellers are inside your perimeter.

def marketplace_controls(merchant, platform):
    if not merchant["is_marketplace"]:
        return None
    return {
        # Contractual: the marketplace must not collect for unlisted sellers.
        "contract_clause_required": True,
        # Operational: you need a way to SEE this, not just a promise.
        "seller_list_feed": platform.seller_roster_endpoint,   # or periodic file
        "reconcile_settlements_to_roster": True,
        # The detection signal: money settling to a seller who is not listed.
        "alert_on": "settlement_to_unrostered_seller",
        "escalation": "suspend_marketplace_settlement, not just the seller",
    }

def category_consistency(merchant):
    """Three sources should agree. When they do not, that IS the finding."""
    declared = merchant["declared_mcc"]
    site     = classify_from_site(merchant["url"])       # what it actually sells
    catalogue= classify_from_catalogue(merchant["items"])
    agree = declared == site == catalogue
    return {"agree": agree, "declared": declared, "observed": (site, catalogue),
            # A merchant declaring a low-risk code while selling a high-risk
            # product is not a data-entry error. It is the oldest trick here.
            "action": "onboard" if agree else "manual_review"}

# STEP 5. PRICE THE RISK BEFORE YOU PRICE THE MERCHANT.
def settlement_terms(merchant, history):
    cat = merchant["mcc"]
    return {
        # Longer hold for categories that refund late: travel, events,
        # pre-order, anything delivering weeks after payment.
        "settlement_hold_days": history.p95_dispute_lag(cat),
        "rolling_reserve_pct": history.chargeback_rate(cat) * SAFETY,
        # The exposure is not the transaction. It is everything unsettled
        # when the merchant stops answering the phone.
        "max_exposure": estimate_unsettled_peak(merchant),
    }

# STEP 6. THE ESCROW, AND THE TRANSACTION IT MAY NOT TOUCH.
ESCROW_RULES = {
    "separate_account": "scheduled_commercial_bank_in_india",
    "no_commingling_with_pa_operating_funds": True,
    # Explicit in the Directions and frequently missed:
    "cash_on_delivery": "NOT PERMITTED through the escrow account",
    # PA-CB: three accounts, not one.
    "pa_cb_accounts": ["domestic_escrow", "inward_collection", "outward_collection"],
    "pa_cb_per_transaction_cap_inr": 2_500_000,      # Rs 25 lakh
    "fx_counterparty": "authorised_dealer_only",
}

# WHAT TO CHECK
# [ ] if the merchant is a marketplace, you can SEE its seller roster. A
#     contract clause with no feed behind it is not a control
# [ ] declared category is checked against the site and the catalogue, not
#     just stored
# [ ] settlement hold derives from the category's dispute lag, not from a
#     single default applied to everyone
# [ ] your exposure number is unsettled funds at peak, not average ticket
# [ ] Cash-on-Delivery never routes through the escrow account
# [ ] PA-CB: three accounts, and no FX with anyone but an Authorised Dealer
# [ ] the agent who onboarded each merchant is recorded against that merchant

from datetime import timedelta

# STEP 7. "IN LINE WITH THE MERCHANT'S BUSINESS PROFILE."
# That phrase is the design brief. It needs a profile specific enough to be
# departed from -- which a dropdown is not.

def capture_profile(application):
    # Ask at onboarding, before the merchant has reason to be careful.
    p = {
        "expected_monthly_volume": application["declared_volume"],
        "expected_avg_ticket":     application["declared_ticket"],
        "expected_geographies":    application["declared_markets"],
        "expected_refund_rate":    application["declared_refunds"],
        "mcc":                     application["category"],
    }
    assert all(v not in (None, "", []) for v in p.values()), \
        "a profile with blanks cannot be departed from"
    return p

def profile_departure(window, profile):
    # Each of these is a different fraud, not one anomaly score.
    flags = []
    if window.volume > profile["expected_monthly_volume"] * 10:
        flags.append("volume_spike")        # laundering, or a lie at onboarding
    if window.avg_ticket > profile["expected_avg_ticket"] * 5:
        flags.append("ticket_inflation")    # bust-out forming
    if window.small_auth_failure_rate > 0.5:
        flags.append("card_testing")        # stolen-card validation
    if set(window.geographies) - set(profile["expected_geographies"]):
        flags.append("unexpected_geography")
    if window.refund_rate > profile["expected_refund_rate"] * 3:
        flags.append("refund_abuse")
    return flags

# STEP 8. OFFBOARDING. NOBODY BUILDS IT UNTIL IT IS URGENT.
def offboard(merchant, ledger, policy, watchlist):
    ledger.stop_new_transactions(merchant)  # first, and immediately
    # Do NOT release on the normal cycle. Chargebacks arrive for weeks.
    ledger.freeze_settlement(
        merchant, until=now_ist() + timedelta(days=policy["dispute_window_days"]))
    # The DIRECTORS, not the entity. The same people return under a new name.
    watchlist.add_people(merchant["directors"], reason=merchant["termination_reason"])
    return {
        "notified_with_reason": True,
        "record_retained": True,            # a terminated merchant complains
        # Settle this in policy BEFORE you need it: the merchant's customers
        # are owed refunds out of money you are holding.
        "customer_refund_position": policy["terminated_merchant_refunds"],
    }

# WHAT TO CHECK
# [ ] the profile has NUMBERS. A category label makes every transaction
#     compliant by definition and the obligation unmeetable
# [ ] each departure type routes differently. Card testing is an incident;
#     a volume spike is a review
# [ ] offboarding freezes settlement rather than releasing it on schedule
# [ ] the DIRECTORS go on the internal list, not the company
# [ ] the refund position for a terminated merchant's customers is decided
#     in policy, not improvised by whoever is on shift
# [ ] the full record survives termination