What is ONDC

The Open Network for Digital Commerce (ONDC) is a government initiative designed to create and promote open networks for the exchange of goods and services, particularly benefiting small and local enterprises. For more detailed information, a quick Google search will suffice.

Why This Guide is Important

Having successfully implemented ONDC in my organization, I've received numerous inquiries about how to quickly get started. To be candid, the implementation process for ONDC can be quite complex. This guide aims to provide a comprehensive overview and simplify the onboarding process, ensuring you won’t have to navigate through endless consultations.

Getting Started with Integration

The onboarding process to the ONDC framework is where many developers face challenges. To initiate this process, you must subscribe to a specific ONDC environment. There are three environments available: staging, pre-production, and production. Each environment has distinct requirements and steps to complete:

1. Setting up DNS
2. Whitelisting
3. Generating public-private key pairs
4. Configuring Nginx
5. Preparing your service/application
6. Invoking the subscribe API
7. Conducting site verification with ONDC
8. Verifying subscription

Before we proceed, I will utilize the repository at https://github.com/yashb042/ondc_demo_app for a complete end-to-end setup, with detailed steps to launch the application. (Feel free to star the repository as well). You don't need extensive knowledge of Golang; even a basic understanding of Docker can help you set up the application in under a minute.

Creating DNS (Domain Name Server)

For the ONDC network, your application must be accessible via a domain name. This means you will need to create three separate domains for the three environments. The domain naming can be flexible; for illustration, I will use ondc-buyer-staging-app.yash.com (replace "yash" with your company's name, e.g., ondc-buyer-staging-app.mycompany.com).

Ensure that the domain has TLS enabled, as only HTTPS endpoints are permitted. The final URL for your server will resemble:

https://ondc-buyer-staging-app.yash.com

This domain should point to the machine where your application will be hosted. Coordinate with your DevOps team to set this up. The DNS should accept all traffic from HTTPS and redirect to port 80 (as specified in the Nginx configuration below).

Whitelisting

Whitelisting involves a manual process where developers fill out an ONDC Google form to allow traffic from their designated DNS server to be accepted by the ONDC servers.

You can access the form here (if this link changes in the future, it will be available in the GitHub repository mentioned in the references): https://docs.google.com/forms/d/1k5k-N2JW4azLsdkJVbWjlsW549Nz5tUatYozSmJERQk/viewform?edit_requested=true

When filling out the form, ensure you select a domain specified by ONDC, with options related to e-Commerce, Travel, Agriculture. For this demo, I selected ONDC:TRV11 [Travel Domain].

Typically, the ONDC team will take 24–48 hours to process the whitelisting request, and you will receive updates at the email address provided in the form.

The Subscriber ID is your application’s unique identifier.

Creating Public-Private Key Pairs

After completing the whitelisting process, you can generate public-private key pairs to serve as authenticators for your API requests. You will need to create two pairs, resulting in four keys (two public keys and two private keys).

The provided repository includes functional code to help you quickly generate these key pairs. Refer to the README.md file in the repository for detailed instructions on generating your public-private key pairs.

Nginx Setup

Once your application is running on a designated port, you must map the newly created DNS to the port where your application operates. This is typically accomplished using Nginx. To install Nginx on your EC2 instance/machine, follow this link: https://www.nginx.com/blog/setting-up-nginx/.

Below is a standard Nginx configuration that you can use to redirect traffic. This configuration listens on port 80 from your Load Balancer and forwards it to port 8080 of your machine.

server {

listen 80;

server_name ondc-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

Access the following GitHub link, clone the repository, and you can run the service either through an IDE or using Docker (recommended). Before launching the application, edit the staging.config.yaml file with the properties of your buyer application (more details can be found in the README.md of the repository). Most properties are self-explanatory, but here are a few that may not be as clear:

buyerAppUrl: Endpoint of your DNS (ensure to include a trailing slash)

buyerAppUri: '/' (can remain as is)

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: as used in the whitelisting form

networkParticipantDomain: as used in the whitelisting form

networkParticipantType: buyerApp/sellerApp (as specified in the whitelisting form)

subscribeUniqueId: a random UUID (keep this for your records)

requestId: a random UUID (only needed for the subscribe operation)

Calling the Subscribe API

Once the aforementioned steps are completed, the next task is to subscribe to ONDC. Here’s how to do it:

1. Using Postman, send a request to the ondc_subscribe endpoint (hosted by your application, found in the demo app) which subsequently calls the ONDC subscribe API.
2. ONDC operates asynchronously; when you call the /subscribe endpoint, you will receive an immediate response, whether it’s HTTP_200 or HTTP_400.
3. A few milliseconds later, ONDC servers will reach out to your DNS (and thus your application connected via Nginx) at the endpoint hosted by your service’s on_subscribe.

ONDC Checks Site-verification.html

When you access the subscribe endpoint of ONDC, it will attempt to call another endpoint hosted by your service at ondc-site-verification.html. If the repository is set up correctly, you should be able to access this endpoint at:

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 need to do anything here, simply check by opening this URL in a browser, inspect the elements, and see if a key is generated in the <head> tag of the HTML.

Subscription Verification

To confirm whether you have successfully subscribed to ONDC, send a request to the following endpoint with your details:

curl -X POST 'https://staging.registry.ondc.org/lookup'

-H 'Content-Type: application/json'

-d '{

"subscriber_id": "ondc-buyer-staging-app.yash.com",

"ukId": "{{UNIQUE_KEY_ID}}"

}'

UNIQUE_KEY_ID refers to the one used in your /subscribe request.

You should receive 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 accomplished in one day what took me over a week of follow-ups with the ONDC team to figure out.

Subscribing to Higher Environments

After successfully subscribing to the staging environment, the process for subscribing to higher environments is mostly consistent. However, ONDC may introduce a few additional checks, which you will learn about after your staging subscription. Once you have successfully onboarded to the staging environment, ONDC will increase its collaboration and support.

To keep this guide concise, I won't delve into the next steps for higher environments. If you're interested in those steps, feel free to reach out, and I'll consider drafting a blog post on that topic as well.

References

Q&A page (for community inquiries): 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

Should you encounter difficulties with any of the steps outlined, please don't hesitate to ask for assistance.

About the Author:

Yash Bansal is an Associate Principal Engineer at redBus. More information about him can be found on his LinkedIn profile. You can also connect with the author at https://topmate.io/yashbansal042.