Pratham Javalkoti.

([email protected])
Intern (Team – Web).

Task: Getting Started with Integration of ONDC.

• ONDC is a network, not an application/website.

• In order to use the network, one has to register with ONDC Registry.
• ONDC uses Async APIs.
• ONDC communication happens from server to server.
• ONDC specification has APIs (/search, /init, /track) and Callback APIs (/on_search,
/on_init, /on_track).
• The participants of the network have to implement the APIs on their backend.
• Buyer apps will call the APIs and will get results on Callback APIs.
• Seller apps will respond to the call received on APIs.

So once all the participants have implemented the APIs on their backends, the applications
can communicate with each other as the servers have common APIs and a common schema
for the payload.

Try it first will be a buyer side app initially. These factors are very important for a buyer side
app:
1. Marketing.
2. Acquire Customers.
3. Payments.
4. Website.
5. Customer Service.
6. Customer Refund.

ONDC depends on beckn protocol.

List of Transaction APIs:
1. search < > on_search.
2. select < > on_select.
3. init < > on_init.
4. confirm < > on_confirm.
5. status < > on_status.
6. track < > on_track.
7. update < > on_update.
8. cancel < > on_cancel.
9. rating < > on_rating.
10.support < > on_support.

Discovery – { search < > on_search }

Order – { select < > on_select, init < > on_init, and confirm < > on_confirm }
Fulfilment – { status < > on_status, track < > on_track, and update < > on_update, cancel <
> on_cancel }
Support – { rating < > on_rating and support < > on_support }

List of Network Infrastructure APIs.

1. search < > on_search.
2. subscribe < > on_subscribe.
3. Lookup.

Structure.
Call: search

Ack
Buyer App Acknowledgment Seller App

Recall: on_search

Ack
Acknowledgment

Gateway is required in case of search < > on_search only. Other all APIs are P2P i.e., Peer
to Peer.

Detailed Information about APIs.

 API Relevance Group

/search Searching a particular product from a buyer side app through a Discover

gateway.

/select Adding a particular searched product into the cart on the buyer side Order

app.

/init Initializing payment. (Paying the money.) Order

/confirm Confirming an order after a payment. Order

/status To get the status of the order. (Ordered, Delivered, and Cancelled.) Fulfilment

/track To track the order. (Details of the product/products in transition.) Fulfilment

/update To update the order status. Fulfilment

/cancel To cancel the order which is confirmed and sent. Fulfilment

/rating Feedback. (Customer → Buyer Side App → Seller Side App) Support

/support Customer Support. Support

The search API uses gateway and the flow is as shown below:
/search → gateway (request to get a list of relevant suppliers) → Registry (Provides a list of
relevant suppliers) → call seller side app → /on_search.
Other all calls and recalls take place directly without any gateway.

API Schema:
Auth Header:
Creating Key Pairs → Auth Header Signing → Auth Header Verification.

Context:

Message.
Error.

Important:
BAP = Backend Application Participant.
BPP = Backend Provider Participant.

/search

Search for services by intent.

Buyer searches for products and services.

https://app.swaggerhub.com/apis/blezDev/ondc-
protocol_api_for_retail_grocery_f_b/1.0.29#/ONDC%20Seller%20App/post_search

Request URL.
https://virtserver.swaggerhub.com/ONDC/ONDC-Protocol-Retail/1.0.29/search

Response Body.
{
"message": {
"ack": {
"status": "ACK"
}
},
"error": {
"type": "CONTEXT-ERROR",
"code": "string",
"path": "string",
"message": "string"
}
}
Response Headers.
access-control-allow-credentials: true
access-control-allow-headers: X-Requested-With,Content-Type,Accept,Origin
access-control-allow-methods: *
access-control-allow-origin: *
cache-control: no-cache
content-encoding: gzip
content-length: 126
content-type: application/json;charset=utf-8
date: Tue,08 Aug 2023 02:53:16 GMT
etag: W/"7e-gO/DcSPnFt9bieLHNwblIinsCBE"
expires: -1
status: 200 OK

Response Time.
1893 ms

/select

Select items from the catalog and build your order.

Buyer selects one or more catalog items.

https://app.swaggerhub.com/apis/blezDev/ondc-
protocol_api_for_retail_grocery_f_b/1.0.29#/ONDC%20Seller%20App/post_select

Request URL.
https://virtserver.swaggerhub.com/ONDC/ONDC-Protocol-Retail/1.0.29/select

Response Body.
{
"message": {
 "ack": {
"status": "ACK"
}
},
"error": {
"type": "CONTEXT-ERROR",
"code": "string",
"path": "string",
"message": "string"
}
}

Response Headers.
access-control-allow-credentials: true
access-control-allow-headers: X-Requested-With,Content-Type,Accept,Origin
access-control-allow-methods: *
access-control-allow-origin: *
cache-control: no-cache
content-encoding: gzip
content-length: 126
content-type: application/json;charset=utf-8
date: Tue,08 Aug 2023 05:14:12 GMT
etag: W/"7e-gO/DcSPnFt9bieLHNwblIinsCBE"
expires: -1
status: 200 OK

Response Time.
708 ms

/init
Initialize an order by providing billing and/or shipping details.
Buyer initializes order checkout.

https://app.swaggerhub.com/apis/blezDev/ondc-
protocol_api_for_retail_grocery_f_b/1.0.29#/ONDC%20Seller%20App/post_init

Request URL.
https://virtserver.swaggerhub.com/ONDC/ONDC-Protocol-Retail/1.0.29/init

Response Body.
{
"message": {
"ack": {
"status": "ACK"
}
},
"error": {
"type": "CONTEXT-ERROR",
"code": "string",
"path": "string",
"message": "string"
}
}

Response Headers.
access-control-allow-credentials: true
access-control-allow-headers: X-Requested-With,Content-Type,Accept,Origin
access-control-allow-methods: *
access-control-allow-origin: *
cache-control: no-cache
content-encoding: gzip
content-length: 126
content-type: application/json;charset=utf-8
date: Tue,08 Aug 2023 05:21:18 GMT
etag: W/"7e-gO/DcSPnFt9bieLHNwblIinsCBE"
expires: -1
status: 200 OK

Request Duration.
2026 ms

/confirm

Initialize an order by providing billing and/or shipping details.

Buyer confirms an order.

https://app.swaggerhub.com/apis/blezDev/ondc-
protocol_api_for_retail_grocery_f_b/1.0.29#/ONDC%20Seller%20App/post_confirm

Request URL.
https://virtserver.swaggerhub.com/ONDC/ONDC-Protocol-Retail/1.0.29/confirm

Response Body.
{
"message": {
"ack": {
"status": "ACK"
}
},
"error": {
"type": "CONTEXT-ERROR",
"code": "string",
"path": "string",
"message": "string"
 }
}

Response Headers.
access-control-allow-credentials: true
access-control-allow-headers: X-Requested-With,Content-Type,Accept,Origin
access-control-allow-methods: *
access-control-allow-origin: *
cache-control: no-cache
content-encoding: gzip
content-length: 126
content-type: application/json;charset=utf-8
date: Tue,08 Aug 2023 05:30:23 GMT
etag: W/"7e-gO/DcSPnFt9bieLHNwblIinsCBE"
expires: -1
status: 200 OK

Request Duration.
1316 ms

/status

Fetch the latest order object.

Buyer checks for status of order.

https://app.swaggerhub.com/apis/blezDev/ondc-
protocol_api_for_retail_grocery_f_b/1.0.29#/ONDC%20Seller%20App/post_status

Response Snippets. (cURL bash)

curl -X 'POST' \
'https://virtserver.swaggerhub.com/ONDC/ONDC-Protocol-Retail/1.0.29/status' \
-H 'accept: application/json' \
 -H 'Content-Type: application/json' \
-d '{
"context": {
"domain": "nic2004:52110",
"country": "string",
"city": "string",
"action": "search",
"core_version": "string",
"bap_id": "string",
"bap_uri": "string",
"bpp_id": "string",
"bpp_uri": "string",
"transaction_id": "string",
"message_id": "string",
"timestamp": "2023-08-08T05:37:33.991Z",
"key": "string",
"ttl": "string"
},
"message": {
"order_id": "string"
}
}'

Request URL.
https://virtserver.swaggerhub.com/ONDC/ONDC-Protocol-Retail/1.0.29/status

Response Body.
{
"message": {
"ack": {
"status": "ACK"
}
 },
"error": {
"type": "CONTEXT-ERROR",
"code": "string",
"path": "string",
"message": "string"
}
}

Response Headers.
access-control-allow-credentials: true
access-control-allow-headers: X-Requested-With,Content-Type,Accept,Origin
access-control-allow-methods: *
access-control-allow-origin: *
cache-control: no-cache
content-encoding: gzip
content-length: 126
content-type: application/json;charset=utf-8
date: Tue,08 Aug 2023 05:37:42 GMT
etag: W/"7e-gO/DcSPnFt9bieLHNwblIinsCBE"
expires: -1
status: 200 OK

Request Duration.
1295 ms

/track

Track an active order.

Buyer tracks fulfillment of an order.
https://app.swaggerhub.com/apis/blezDev/ondc-
protocol_api_for_retail_grocery_f_b/1.0.29#/ONDC%20Seller%20App/post_track

Response Snippets. (cURL bash)

curl -X 'POST' \
'https://virtserver.swaggerhub.com/ONDC/ONDC-Protocol-Retail/1.0.29/track' \
-H 'accept: application/json' \
-H 'Content-Type: application/json' \
-d '{
"context": {
"domain": "nic2004:52110",
"country": "string",
"city": "string",
"action": "search",
"core_version": "string",
"bap_id": "string",
"bap_uri": "string",
"bpp_id": "string",
"bpp_uri": "string",
"transaction_id": "string",
"message_id": "string",
"timestamp": "2023-08-08T05:47:18.798Z",
"key": "string",
"ttl": "string"
},
"message": {
"order_id": "string",
"callback_url": "string"
}
}'

Request URL.
https://virtserver.swaggerhub.com/ONDC/ONDC-Protocol-Retail/1.0.29/track

Response body.
{
"message": {
"ack": {
"status": "ACK"
}
},
"error": {
"type": "CONTEXT-ERROR",
"code": "string",
"path": "string",
"message": "string"
}
}

Response Headers.
access-control-allow-credentials: true
access-control-allow-headers: X-Requested-With,Content-Type,Accept,Origin
access-control-allow-methods: *
access-control-allow-origin: *
cache-control: no-cache
content-encoding: gzip
content-length: 126
content-type: application/json;charset=utf-8
date: Tue,08 Aug 2023 05:47:27 GMT
etag: W/"7e-gO/DcSPnFt9bieLHNwblIinsCBE"
expires: -1
status: 200 OK

Request Duration.
975 ms

/cancle

Cancel an order.
Buyer cancels an order.

https://app.swaggerhub.com/apis/blezDev/ondc-
protocol_api_for_retail_grocery_f_b/1.0.29#/ONDC%20Seller%20App/post_cancel

Response Snippet. (cURL bash)

curl -X 'POST' \
'https://virtserver.swaggerhub.com/ONDC/ONDC-Protocol-Retail/1.0.29/cancel' \
-H 'accept: application/json' \
-H 'Content-Type: application/json' \
-d '{
"context": {
"domain": "nic2004:52110",
"country": "string",
"city": "string",
"action": "search",
"core_version": "string",
"bap_id": "string",
"bap_uri": "string",
"bpp_id": "string",
"bpp_uri": "string",
"transaction_id": "string",
"message_id": "string",
"timestamp": "2023-08-08T05:57:01.648Z",
"key": "string",
"ttl": "string"
},
 "message": {
"order_id": "string",
"cancellation_reason_id": "string",
"descriptor": {
"name": "string",
"code": "string",
"symbol": "string",
"short_desc": "string",
"long_desc": "string",
"images": [
"string"
],
"audio": "string",
"3d_render": "string"
}
}
}'

Request URL.
https://virtserver.swaggerhub.com/ONDC/ONDC-Protocol-Retail/1.0.29/cancel

Response Body.
{
"message": {
"ack": {
"status": "ACK"
}
},
"error": {
"type": "CONTEXT-ERROR",
"code": "string",
"path": "string",
 "message": "string"
}
}

Response Headers.
access-control-allow-credentials: true
access-control-allow-headers: X-Requested-With,Content-Type,Accept,Origin
access-control-allow-methods: *
access-control-allow-origin: *
cache-control: no-cache
content-encoding: gzip
content-length: 126
content-type: application/json;charset=utf-8
date: Tue,08 Aug 2023 05:57:09 GMT
etag: W/"7e-gO/DcSPnFt9bieLHNwblIinsCBE"
expires: -1
status: 200 OK

Request Duration.
966 ms

/update

Update an order.
Buyer updates an order.

https://app.swaggerhub.com/apis/blezDev/ondc-
protocol_api_for_retail_grocery_f_b/1.0.29#/ONDC%20Seller%20App/post_update

Request URL.
https://virtserver.swaggerhub.com/ONDC/ONDC-Protocol-Retail/1.0.29/update
Response Body.
{
"message": {
"ack": {
"status": "ACK"
}
},
"error": {
"type": "CONTEXT-ERROR",
"code": "string",
"path": "string",
"message": "string"
}
}

Response Headers.
access-control-allow-credentials: true
access-control-allow-headers: X-Requested-With,Content-Type,Accept,Origin
access-control-allow-methods: *
access-control-allow-origin: *
cache-control: no-cache
content-encoding: gzip
content-length: 126
content-type: application/json;charset=utf-8
date: Tue,08 Aug 2023 06:03:39 GMT
etag: W/"7e-gO/DcSPnFt9bieLHNwblIinsCBE"
expires: -1
status: 200 OK

Request Duration.
1356 ms
/rating

Provide feedback on a service.

Buyer rates for one or more rating categories.

https://app.swaggerhub.com/apis/blezDev/ondc-
protocol_api_for_retail_grocery_f_b/1.0.29#/ONDC%20Seller%20App/post_rating

Response Snippet. (cURL bash)

curl -X 'POST' \
'https://virtserver.swaggerhub.com/ONDC/ONDC-Protocol-Retail/1.0.29/rating' \
-H 'accept: application/json' \
-H 'Content-Type: application/json' \
-d '{
"context": {
"domain": "nic2004:52110",
"country": "string",
"city": "string",
"action": "search",
"core_version": "string",
"bap_id": "string",
"bap_uri": "string",
"bpp_id": "string",
"bpp_uri": "string",
"transaction_id": "string",
"message_id": "string",
"timestamp": "2023-08-08T06:07:56.583Z",
"key": "string",
"ttl": "string"
},
"message": {
"rating_category": "string",
 "id": "string",
"value": 5,
"feedback_form": [
{
"id": "string",
"parent_id": "string",
"question": "string",
"answer": "string",
"answer_type": "radio"
}
],
"feedback_id": "string"
}
}'

Request URL.
https://virtserver.swaggerhub.com/ONDC/ONDC-Protocol-Retail/1.0.29/rating

Response Body.
{
"message": {
"ack": {
"status": "ACK"
}
},
"error": {
"type": "CONTEXT-ERROR",
"code": "string",
"path": "string",
"message": "string"
}
}
Response Headers.
access-control-allow-credentials: true
access-control-allow-headers: X-Requested-With,Content-Type,Accept,Origin
access-control-allow-methods: *
access-control-allow-origin: *
cache-control: no-cache
content-encoding: gzip
content-length: 126
content-type: application/json;charset=utf-8
date: Tue,08 Aug 2023 06:08:04 GMT
etag: W/"7e-gO/DcSPnFt9bieLHNwblIinsCBE"
expires: -1
status: 200 OK

Request Duration.
1031 ms

/support

Contact support.
Buyer searches for Support Contact details.

https://app.swaggerhub.com/apis/blezDev/ondc-
protocol_api_for_retail_grocery_f_b/1.0.29#/ONDC%20Seller%20App/post_support

Response Snippet. (cURL bash)

curl -X 'POST' \
'https://virtserver.swaggerhub.com/ONDC/ONDC-Protocol-Retail/1.0.29/support' \
-H 'accept: application/json' \
-H 'Content-Type: application/json' \
-d '{
 "context": {
"domain": "nic2004:52110",
"country": "string",
"city": "string",
"action": "search",
"core_version": "string",
"bap_id": "string",
"bap_uri": "string",
"bpp_id": "string",
"bpp_uri": "string",
"transaction_id": "string",
"message_id": "string",
"timestamp": "2023-08-08T06:13:09.168Z",
"key": "string",
"ttl": "string"
},
"message": {
"ref_id": "string"
}
}'

Request URL.
https://virtserver.swaggerhub.com/ONDC/ONDC-Protocol-Retail/1.0.29/support

Response Body.
{
"message": {
"ack": {
"status": "ACK"
}
},
"error": {
 "type": "CONTEXT-ERROR",
"code": "string",
"path": "string",
"message": "string"
}
}

Response Headers.
access-control-allow-credentials: true
access-control-allow-headers: X-Requested-With,Content-Type,Accept,Origin
access-control-allow-methods: *
access-control-allow-origin: *
cache-control: no-cache
content-encoding: gzip
content-length: 126
content-type: application/json;charset=utf-8
date: Tue,08 Aug 2023 06:13:16 GMT
etag: W/"7e-gO/DcSPnFt9bieLHNwblIinsCBE"
expires: -1
status: 200 OK

Request Duration.
1007 ms

Reference: https://app.swaggerhub.com/apis/blezDev/ondc-
protocol_api_for_retail_grocery_f_b/1.0.29#/info