ONDC integrations

With a normal API, one team owns the contract. With ONDC, buyer apps and seller apps implement a shared specification independently, and you are integrating with however many teams decided to interpret it.

We built gift card integrations as a buyer and as a seller, plus a B2B retail seller for a client. Same spec, three seats at the table, three flavours of “technically compliant but not what we expected”. We had also argued over parts of the gift card taxonomy, which made watching three teams interpret it three ways its own kind of humbling.

You send a search and the answers do not return on that connection. They arrive at a callback endpoint, sometimes from a participant you never called, sometimes late, sometimes twice.

So a broken integration is rarely a stack trace. It is a callback that never came, or one carrying a transaction ID you are not tracking. The fixes are unglamorous: idempotency keys on every handler, defensive parsing of every field, and the raw payload logged before anything touches it.

Every ONDC service we run imports the same shared library. It signs requests, handles the key exchange for encrypted payloads, and wraps registry and category lookups. Keeping that in one package means one place to fix when the network changes the rules, which it does.

Each gift-card brand needs its own denominations, commissions, margins, provider routing, and settlement rules. A manual check before activation took three and a half hours per brand, and misconfigured brands still slipped through. We built a validation engine that checks all of it in about two minutes, and re-runs daily to catch changes on the provider side.

Inside our side of the network, a single transaction could pass through four or five services before reaching anyone else. Request-scoped context keeps the transaction ID attached as it hops between them, so one grep shows the whole path a callback took.