ONDC.

How Do You Run One Order Through Four Companies That Don't Trust Each Other's Databases?

It is Dhanteras evening in Moradabad, the night families buy brass and silver for luck. Rehana Ansari, 41, runs Ansari Brass Works from a narrow shop near the old market: puja thalis, diyas, small idols, polished by her brother in the back room. Two years ago she listed her stock on a seller app her trade association recommended. She has never built a website, and she has never heard of most of the apps her orders come from.

At 7:41 pm her tablet chimes: a puja thali, ordered from Pune through a payments app. At 7:43, diyas for a family in Kolkata, through a bank's shopping tab. At 7:44, two people tap "Add to cart" on her last brass Lakshmi–Ganesh set within a second: one in Lucknow on a grocery app, one in Jaipur on a loyalty marketplace. Rehana sees one order for it; the Jaipur buyer sees "Sorry, this item is no longer available".

The Pune buyer has a worse minute. She pays, the screen says "Confirming your order with the seller…", and the spinner keeps spinning. She taps "Place order" again. Two minutes later: "Order placed". Rehana's tablet shows one thali order from Pune, not two. At 8:10 a rider from a small Moradabad delivery company reads out a pickup code and takes the parcels. None of these companies runs the others. They agree on nothing except a protocol, a registry of who's who, and rules for money and complaints.

This is the system we'll design today.

The Interview Begins#

You're interviewing at a company that wants to join an open commerce network as a seller-side platform. The interviewer shares two screenshots. The first is a seller's order list on a tablet: four orders in four minutes, each tagged with a different buyer app's name. The second is a buyer's phone showing "Confirming your order with the seller…" under a spinner.

People often call ONDC "UPI for commerce", and the analogy was there from the start: Nandan Nilekani, an adviser to ONDC, wanted to do for e-commerce what UPI had done for payments (Bloomberg, April 2022). The analogy is useful for the shape (many apps on one set of open rails, with a neutral operator in the middle) and misleading for the mechanics. A UPI payment is one atomic debit and credit routed through a central switch; we designed that in UPI (Bonus Problem 1). An ONDC order is a conversation between companies that lasts from a search to a return window days later, with no central switch in the middle of it at all.

Your Questions#

Functional Requirements#

Non-Functional Requirements#

Orders and Messages#

Search Fan-Out and Catalogues#

Keys, Registry and Money#

Key Metrics Summary#

System Architecture#

%% title: An open network: parties talk directly; the shared services stay thin
flowchart TD
  subgraph L1["Layer 1 · Buyers"]
    direction LR
    BUY@{ icon: "sd:users", label: "Buyers<br/>Pune, Kolkata, Lucknow, Jaipur" }
    BAP["Buyer apps · BAP<br/>catalogue cache, cart, checkout, collector"]:::core
  end
  subgraph L2["Layer 2 · Shared network services"]
    direction LR
    REG@{ icon: "sd:id", label: "Registry<br/>subscribers, keys, domains, cities" }
    GW@{ icon: "sd:gateway", label: "Gateway<br/>multicasts search only" }
  end
  subgraph L3["Layer 3 · Supply"]
    direction LR
    BPP["Seller apps · BPP<br/>catalogues, quotes, orders"]:::hot
    SOR@{ icon: "sd:store", label: "Sellers on record<br/>Ansari Brass Works" }
    LSP@{ icon: "sd:delivery", label: "Logistics apps<br/>couriers, small fleets" }
  end
  subgraph L4["Layer 4 · Money and trust"]
    direction LR
    SA@{ icon: "sd:bank", label: "Settlement agency<br/>match, net, bank instructions" }
    IGM@{ icon: "sd:chat", label: "Issues and grievances<br/>IGM, GROs, ODR" }
    OBS@{ icon: "sd:dashboard", label: "Network observability<br/>masked logs, scorecards" }
  end
  BUY ==> BAP
  BAP ==>|"search"| GW
  GW ==>|"multicast by domain, city"| BPP
  BPP -.->|"on_search, direct"| BAP
  BAP ==>|"select, init, confirm, status"| BPP
  BPP ==>|"logistics search to confirm"| LSP
  BPP --> SOR
  BAP -.->|"key lookup, cached"| REG
  BPP -.->|"key lookup, cached"| REG
  BAP -->|"settle"| SA
  BPP -->|"settle"| SA
  BAP --> IGM
  BPP -.->|"logs"| OBS
  class BUY client
  class REG,GW edge
  class SOR store
  class LSP external
  class SA store
  class IGM service
  class OBS service

KEY INSIGHTS:

• The network is a protocol, not a platform. The registry and gateways carry identities and searches; orders, quotes, statuses and money instructions go peer to peer
• Consistency comes from the protocol's rules, not from a database. Ids, idempotent request and callback pairs, ordered states and deterministic failure rules make two sets of books agree
• Every edge is a trust boundary. Each call is signed by its sender and verified against the registry by its receiver, so a participant can be held to what it sent

Data Flow: The Pune Thali#

%% title: The Pune thali, from cached search to rider pickup
sequenceDiagram
  autonumber
  participant B as Payments app · BAP
  participant S as Rehana's seller app · BPP
  participant L as Logistics app
  Note over B: search served from its catalogue cache
  B->>S: select thali, txn T1
  S-->>B: ACK
  S->>L: logistics search Moradabad to Pune
  L-->>S: ACK, then on_search with options
  S->>B: on_select quote · item + delivery
  B->>S: init billing, address, payment terms
  S->>L: logistics init
  S->>B: on_init with cancellation and settlement terms
  B->>B: buyer pays · order id O-77 created
  B->>S: confirm O-77
  S-->>B: ACK · order held, not yet sent to shop
  S->>L: logistics confirm
  S->>B: on_confirm O-77 Accepted
  B-->>S: ACK · now released to Rehana
  L->>S: on_status Order-picked-up
  S->>B: on_status Order-picked-up

MEANWHILE, IN PARALLEL:

• Every arrow is signed by its sender and verified against a cached copy of the sender's registry key
• One transaction_id runs through select, init and confirm; each request and callback pair has its own message_id, so either side can match callbacks and drop duplicates
• Both sides log every message, and push masked copies to network observability

Deep Dive 1: Every Message Is a Signed Contract (Week 9 Concepts: Security Architecture; Week 2: Webhook Delivery)#

This builds on Week 9, Day 5 · Security Architecture and Week 2, Day 4 · Webhook Delivery.

What is published: ONDC's signing document says that because of "the commercial nature of the transactions, every request/callback pair is considered to be a 'contract' between two parties", so all requests and callbacks are signed and verified. The digest is BLAKE-512 over the body; the signing string is (created), (expires) and the digest; the signature is Ed25519, in an Authorization header whose keyId is {subscriber_id}|{unique_key_id}|{algorithm}. A gateway forwarding a search adds its own X-Gateway-Authorization header, and the seller app verifies both. With no valid key, the receiver NACKs as unauthorised. To join, a participant needs a domain name (its subscriber_id) with an SSL certificate the registry checks by OCSP, an Ed25519 signing key pair and an X25519 encryption key pair, a site-verification page carrying a signed request id, and an /on_subscribe endpoint that must decrypt the registry's encrypted challenge. The registry's recommended rate limits are 10 a minute for /subscribe and 7,600 for /lookup.

%% title: Joining the network, then every message after
flowchart TD
  NP["New participant<br/>FQDN, SSL, two key pairs"]:::service
  SUB@{ icon: "sd:id", label: "Registry /subscribe<br/>schema, OCSP, site check" }
  CH@{ icon: "sd:lock", label: "Challenge to /on_subscribe<br/>X25519 shared key, AES" }
  LIVE["Listed: roles, domains,<br/>cities, public keys"]:::core
  SIGN["Each request: BLAKE-512 digest,<br/>Ed25519 signature, keyId"]:::hot
  RX["Receiver: key from cache<br/>or /lookup, then verify"]:::core
  BAD["NACK, unauthorised"]:::bad
  NP ==> SUB ==> CH ==> LIVE
  LIVE -.->|"keys published"| RX
  SIGN ==> RX
  RX -.->|"no key or bad signature"| BAD
  class SUB edge
  class CH edge

• Sign the bytes you send, verify the bytes you got. Re-serialising JSON changes whitespace and key order; ONDC's auth-header guide says to hash the "raw payload".
• Cache keys, not answers. A cache keyed by (subscriber_id, unique_key_id) with a TTL of minutes absorbs nearly every verification. On a failure, refresh that one key once before NACKing: it may have just rotated.
• The registry is a dependency with a budget. If it's slow, cached keys keep the network running; only new participants wait, which is the right failure.
• Signatures make logs evidence. A signed /on_select with a price is provably what the seller app said; that matters in disputes and reconciliation.
• It's webhook delivery in both directions. Every callback is a webhook between companies: signed, retried with a cap, deduplicated by id.

# network/auth.py

"""
Signing and verifying ONDC-style requests (illustrative, using PyNaCl and hashlib).
Digest: BLAKE2b-512 of the raw body. Signing string: (created), (expires), digest.
Keys are looked up in the registry by subscriber id and key id, then cached.
"""

import base64, hashlib, time
from nacl.signing import SigningKey, VerifyKey


def signing_string(body: bytes, created: int, expires: int) -> bytes:
    digest = base64.b64encode(hashlib.blake2b(body, digest_size=64).digest()).decode()
    return f"(created): {created}\n(expires): {expires}\ndigest: BLAKE-512={digest}".encode()


def sign(body: bytes, sk: SigningKey, subscriber_id: str, key_id: str, ttl_s: int = 300) -> str:
    created = int(time.time()); expires = created + ttl_s
    sig = base64.b64encode(sk.sign(signing_string(body, created, expires)).signature).decode()
    return (f'Signature keyId="{subscriber_id}|{key_id}|ed25519",algorithm="ed25519",'
            f'created="{created}",expires="{expires}",headers="(created) (expires) digest",'
            f'signature="{sig}"')


def verify(raw_body: bytes, header: dict, keys) -> bool:
    sub, key_id, alg = header["keyId"].split("|")
    if alg != header["algorithm"] or not (int(header["created"]) <= time.time() <= int(header["expires"])):
        return False
    msg = signing_string(raw_body, int(header["created"]), int(header["expires"]))
    for attempt in (0, 1):
        pub = keys.get(sub, key_id, refresh=(attempt == 1))     # cache first, registry on retry
        if pub is None:
            continue
        try:
            VerifyKey(base64.b64decode(pub)).verify(msg, base64.b64decode(header["signature"]))
            return True
        except Exception:
            continue                                            # maybe rotated: refresh once
    return False                                                # caller NACKs: unauthorised

Deep Dive 2: Discovery: a Broadcast You Pay Once (Week 7 Concepts: Indexing Pipeline; Week 2: Timeout Hell; Week 4: Cache Invalidation)#

This builds on Week 7, Day 2 · Indexing Pipeline, Week 2, Day 1 · Timeout Hell and Week 4, Day 2 · Cache Invalidation.

What is published: ONDC's retail API contract (1.2.0) says search "will be used to communicate the intent for a full or incremental catalog refresh" and is "always broadcast through the gateway"; ONDC's FAQ adds that the gateway filters seller apps by domain and city. The full catalogue "will be sent directly by the seller NPs to the buyer NP", by city (for grocery, optionally by sub-category), inline or as a time-limited download link; the contract notes that "most buyer apps cache catalogs". For incremental refresh, a buyer app can pull a time window or ask for pushes "at a frequency within a range of 1-30 mins"; changes carry timestamps at provider, location and item level; and a seller app "should push catalog updates… until ACK is received from all buyer NPs". The search intent also declares the buyer app's finder fee (the example is 3%). In December 2025 the Commerce Ministry told the Lok Sabha that seller-side apps make their full catalogues discoverable to all buyer-side apps, while buyer-side apps disclose "key parameters used for sorting or listing search results".

%% title: Two ways to search an open network
flowchart TD
  Q@{ icon: "sd:search", label: "Buyer types<br/>brass puja thali" }
  MODE{"Catalogue cached<br/>for this city?"}
  IDX["Buyer app's own index<br/>answers in milliseconds"]:::core
  BC@{ icon: "sd:gateway", label: "Live search via gateway<br/>to every seller app" }
  WAIT["Collect on_search until ttl<br/>show partial results"]:::hot
  REF["Full refresh daily by city,<br/>incremental pushes 1 to 30 min"]:::service
  Q ==> MODE
  MODE ==>|"yes"| IDX
  MODE -->|"no, or new category"| BC ==> WAIT
  REF -.->|"keeps it fresh"| IDX
  class Q client

• The buyer app owns an indexing pipeline. Catalogue refreshes are its ingestion: Week 7's pipeline, except the documents arrive as signed callbacks from a hundred companies.
• Order by the seller's timestamps, not by arrival. A full refresh ingested from 8:00 to 9:00 can race with pushes from 8:30. Keep the latest event timestamp per item; ignore anything older.
• Absence isn't deletion. Disabling a provider, a store or an item is an explicit message.
• Stock in the cache is a hint. The seller app's /on_select is authoritative, and it pushes stock-outs in its next incremental refresh.
• Live search is for gaps. A new city, an uncached category, a ride: broadcast, collect until ttl, show partial results. The slow seller app loses its slot, not the buyer's patience.
• The seller app runs pub–sub too. With 25 subscribed buyer apps, it aggregates changes once and fans them out 25 times, with ACKs and retries.

# buyer_app/catalog_ingest.py

"""
Ingesting full and incremental catalogue refreshes (illustrative). Each item update
carries the seller's event timestamp; the cache keeps the latest per item, so a slow
full refresh can't overwrite newer incremental changes. Providers are disabled only
by an explicit message, never because a response didn't arrive.
"""


def apply_full_refresh(cache, bpp_id: str, provider: dict, as_of: str) -> None:
    pid = (bpp_id, provider["id"])
    seen = set()
    for item in provider["items"]:
        key = pid + (item["id"],)
        seen.add(key)
        if cache.item_ts(key) is None or cache.item_ts(key) <= as_of:
            cache.put_item(key, item, ts=as_of)
    for key in cache.items_of(pid):                  # items this provider no longer lists
        if key not in seen and cache.item_ts(key) <= as_of:
            cache.disable_item(key, ts=as_of)        # only for providers that DID respond


def apply_incremental(cache, bpp_id: str, provider: dict) -> None:
    pid = (bpp_id, provider["id"])
    if provider.get("disabled"):                     # explicit: the only way a provider goes away
        cache.disable_provider(pid, ts=provider["time"]["timestamp"])
        return
    for item in provider.get("items", []):
        key, ts = pid + (item["id"],), item["time"]["timestamp"]
        if cache.item_ts(key) is None or ts > cache.item_ts(key):
            cache.put_item(key, item, ts=ts)         # newer wins; older pushes are ignored

Deep Dive 3: One Order, Two Databases (Week 2 Concepts: Idempotency; Week 5: Saga Pattern; Week 3: Transactional Outbox)#

This builds on Week 2, Day 2 · Idempotency in Practice, Week 5, Day 2 · Saga Pattern and Week 3, Day 2 · Transactional Outbox.

What is published: ONDC's retail contract spells out "Rules for order confirmation". /confirm and /on_confirm "should be idempotent", and the buyer app "will create the order id which will be unique across the network". On a valid /confirm, the seller app ACKs and "creates order (preferably with internal state to indicate order is being processed), but shouldn't forward to merchant". A validation failure is NACKed with 31002 and the buyer app cancels with reason code 999; after a retriable error (31001) or silence, the buyer app retries, with "a cap for no of attempts over specific duration", then cancels with 999. Once the buyer app ACKs /on_confirm, "SNP forwards order to merchant"; if the buyer app NACKs it (23002) or stays silent past the seller app's retries, the seller app cancels with 998, and meanwhile answers other calls with error 31003, "order processing in progress". Stale messages, older than one already processed for the same transaction_id and message_id, can be NACKed (20002 or 30022). ONDC's FAQ adds that when a cart spans several seller apps and one /confirm fails, "all associated orders in that transaction_id must be cancelled".

%% title: An order on both sides, or on neither
stateDiagram-v2
  [*] --> CONFIRM_SENT: buyer app creates order id, sends confirm
  CONFIRM_SENT --> HELD_AT_SELLER: seller ACKs, order held
  CONFIRM_SENT --> CANCELLED_999: NACK 31002 or no answer after retries
  HELD_AT_SELLER --> ACCEPTED: on_confirm ACKed, released to shop
  HELD_AT_SELLER --> CANCELLED_998: on_confirm NACKed or unanswered
  ACCEPTED --> IN_PROGRESS: packed, picked up
  IN_PROGRESS --> COMPLETED: delivered
  ACCEPTED --> CANCELLED: cancel or force cancel
  IN_PROGRESS --> CANCELLED: RTO initiated
  COMPLETED --> [*]
  CANCELLED_999 --> [*]
  CANCELLED_998 --> [*]
  CANCELLED --> [*]
  class COMPLETED ok
  class CANCELLED_999 bad
  class CANCELLED_998 bad
  class HELD_AT_SELLER queue

• The buyer app owns the id; the seller app owns the state. One side names the order so retries collide; the other is the truth about fulfilment.
• Hold, then release. The ACK to /confirm means "recorded", not "packing". Release to the shop only after the buyer app acknowledges /on_confirm.
• Every failure has one terminal answer. No ACK → 999 by the buyer app; unacknowledged /on_confirm → 998 by the seller app. Both reach "cancelled" without talking: a saga whose compensations are written in the protocol.
• An outbox per edge. The order row and its pending /on_confirm commit in one local transaction; a sender retries until ACKed. A crash between "saved" and "sent" can't lose a callback.
• Terminal means frozen. ONDC's contract freezes an order at "Completed" or "Cancelled", except returns within the window, each a new fulfillment.
• Cancellation has a fallback. If the seller app doesn't answer /cancel in time, the buyer app sends a "force" cancel; if that's ignored too, an IGM issue's resolution produces the /on_cancel. Fees follow terms published in /on_init.

# seller_app/confirm.py

"""
Handling /confirm at the seller app (illustrative). The order is created once per
network order id, held until the buyer app ACKs our /on_confirm, and released to the
shop only then. All outgoing callbacks go through an outbox in the same transaction.
"""

RETRY_WINDOW_S = 120          # our cap; ONDC leaves the cap to each participant


def on_confirm_request(db, msg) -> dict:
    ctx, order = msg["context"], msg["message"]["order"]
    key = (ctx["bap_id"], order["id"])                          # network-unique order id
    existing = db.orders.get(key)
    if existing:                                                # a retry: same order, same answer
        return {"ack": "ACK"}
    if db.seen_newer(ctx["transaction_id"], ctx["message_id"], ctx["timestamp"]):
        return {"nack": "30022"}                                # stale request
    problem = validate(db, order)                               # quote, stock, terms match on_init
    if problem:
        return {"nack": "31002", "message": problem}            # buyer app cancels with 999
    with db.tx():
        db.orders.insert(key, order, state="HELD", txn=ctx["transaction_id"])
        db.stock.reserve(order["items"], ref=key)
        db.outbox.add(to=ctx["bap_uri"], action="on_confirm",
                      body=build_on_confirm(order, state="Accepted"), ref=key)
    return {"ack": "ACK"}


def on_outbox_result(db, ref, acked: bool, age_s: float) -> None:
    if acked:
        db.orders.update(ref, state="Accepted")
        release_to_merchant(ref)                                # only now does Rehana see it
    elif age_s > RETRY_WINDOW_S:
        with db.tx():
            db.orders.update(ref, state="Cancelled", reason="998")
            db.stock.release(ref=ref)
            db.outbox.add(action="on_cancel", body=cancel_body(ref, "998"), ref=ref)

Deep Dive 4: Logistics Is Just Another Participant (Week 5 Concepts: Saga Orchestration; Week 3: Dead Letters)#

This builds on Week 5, Day 3 · Saga Orchestration and Week 3, Day 4 · Dead Letters and Poison Pills.

What is published: ONDC's FAQ describes the "cascaded" flow: "once the retail buyer builds a cart (in /select call), the seller app starts searching for logistics service providers… Logistics buyer which is also the retail seller then goes ahead with one of the LSP and cascades back the delivery charges in /on_select of the retail contract." On retail /init it initialises the logistics order, "from then on, all subsequent calls are cascaded". If the provider delays pickup or cancels, the logistics buyer can cancel and cascade it back, or "search for another LSP"; in a non-cascaded flow the seller app bears any delivery cost above its estimate. The retail contract defines RTO: a logistics /on_cancel with an RTO reason code "will initiate RTO" and a cascaded retail /on_cancel with a new RTO fulfillment. ONDC's "Harmonizing statuses" note adds pickup and delivery confirmation codes (an AWB number or OTP). At network scale, ONDC reported 50,000+ delivery executives in 250+ cities, and a first-in, first-out model matching the first-ready order with the first-arriving rider that reached 25% of logistics orders and cut average pickup times from 15 minutes to under 6 (FY 2025–26).

%% title: One retail order, two linked transactions, one orchestrator in the middle
sequenceDiagram
  autonumber
  participant B as Buyer app
  participant S as Seller app · orchestrator
  participant L1 as Logistics app 1
  participant L2 as Logistics app 2
  B->>S: confirm O-77
  S->>L1: logistics confirm, linked to O-77
  S->>B: on_confirm Accepted
  L1->>S: on_cancel · no rider
  alt another provider available
    S->>L2: logistics search, init, confirm
    S->>B: on_status · new pickup time
    L2->>S: on_status Order-picked-up
    S->>B: on_status Order-picked-up
  else nobody available
    S->>B: on_cancel O-77 · refund per terms
  end
  Note over S,L2: RTO later? logistics on_cancel with RTO code · cascaded retail on_cancel with an RTO fulfillment

• The seller app is the saga orchestrator. It holds both transactions and decides compensations: re-procure, cancel, or RTO. The buyer app never talks to the logistics app.
• Map states with a table. "Agent-assigned", "Order-picked-up", "Out-for-delivery", "Order-delivered" map to retail fulfilment states; a versioned table beats ad hoc translation.
• Forward every change, once. Each logistics on_status becomes one retail on_status through the outbox; the contract says batching "should not be done".
• Dead-letter, don't loop. If the buyer app NACKs a cascaded status for bad schema, resending the same bytes won't help: park it, alert, fix, replay.
• Codes are the handover, and price is fixed at confirm. Pickup and delivery codes are evidence for disputes; any delivery-cost difference is between the seller app and the provider.

# seller_app/logistics_cascade.py

"""
Cascading logistics events into the retail order (illustrative). The seller app maps
each logistics state to the retail fulfillment state, re-procures on a pre-pickup
cancellation, and cascades RTO. Every outgoing callback goes through the outbox.
"""

STATE_MAP = {
    "Agent-assigned": "Agent-assigned", "Order-picked-up": "Order-picked-up",
    "Out-for-delivery": "Out-for-delivery", "Order-delivered": "Order-delivered",
}


def on_logistics_event(db, lo, event) -> None:
    order = db.orders.by_logistics_order(lo.id)
    if event.kind == "status":
        retail_state = STATE_MAP.get(event.state)
        if retail_state and db.fulfilment.advance(order.id, retail_state, at=event.ts):
            db.outbox.add(action="on_status", body=status_body(order, retail_state), ref=order.id)
    elif event.kind == "cancel" and event.is_rto:
        with db.tx():                                           # a valid RTO must be accepted
            db.orders.update(order.id, state="Cancelled", fulfilment="RTO-Initiated")
            db.outbox.add(action="on_cancel", body=rto_body(order, event), ref=order.id)
    elif event.kind == "cancel" and not db.fulfilment.picked_up(order.id):
        alt = reprocure(order, exclude=lo.provider)             # search, init, confirm with another LSP
        if alt:
            db.outbox.add(action="on_status", body=eta_body(order, alt.eta), ref=order.id)
        else:
            with db.tx():
                db.orders.update(order.id, state="Cancelled", reason=event.reason)
                db.outbox.add(action="on_cancel", body=cancel_body(order, event.reason), ref=order.id)

Deep Dive 5: Settlement and Reconciliation Between Companies (Week 3 Concepts: Audit Logs; Week 5: Conflict Resolution; Week 2: Distributed Cron)#

This builds on Week 3, Day 5 · Audit Log System, Week 5, Day 4 · Conflict Resolution and Week 2, Day 5 · Distributed Cron.

What is published: ONDC's Reconciliation and Settlement Framework (RSF 2.0, redesigned in 2024) names a collector (usually the buyer app in retail), a receiver (the seller app) and a settlement agency (ONDC's FAQ names NBBL, an NPCI subsidiary). Participants open an account for ONDC settlement and integrate six APIs: /settle, /on_settle, /report, /on_report, /recon and /on_recon. Both sides send /settle for orders due under the order's terms (settlement_basis, such as delivery, and settlement_window, such as P1D); the cycle runs daily. The NOCS procedural guidelines list the agency's checks (duplicates, participants, settlement accounts, "2-way reconciliation", balance), then a Multilateral Net Settlement Batch uploaded to RBI's RTGS platform at a cut-off, pair-wise payouts to sellers by NEFT, RTGS or IMPS, and /on_settle with a settlement reference per order. RSF 2.0 is "claim based rather than depending solely on Buyer Apps", unmatched orders are rejected, and the agency nets interbank movement while participants submit gross. ONDC's FAQ says retail usually settles after a terminal state, "for example return window plus 7 days", that the time allowed for an on_recon is typically "around 5-7 days", and that unresolved differences go to IGM; refunds after money has moved go through an IGM issue too.

%% title: Money moves only when both sides say the same thing
flowchart TD
  C["Buyer app · collector<br/>/settle: inter-NP 1,000, self 50"]:::core
  R["Seller app · receiver<br/>/settle: inter-NP 1,000, self 200, provider 800"]:::core
  SA@{ icon: "sd:bank", label: "Settlement agency<br/>dedupe, validate, match, balance" }
  M{"Both sides match<br/>for this order?"}
  NET@{ icon: "sd:file", label: "Net batch to RTGS<br/>pair-wise payouts" }
  NS["NOT_SETTLED<br/>recon and on_recon"]:::hot
  IGM@{ icon: "sd:chat", label: "IGM issue<br/>underpaid, overpaid, not paid" }
  SOR@{ icon: "sd:wallet", label: "Rehana's bank<br/>₹800" }
  C ==> SA
  R ==> SA
  SA ==> M
  M ==>|"yes"| NET ==> SOR
  M -->|"no"| NS
  NS -->|"agreed: next cycle"| SA
  NS -.->|"still disputed"| IGM
  class SA store
  class NET store
  class IGM service
  class SOR external

• Two ledgers, one matcher. Each participant keeps an append-only ledger of what each order owes. The agency never decides who's right; it moves money only when they agree.
• Derive amounts from the signed trail. Quote, finder fee, cancellation terms and every /on_update are signed messages both sides hold. Computed from the same trail, settlements agree by construction; mismatches mean bugs, missed updates or tax.
• Settle after the terminal state. Waiting for "Completed" plus the return window makes most refunds a reduction, not a clawback.
• Daily is a cron with a deadline. One idempotent run per cycle before the cut-off: select orders due today, send /settle, persist /on_settle, ask /report if it doesn't arrive.
• Reconcile three ways. Ledger against /on_settle, /on_settle references against the bank statement, and own view against the counterparty's through /recon.
• Gross in, net out. The agency nets every participant's gross orders into one batch, so a hundred participants don't need a hundred bilateral transfers.

# settlement_agency/match.py

"""
Matching collector and receiver instructions for one settlement cycle (illustrative).
Only orders where both sides' amounts agree (or where the collector stayed silent,
as RSF 2.0 provides) are settled, and only if the collector's account can fund them.
"""

from collections import defaultdict


def settle_cycle(claims, submissions, balances):
    """claims: receiver /settle lines; submissions: collector /settle lines; keyed by order id."""
    by_order = {s.order_id: s for s in submissions}
    silent = {c.collector for c in claims} - {s.collector for s in submissions}
    matched, rejected = [], []
    for c in claims:
        s = by_order.get(c.order_id)
        if s is None and c.collector in silent:
            matched.append(c)                                   # claim-based: collector sent nothing
        elif s is None or (s.inter_np, s.collector_amt) != (c.inter_np, c.collector_amt):
            rejected.append((c.order_id, "NOT_SETTLED"))        # → /recon between the two NPs
        else:
            matched.append(c)
    need = defaultdict(int)
    for c in matched:
        need[c.collector] += c.inter_np
    funded = [c for c in matched if balances[c.collector] >= need[c.collector]]
    short = [(c.order_id, "NOT_SETTLED") for c in matched if c not in funded]
    return net_batch(funded), payouts(funded), rejected + short  # → RTGS batch, NEFT/IMPS, /on_settle

Deep Dive 6: Complaints and Health Across Company Lines (Week 10 Concepts: Observability, SLOs; Week 8: Event Ingestion)#

This builds on Week 10, Day 2 · Observability, Week 10, Day 1 · SLIs, SLOs and SLAs and Week 8, Day 1 · Event Ingestion.

What is published: ONDC's complaints page says the buyer app "must provide you with this response within 48 hours", with a ticket number, and the complaint "has to be resolved within 30 days", both "under the E-commerce Rules 2020"; for product or delivery issues, typically, "the seller or Seller App will be responsible for resolving your complaint, while the Buyer App only facilitates". Unresolved complaints go to ONDC's grievance portal, then to "empanelled Online Dispute Resolution service providers" or consumer courts. IGM defines four APIs (issue, on_issue, issue_status, on_issue_status), issue types (issue, grievance, dispute), grievance officers (the interfacing participant's, the counterparty's and the cascaded counterparty's), and expected_response_time and expected_resolution_time fields; ONDC's FAQ adds that in a cascaded complaint "multiple eligible actors (like seller or lsp) can submit various resolution options". ONDC's September 2023 observability white paper has participants push logs "while masking personal identifiable information and business sensitive information", computes metrics like "attempt to confirm rate, fill rate, cancellation rate" and asynchronous response times, sends monthly scorecards, and promises that "at no point, a network participant would have access to sensitive insights pertaining to another network participant". Before going live, participants get their test logs approved, generated with ONDC's Pramaan tool or checked by its log validation utility.

%% title: A complaint crosses three companies, one append-only issue
sequenceDiagram
  autonumber
  participant U as Kolkata buyer
  participant B as Bank's app · BAP
  participant S as Seller app
  participant L as Logistics app
  U->>B: one diya dented, photo
  B-->>U: ticket, resolve by Thursday
  B->>S: issue · item damaged, refs O-91
  S-->>B: ACK
  S->>L: issue cascaded · damage in transit?
  L->>S: on_issue · resolution proposed, refund ₹120
  S->>B: on_issue · refund ₹120 proposed
  B->>U: accept refund?
  U->>B: yes
  B->>S: issue · resolution accepted, close
  Note over B,S: refund flows through settlement · every action appended, signed, never edited

• One issue, append-only actions. Both sides hold copies; changes are appended actions with ids and references. Nobody edits history, so copies converge.
• Timers are data. Response and resolution deadlines are fields every participant's scheduler watches; a miss is an escalation event.
• Route by role. Each grievance officer talks only to its neighbours, as in the order flow.
• Observability is a protocol too. One masked event per protocol message (action, ids, timestamps, outcome) goes to a network collector, which computes the same metrics for everyone and shows each participant only its own.
• Measure the edges. Callback latency, NACKs by code, confirm success, cancellations by reason. In an async network a slow edge is invisible until orders silently die.

# network_obs/edge_metrics.py

"""
Per-participant edge metrics from masked protocol logs (illustrative). Each event has
the sender, receiver, action, transaction and message ids and timestamps; no buyer
data. Callback latency is measured from the request's ACK to its on_ callback.
"""

from statistics import quantiles


def edge_metrics(events, window):
    req, lat, confirms, accepted = {}, [], 0, 0
    for e in events.in_window(window):
        if not e.action.startswith("on_"):
            req[(e.transaction_id, e.message_id)] = e.ts       # request seen
            confirms += e.action == "confirm"
        else:
            t0 = req.pop((e.transaction_id, e.message_id), None)
            if t0 is not None:
                lat.append(e.ts - t0)                           # request → callback
            accepted += e.action == "on_confirm" and e.order_state == "Accepted"
    p95 = quantiles(lat, n=20)[-1] if len(lat) >= 20 else None
    return {"confirm_success": accepted / confirms if confirms else None,
            "callback_p95_s": p95,
            "unanswered": len(req)}                             # requests with no callback yet

Rehana's Dhanteras#

Edge Cases#

Monitoring Dashboard#

SLOs for an Open Network#

The interviewer leans back. "One more."

Summary: Concepts Applied from 10-Week Course#

Why ONDC Matters#

Self-Assessment Checklist#

After studying this case study, you should be able to:

Protocol and trust:

Discovery and orders:

Money and operations:

Sources#

ONDC (ondc.org and ONDC publications):

• Read

  ONDC — Our journey (first order on 29 April 2022 in Bengaluru; Section 8 company in December 2021; 1M+ transactions May 2023, 10M+ August 2023, 100M+ August 2024, 250M+ June 2025, 500M on 25 July 2026; 50+ logistics partners incl. 30+ small fleet operators, June 2026), accessed October 2026: https://ondc.org/pages/about-us.html

• Paper

  ONDC — Building Bharat's Digital Commerce Infrastructure: FY 2025–26 in Focus (218 million transactions in FY 2025–26; 50,000+ delivery executives across 250+ cities; small fleet operators 35% of fulfilled orders; FIFO model 25% of logistics orders, pickup times from 15 to under 6 minutes; 300,000 metro and bus tickets a day), 2026: https://ondc.org/public/assets/newsletters/ondc-fy25-26-in-focus.pdf

• Read

  ONDC — Complaints (buyer app to respond within 48 hours and resolve within 30 days under the E-commerce Rules 2020; escalation to ONDC's grievance portal; ODR), accessed October 2026: https://ondc.org/pages/complaint.html

• Read

  ONDC — Gateway (gateways multicast search requests to seller applications), accessed October 2026: https://ondc.org/pages/gateway.html

• Book

  ONDC — Payment Assurance Program ("not live yet"; refundable security deposit by buyer participants), accessed October 2026: https://ondc.org/pages/payment-assurance-program.html

• Paper

  ONDC — White Paper: Strengthening the Health and Growth of India's E-commerce in an open network (network observability; masked logs; metrics; scorecards; data governance), September 2023: https://ondc-static-website-media.s3.ap-south-1.amazonaws.com/ondc-website-media/downloads/governance-and-policies/ONDC%20-%20White%20Paper%20-%20Strengthening%20the%20Health%20and%20Growth%20of%20India%E2%80%99s%20E-commerce%20in%20an%20open%20network%20-%20Sept%202023.pdf

• Paper

  ONDC — RSF 2.0 (Reconciliation & Settlement Framework) explainer and BRD (roles; claim-based settlement; gross submissions, net movement; edge cases), April–August 2024: https://ondc-static-website-media.s3.ap-south-1.amazonaws.com/res/daea2fs3n/image/upload/ondc-website/files/esf_2_0_explainer_and_brd_02_08_24.pdf

• Paper

  ONDC and NBBL — NOCS Procedural Guidelines, version 2.0 draft, 13 November 2024 (settlement steps; validations; Multilateral Net Settlement Batch on RBI RTGS; Process 1 and 2 payouts; /on_settle references): https://ondc-static-website-media.s3.ap-south-1.amazonaws.com/ondc-website-media/downloads/resource/nocs_procedural_guidelines.pdf

• Read

  ONDC — Reconciliation & Settlement Framework page (archived 9 June 2026): https://web.archive.org/web/20260609102854/https://resources.ondc.org/reconsiliationandsettlementframework

ONDC protocol and developer documentation (github.com/ONDC-Official):

• Docs

  developer-docs — Signing and verification (every request/callback pair a "contract"; BLAKE-512 digest; Ed25519; keyId format; X-Gateway-Authorization; NACK when no valid key): https://github.com/ONDC-Official/developer-docs/blob/main/registry/signing-verification.md

• Docs

  developer-docs — Onboarding of Participants (FQDN, SSL and OCSP; Ed25519 and X25519 key pairs; site verification; /on_subscribe challenge; /lookup; recommended registry rate limits): https://github.com/ONDC-Official/developer-docs/blob/main/registry/Onboarding%20of%20Participants.md

• Docs

  developer-docs — Auth header signing and verification (hash the raw payload; HTTP 401 on failure): https://github.com/ONDC-Official/developer-docs/blob/main/protocol-network-extension/Auth%20Header%20-%20signing%20and%20verification.md

• Docs

  ONDC — Retail API contract 1.2.0 (full and incremental catalogue refresh; catalogue caching; finder fee in search; rules for order confirmation, error codes 31001, 31002, 31003, 23001, 23002, 20002, 30022 and reason codes 998, 999; terminal states; force cancellation; RTO), linked from: https://github.com/ONDC-Official/developer-docs/blob/main/protocol-network-extension/api-contracts/retail/All%20RET%20Domains.md

• Docs

  ONDC-FAQs — Technical architecture, registry, logistics, RSF, IGM, getting started and network observability FAQs (gateway multicasts and doesn't return responses; only discovery via gateway; collected_by; transaction_id and message_id; ttl; ±10 s timestamps; cascaded logistics; RSF APIs, example amounts, daily cycle, "return window plus 7 days", on_recon TTL around 5–7 days; multiple resolution options in a cascaded complaint; both NPs push observability logs; Pramaan and log validation): https://github.com/ONDC-Official/ONDC-FAQs

• Book

  ONDC-Protocol-Specs — Payment and Settlement Protocol v0.6 draft (collection by buyer app, seller app or logistics agent for COD; withholding amount) and Harmonizing statuses in cascaded retail & logistics transactions (pickup and delivery confirmation codes), 2022: https://github.com/ONDC-Official/ONDC-Protocol-Specs

• Docs

  ONDC-NTS-Specifications — IGM release (issue, on_issue, issue_status, on_issue_status): https://github.com/ONDC-Official/ONDC-NTS-Specifications

• Read

  protocol-network-extension — IGM enumerations (issue types, categories, GRO types, statuses): https://github.com/ONDC-Official/protocol-network-extension/tree/main/enums/igm

Beckn protocol:

• Docs

  Beckn Protocol — BECKN-RFC-003, Beckn Protocol Communication (server-to-server, asynchronous; ACK then on_ callback; gateway multicast; multiple on_status), updated 2 July 2024: https://github.com/beckn/protocol-specifications/blob/master/docs/BECKN-003-Beckn-Protocol-Communication-Draft-01.md

Government of India:

• Read

  PIB — ONDC Enables Fair, Transparent and Inclusive E-Commerce… (1.16 lakh+ retail sellers live from 630+ cities and towns as of 9 December 2025; seller apps' full catalogues discoverable to all buyer apps; buyer apps disclose ranking parameters), Lok Sabha written reply, 16 December 2025: https://www.pib.gov.in/PressReleasePage.aspx?PRID=2204664

• Paper

  PIB — Digital Infrastructure in India factsheet (154.4 million+ cumulative orders and 15.4 million+ in December 2024; ~4.9 lakh a day; 7.64 lakh+ sellers and service providers; 616+ cities), February 2025: https://static.pib.gov.in/WriteReadData/specificdocs/documents/2025/feb/doc202521494701.pdf

Reporting:

• Read

  Business Today — ONDC clocks 1.2 million transactions during Diwali week (nearly 1.2 million, 6–13 November 2023; 600+ cities), 17 November 2023: https://www.businesstoday.in/entrepreneurship/start-up/story/ondc-clocks-12-million-transactions-during-diwali-week-406132-2023-11-17

• Read

  Inc42 — Riding On Festive Season, ONDC Logs 14 Mn Transactions In October (5.5 million mobility, 8.4 million non-mobility, October 2024; Inc42 cites a Moneycontrol report quoting an unnamed industry source), 5 November 2024: https://inc42.com/buzz/riding-on-festive-season-ondc-logs-14-mn-transactions-in-october

• Read

  Bloomberg via Al Jazeera — In India, a new platform to curb the powers of Amazon, Flipkart (Nilekani, "hired as an adviser to ONDC last summer", wants to do for e-commerce what UPI did for payments), 28 April 2022: https://www.aljazeera.com/economy/2022/4/28/this-indian-billionaire-is-working-to-curb-the-powers-of-amazon

Design note: the services inside each participant, the code, thresholds, retry windows, dashboards and every number labelled as an assumption or estimate are an illustrative design, not any participant's or ONDC's internal systems. Seller apps per city, searches a second, catalogue sizes, messages per order, the festival peak and the final challenge's figures are assumptions. Rehana Ansari, Ansari Brass Works and her orders are fictional, and the buyer apps in her story are described, not real. ONDC's figures come from publications between 2022 and 2026; ONDC's transaction counts include mobility, transit tickets and financial services as well as retail. Consumer-protection and settlement rules are summarised for engineering context and should be checked against current ONDC policy and law.

Further Reading#

Related systems to study:

• Read

  UPI (Bonus Problem 1 in this series): the open payments network ONDC is often compared to; one atomic transfer through a central switch, where ONDC has no switch in the order path

• Read

  Razorpay (Bonus Problem 18): payments, settlement and reconciliation from a gateway's side

• Read

  Blinkit (Bonus Problem 12) and Swiggy (Bonus Problem 17): one platform owning catalogue, orders and dispatch, the opposite of an unbundled network

• Read

  Flipkart Big Billion Days (Bonus Problem 27): a single marketplace's festival sale, for contrast with a festival on an open network

Foundational concepts (this course):

• Read

  Week 2, Day 1 — Timeout Hell

• Read

  Week 2, Day 2 — Idempotency in Practice

• Read

  Week 2, Day 4 — Webhook Delivery

• Read

  Week 2, Day 5 — Distributed Cron

• Read

  Week 3, Day 2 — Transactional Outbox

• Read

  Week 3, Day 4 — Dead Letters and Poison Pills

• Read

  Week 3, Day 5 — Audit Log System

• Read

  Week 4, Day 2 — Cache Invalidation

• Read

  Week 5, Day 2 — Saga Pattern

• Read

  Week 5, Day 3 — Saga Orchestration

• Read

  Week 5, Day 4 — Conflict Resolution

• Read

  Week 7, Day 2 — Indexing Pipeline

• Read

  Week 8, Day 1 — Event Ingestion

• Read

  Week 9, Day 5 — Security Architecture

• Read

  Week 10, Day 1 — SLIs, SLOs and SLAs

• Read

  Week 10, Day 2 — Observability

"Name the order on one side, keep it on both, release it only when both have heard, and move money only when both books agree."