Integrate with ONDC — A comprehensive guide about technical APIs
What is ONDC
ONDC is an initiative by the government aimed at implementing and promoting open networks for the exchange of goods and services across the board, with a focus on small and local businesses. Enough!! More info is a Google Search away, please suit yourself.
Why is this article relevant?
I have implemented ONDC at my current organization, and that information being public invites a lot of people asking questions on how to get started quickly with ONDC. To be honest, ONDC is not the most straightforward implementation you will get🥲. This article lists down and explains everything you need to get onboarded without the hassle of running around people to get things in place.
Get started with the Integration
Getting on-boarded to the ONDC framework is where most of the developers struggle. Let me simplify this, to begin with the onboarding, we have to subscribe to a respective ONDC environment. There are 3 ONDC environments: staging, preprod and production. Each environment has its own set of nuances and markers to be completed:
1- Creating DNS
2- Whitelisting
3- Creating public-private key pairs
4- Nginx setup
5- Setting up your service/application
6- Calling the subscribe API
7- ONDC checks Site-verification.html
8- Subscription Verification
Before we start, I will be using this repo https://github.com/yashb042/ondc_demo_app for the complete E2E setup, with the steps mentioned to start up the application. (Please ️⭐️Star⭐️ the repo as well). Even if you don’t know how Golang works, basic knowledge of Docker can also lead you to set up the application easily in under a minute.
Creating DNS (Domain Name Server)
ONDC network requires your application to be exposed to the internet, via a domain name. For 3 environments, there will be 3 domains you have to create. The naming of the domain can be anything, in this example, I will be using ondc-buyer-staging-app.yash.com
(Replace yash with your company name, ex : ondc-buyer-staging-app.mycompany.com)
The domain name should have TLS enabled, only https:// endpoints are allowed. The final URL of your server would look like this:
https://ondc-buyer-staging-app.yash.com
This domain should be mapped to your machine where you will be hosting the application. Ask your devOps team to do that. The DNS should allow all traffic from https and redirect to port 80 (mentioned in the nginx file below).
Whitelisting
Whitelisting in a manual process of developers filling an ONDC Google form to allow traffic from their created DNS server to be accepted by the ONDC servers.
Go to this link (if it gets updated in future, you will find it on the github repo link mentioned in the references) — https://docs.google.com/forms/d/1k5k-N2JW4azLsdkJVbWjlsW549Nz5tUatYozSmJERQk/viewform?edit_requested=true
The main thing to note in the form is to select a Domain specified by ONDC, with the options relating to e-Commerce, Travel, Agriculture. I have selected ONDC:TRV11 [Travel Domain] for the demo.
The ONDC team usually takes 24–48 hours to whitelist the domain, and you will get updates on the email_id you have mentioned in the form.
Subscriber ID is the unique identifier for your application.
Creating public-private key pairs
Once you are done with the whitelisting, you can start with creating the public-private key pairs to act as API request authenticators. You will be creating 2 pairs of public-private key pairs, so a total of 4 keys (2 public keys and 2 private keys).
In the repo provided, you can find a working code which you can use to instantly generate the 2 key-pairs. Go through the README.md file of this repo, to see how you can generate your public-private key pairs.
Nginx setup
Once your application is running on a certain port, you need to map the newly created DNS with the port your application is running on. We use nginx for this, to install nginx on your EC2 instance/machine, follow this link https://www.nginx.com/blog/setting-up-nginx/
Following is a standard nginx configuration, you can use to redirect the traffic. The configuration listens to port 80 from your Load Balancer and redirects it to port 8080 of your machine.
server {
listen 80;
server_nameondc-buyer-staging-app.yash.com;
underscores_in_headers on;
location / {
proxy_pass http://localhost:8080;
proxy_connect_timeout 300;
proxy_send_timeout 300;
proxy_read_timeout 300;
send_timeout 300;
}
}Setting up your service/application
Go to the following Github link, clone the repo and you can run the service either using an IDE or using Docker (preferred). Before you start running the application, you have to edit the staging.config.yaml file with properties of your buyer app (more details in the README.md of the repo). Most of the properties are self-explanatory, only mentioning the ones which are not so evident -
buyerAppUrl - Endpoint of your DNS (beware of the slash)
buyerAppUri - you can keep it as '/'
gatewayUrl - https://staging.gateway.proteantech.in
ondcEncryptionPublicKey - MCowBQYDK2VuAyEAduMuZgmtpjdCuxv+Nc49K0cB6tL/Dj3HZetvVN7ZekM=
signingPrivateKey - generated above
signingPublicKey - generated above
privateKeyCrypto - generated above
publicKeyCrypto - generated above
registryUrl - https://staging.registry.ondc.org
subscriberId - used in the whitelisting form
networkParticipantDomain - used in the whitelisting form
networkParticipantType - buyerApp/sellerApp(used in the whitelisting form)
subscribeUniqueId - random UUID (but keep it with you)
requestId - random UUID (only needed for subscribe)Calling the subscribe API
After the above steps are done, it’s time to do a very simple thing, subscribing to ONDC. For this —
- From Postman, you have to hit the /ondc_subscribe EP (hosted by your application, present in the demo app shared) which in turn calls the ONDC /subscribe API.
- ONDC works in async fashion, where when you call the /subscribe EP, you will instantly get a response, be it HTTP_200 or HTTP_400.
- Then, after a few milliseconds, ONDC servers will call your DNS (in turn your application connected to the DNS via Nginx), at the endpoint hosted by your service’s on_subscribe.
1. Request from Postman to your application
curl - location - request POST 'http://localhost:8080/ondc_subscribe' - data ''2. Request from your application to ONDC /subscribe EP (sent by your microservice) :
URL — https://staging.registry.ondc.org/subscribe
The parameters from this request should be auto-populated using the staging.config.yaml file you added in the service setting up part.
The response you get from ONDC is simply an ACK response if everything was rightly configured in the staging.config.yaml
3. The ONDC request to your service’s /on_subscribe EP will look like this :
The ONDC request looks like this :
{
"subscriber_id" : "ondc-buyer-staging-app.yash.com",
"challenge" : "esgjaijfgeoskaraeowkrelakrela"
}The response to this request you have to send to ONDC, send the decrypted_challenge_string.
{
"answer": "DECRYPTED_DATA"
}If the decryption at your end worked fine, you would have successfully subscribed to the ONDC staging environment.
ONDC checks Site-verification.html
When you hit the /subscribe EP of ONDC, ONDC will try to call one more hosted EP by your service with URI as /ondc-site-verification.html. If you have setup the repo properly, the endpoint should automatically be available to you here -
https://ondc-buyer-staging-app.yash.com/ondc-site-verification.html
(Replace ondc-buyer-staging-app.yash.com with your DNS name)
You don’t have to do anything here, just check yourself by opening this URL in a browser, go to the Inspect element and see whether a key is being generated in the <head> tag of HTML like this:
Subscription Verification
You can verify whether you have subscribed properly to ONDC or not, by hitting the following EP, with your details.
curl - location 'https://staging.registry.ondc.org/lookup' \
- header 'Content-Type: application/json' \
- data '{
"subscriber_id": "ondc-buyer-staging-app.yash.com",
"ukId": "{{UNIQUE_KEY_ID}}"
}'UNIQUE_KEY_ID is the one you used in the /subscribe request.
You should get a response like this :
[
{
"subscriber_id": "ondc-buyer-staging-app.yash.com",
"status": "SUBSCRIBED",
"ukId": "{{UNIQUE_KEY_ID}}",
"subscriber_url": "https://ondc-buyer-staging-app.yash.com/",
"country": "IND",
"domain": "ONDC:TRV11",
"valid_from": "2024–04–18T18:27:54.101Z",
"valid_until": "2030–07–08T06:27:54.101Z",
"type": "BAP",
"signing_public_key": "EWQH40vEJB/QiGCaLb97P5AaiCE7WFqKVBGe8Qtwsr0=",
"encr_public_key": "MCowBQYDK2AFDyEAtexpJPC5LYuGHgbRuyZkiIRTUvoAaTzsAh3rbaWPrz8=",
"created": "2024–04–19T10:23:41.533Z",
"updated": "2024–04–19T10:23:41.533Z",
"br_id": "{{UNIQUE_KEY_ID}}",
"city": "*"
}
]Congratulations, you have successfully done within 1 day, what took me more than a week of following up from ONDC team and figuring out everything.
Subscribing in Higher environments
Once you’re subscribed to the staging environment, the process for subscribing to higher environments mostly stays the same. There will be a few more checks presented by the ONDC team to you, which you will get to know once you subscribe to the staging environment. Once you’re onboarded perfectly to the staging environment, ONDC will start involving more and more with you, and help you along the way. To keep the article short, I will be skipping the next steps for higher environments.
Let me know if you want to know the steps for higher environments, and I will write a blog for that as well.
References
Q&A page (to ask questions in the community)
https://github.com/ONDC-Official/developer-docs/discussions/31
Tech quickstart guide
https://github.com/ONDC-Official/ONDC-Protocol-Specs/blob/master/protocol-specifications/docs/draft/Tech%20Quickstart%20Guide.md
Protocol Specifications
https://github.com/beckn/protocol-specifications/tree/b028fa3b8a5ea3c9be890ae673fa4472a4e78355
Let me know if you struggle with any of the mentioned steps, will try to help.
About the Author :
Yash Bansal is an Associate Principal Engineer at redBus. More info about him can be found on his LinkedIn profile. The author can also be connected with at https://topmate.io/yashbansal042
