Pic Credit journalsofindia

Open Network for Digital Commerce (ONDC) is an initiative aiming at promoting open networks for all aspects of exchange of goods and services over digital or electronic networks.

Technical workflow
  1. Client(Buyer) — It’s the end user who wants to purchase any products.
  2. Buyer App(BAP) — Its the application (Web App or Mobile App) where Buyer can search for the products they like and buy it. Note while searching for any products you must have to provide your location.
  3. ONDC Gateway — When Buyer search for any products, search request goes from buyer app to ONDC Gateway and ONDC Gateway broadcast that requests to all Seller App present in the registry for specific location.
  4. Seller App (BPP) — This is main application holding all products, sellers, support fulfillment etc. Here seller can add products, manage inventory, generate invoice, shipments etc. Note buyer apps does not have any products, seller sends products to buyer app via ONDC gateway on search request.

 

When any user lands on buyer app to purchase any products then they will not see any products (Except buyer app has done some customization to display static products from top sellers or their own products). Buyer will see two input box one for current location and another for the search. Search can also be of type Product, Provider(Seller) & Category. Here i am going to explain you product search.

Now when user enter their current location and search for any products they want to purchase then buyer app generate ONDC search API Payload which will contain context and message like following

{
  "context":
  {
    "domain":"nic2004:52110",
    "action":"search",
    "country":"IND",
    "city":"std:080",
    "core_version":"1.0.0",
    "bap_id":"ondc.paytm.com",
    "bap_uri":"https://ondc-staging.paytm.com/retail",
    "transaction_id":"3df395a9-c196-4678-a4d1-5eaf4f7df8dc",
    "message_id":"1655281254861",
    "timestamp":"2022-06-15T08:20:54.861Z",
    "ttl": "PT30S"
  },
  "message":
  {
    "intent":
    {
      "item":
      {
        "descriptor":
        {
          "name": "<product name>"
        },
      },
      "fulfillment":
      {
        "type":"Delivery"
        "end": {
          "location": {
            "gps": "12.974002,77.613458",
            "address":
            {
              "area_code": "<current pincode>"
            }
          }
        }
      },
      "payment":
      {
        "@ondc/org/buyer_app_finder_fee_type":"percent",
        "@ondc/org/buyer_app_finder_fee_amount":"3"
      }
    }
  }
}

as you can seen the above search payload, it contains context and message. Context contains all information like

  1. bap_id — its unique id for the buyer app
  2. bap_uri — URL for the buyer app
  3. transaction_id — this is the unique id for each search request and will remain same in overall checkout process.
  4. action — this denote type of action. here since we are searching for products then action is search. In case of order confirmation it will be confirm and so on.
  5. city: this is the city code. You have to map pincode/city name with the city code.

In the message if you can see we have all details related to the particular action. Here if you check in the message we have intent.

  1. Intent contains item details which user wants to search.
  2. Then we have fulfillment, this contains delivery details. For example you want to search product in Bengaluru near your location say in 5 KM radius. Then this details will be useful. If products are not in the range of 5 KM as assumed from your current location then it wont show you as a result in the buyer app.
  3. Next we have payment, this contains buyer app fees, since buyer purchase products from the buyer app so buyer app will also charge seller if user successfully checkout. Not it is up to seller apps to accept this payment term by buyer app. If they don’t agree on the payment term requested by the buyer app then seller will have to send NACK as a response with specific message to the gateway.

Before hitting search request to gateway you have to sign the request payload and then add that signature to the header (Auth header) and then send it to gateway. Note this applies for all kind of outgoing ONDC request. You can refer this document to know how you can implement it in your application.

Now once you hit search request to gateway, Gateway will first verify the auth header which you have sent, by using your public key present in ONDC registry. If header is valid then it will broadcast search request to all seller app in that particular location provided by the user. Note: Gateway also sign header and then only send requests to sellers.

Now once request receive to the seller apps, it will first validate header by using public key of gateway and then it search for products present in their database, if products are found then it will respond with the result by calling callback API for search which is on_search. But before hitting callback api it will have to build payload for the same.

Building Payload for on_search callback API

You can refer this document for building callback API. I am going to explain you few fields that are present in the payload.

  1. bpp/descriptor — It is an aggregator of sellers. Means aggregator is a platform where sellers can register themself to sell their products on ONDC. Here you have to pass few parameters like name, symbol(Logo), descriptions (short/long) etc.
  2. bpp/providers — It contains seller details. Suppose you searched for product coffee, so it is possible that multiple seller can sell coffee. So here you have to pass all sellers who is selling coffee in this bpp/providers array with their store location. Note: You can also pass multiple location of stores of one seller. Here you have to provide all items of this particular seller which is matching particular search. You can also pass fulfillments, which basically contains seller contact details.
  3. bpp/fulfillments — If seller is going to do the order fullfillments then they have to pass Delivery, if neither seller or logistics partner is going to fullfillment then in that case they have to pass pickup.

Once your payload is ready then you have to simply generate auth header as explained earlier and pass it in the header and in the body you have to pass generated payload and send callback POST request to gateway on_search api. If everything is valid then gateway will send this payload to buyer app asynchronously.

How buyer app display search result?

Since search results coming from the gateway are asynchronous it will be really tough to show result on the buyer app UI right? So solve this problem we can use following approaches

  1. Long Polling — It is Half-Duplex meaning that a new request-response cycle is required each time the client wants to communicate something to the server. Here when every we receive any request from the gateway we will save that request to some DB (NoSQL can be prefered) and send that result to client.
  2. WebSockets — It is Full-Duplex meaning both the client and the server can send and receive messages across the channel. So when we receive any request from the gateway we can directly send it to the buyer app without even storing it somewhere.
  3. Firebase(Firestore) — An initial call using the callback you provide creates a document snapshot immediately with the current contents of the single document. Then, each time the contents change, another call updates the document snapshot. With the help of this you can directly get updated content on the buyer app.

Thanks for reading this blog hope you have liked it. If yes then please clap and follow me for more blogs like this. I will be very soon posting next part which will contain select, init and other ONDC APIs.

Did you enjoy this article? If so, get more similar content by subscribing to Decoded, our YouTube channel!. Happy coding.