The version history table describes the major changes to the specifications between published versions.
| Version | Authors | Comment |
|---|---|---|
| 0.1 | Ravi Prakash | First draft of core specifications |
- Preface
- Introduction
- Requirements
- Functional Requirements
- Requirements for all modes
- Requirements for BAP mode
- Common Requirements
- Authentication - Key verification
- DOFP functionality
- Sending Request (Transaction API)
- Layer 2 Configuration (Transaction API)
- Core spec compatibility (Transaction API)
- Handling synchronous response (Transaction API)
- Listening to responses (Transaction API)
- Acknowledging responses (Transaction API)
- Client side interface (Transaction API)
- Context (Transaction API)
- Error handling (Transaction API)
- XInput (Transaction API)
- Meta API - Fetching information
- Requirements for BPP Mode
- Common Requirements
- Authentication - Key verification
- Authentication - Verification - Gateway
- DOFP functionality
- Listening to Requests (Transaction API)
- Layer 2 Configuration (Transaction API)
- Core spec compatibility (Transaction API)
- Acknowledging request (Transaction API)
- Sending Responses (Transaction API)
- Handling response acknowledgements (Transaction API)
- Context (Transaction API)
- Responses without corresponding requests
- XInput (Transaction API)
- Error handling (Transaction API)
- Meta API - Listening and returning data
- Requirements for Registry mode
- Requirements for Gateway mode
- Non-Functional Requirements
- Functional Requirements
- Appendices
The purpose of this document is to establish a standardized framework for Beckn-ONIX. By defining common interfaces and components, this document aims to ensure that all Beckn-ONIX distributions and SDKs are interoperable, enabling seamless integration and communication between systems. This standardization is crucial for enhancing consistency and reliability.
A good understanding of the Beckn Protocol and the ecosystem is required to get maximum benefit from this document. Learning resources are provided in the section below to help in this task.
The users of this document are the developers or organizations who want to build a Beckn-ONIX distribution or a Beckn-ONIX SDK.
….
This section provides definitions and explanations of key terms and concepts used in the Beckn-Onix network. Understanding these terms is essential for navigating the functionalities and interactions within the ecosystem.
| Term | Description |
| DOFP Session | An end-to-end transaction workflow consisting of Discovery, Ordering, Fulfillment, and Post-fulfillment (not necessarily in the same sequence), resulting in the execution of a contract between a consumer and a provider. |
| BAP | Beckn Application Platform |
| BPP | Beckn Provider Platform. |
| BG | Beckn Gateway. |
| Registry | Beckn Registry. |
| Specification | A technical document that describes how a system is to be developed to achieve a specific set of objectives or requirements. |
| Ecosystem | An ecosystem is a community of stakeholders that support platforms implementing the specification. Ecosystems can be made up of developers, resellers, customers, software, services, and more. |
| Ecosystem Maturity | The level of readiness of an ecosystem to design, build, and use implementations of the specification. This can range from basic access to internet infrastructure to more advanced features like digital identities, assets, payments, and trust infrastructure. |
| Consumer | A person, or an organization that wants to discover, buy or avail products, services, and/or opportunities. |
| Provider | A person, or an organization that wants to publish, sell, allocate, or provide products, services, and/or opportunities. |
| Intent | A consumer’s desire to purchase, procure, or avail something being offered by a provider. |
| Catalog | A provider’s list of products, services, and opportunities that is made available to consumers. |
Refer to the below resources to get an understanding of the Beckn protocol and Beckn-ONIX. Also refer to the references section of this document for additional resources.
- Beckn Protocol:
- Beckn-Onix:
Today, most online transactions between a consumer and a provider happen via a centralized platform acting as an intermediary. However, not everything on the internet works this way. Emails, WiFi, phone calls, and the World Wide Web, all operate on standard protocols that allow for Peer to Peer communication between machines without the need for a centralized intermediary.
Beckn Protocol fundamentally reimagines how transactions are conducted on the internet today.
Beckn-ONIX envisions becoming the foundational standard for rapidly deploying and integrating Beckn protocol-enabled networks. By offering a robust, secure, and high-performance framework, Beckn-ONIX aims to empower the community to build adaptable, production-ready applications with ease. Much like Apache or Nginx serves as a backbone for HTTP-based systems, Beckn-ONIX aspires to be the go-to standard for creating reliable and scalable Beckn protocol adapters. This vision focuses on accelerating innovation by simplifying network deployment, enabling developers to focus on building the future of decentralized applications.
- A Beckn-ONIX distribution/SDK must allow setting up a new network.
- A Beckn-ONIX distribution/SDK must allow an NP to join an existing network.
- A Beckn-ONIX distribution/SDK must allow merging multiple networks.
- A Beckn-ONIX distribution/SDK must allow configuration of an existing network.
The goal is to accelerate the pace of innovation and encourage focus on driving progress and achieving breakthrough solutions.
A Beckn-ONIX distribution must have at least the following key capabilities:
- Set up and configure open networks within a matter of minutes
- Join existing networks through elaborate SDKs
- Scale effortlessly
- It should be simple and intuitive
This section lists the core requirements of a Beckn-ONIX distribution (sometimes referred to as software). It does not assume any implementation decisions except as required by the Beckn protocol (e.g. Beckn protocol messages are sent over http. So the network participant needs to expose http endpoints in order to receive them). Except those mentioned, all other design aspects can be chosen by the implementers.
The mandatory requirements use the word must. The recommended requirements use the word should and the optional requirements use the word may.
Beckn network defines Network Participants with four main roles. They are
- **BAP (Beckn Application Platform) **- consumer-facing infrastructure which captures consumers’ requests via its UI applications, converts them into beckn-compliant schemas and APIs at the server side, and fires them at the network.
- **BPP (Beckn Provider Platform) **- platforms that maintain an active inventory, one or more catalogs of products and services, implement the supply logic and enable fulfillment of orders. The BPP can be a single provider with a Beckn API implementation or an aggregator of merchants
- Registry - stores detailed information about every network participant and acts as the trust layer of the Beckn network.
- Gateway - are extremely lean and stateless routing servers. Its purpose is to optimize discovery of BPPs by the BAPs by merely matching the context of the search.
A Beckn-ONIX instance can take on any of the four roles of Network participants. We use the term mode in the rest of the document. We describe below (in different sub-sections), requirements common to all modes as well as requirements when operating in one of the modes. If an instance is operating in more than one mode, it should satisfy the requirements of all of those modes it is operating in.
These minimal core requirements do not explain the business logic, application programming interface (except those on Beckn network side defined by the protocol) or user interface that might be required in any consumer side or provider side application. Some of these requirements will be covered in other Beckn-ONIX extended requirement documents.
In the rest of the document, the word Network Participant refers to the Beckn-ONIX installed software instance that is acting as a Network Participant in the Beckn network. So when we say “Network Participant must…”, it effectively means that the “Beckn-ONIX distribution installed software instance must…”
- It must be possible to install the software and configure it to operate in any mode required. The installation must allow
- Creation of a new Beckn network (mostly relevant for the Registry mode)
- Joining an existing Beckn network as a network participant
- Configuring an existing network participant
- Merging two networks (relevant in the Registry mode)
- The installation process should guide the user with intuitive prompts and help setup mandatory configuration such as identity (see below) . The exact process of installation and configuration (whether through wizards, GUI or combination of these explained through a procedure) is left to implementation.
- Software must allow setting Subscriber Id and Subscriber URL of the network participant. This Subscriber Id and Subscriber URL must follow the format defined here. This Subscriber Id and Subscriber URL must be used in messages to identify the network participant. Depending on the role and the message, different names (subscriber_id, bap_id, bpp_id ) are used to refer to these values. Network participant’s Subscriber Id and Subscriber URL must be registered with the Registry. While registering usually, the role (BAP, BPP, BG), the domain in which they transact and the location of the network participant is also set. The exact process(manual/automated) of registration may be defined by registry implementation.
- It must be possible to set private-public key pairs of the Network Participant. The key pairs are associated with a key_id. The format of the key pairs, key_id and other details are documented here. Software may support multiple key-pairs with different key ids.
- Key-Pair generation: The software should support easy generation of private-public key pairs.
- Public key update: The public key of the key-pair must be updated at the registry. This is done using the subscribe endpoint and is documented here.
- Security - Key-Pair refresh: It must be possible for public-private key pair to be updated. The update will involve changing it at the registry using the subscribe endpoint as well as use of the new key in further transactions.
- Any message that is sent on the Beckn network must be hashed and signed with the private key associated with the network participant. This signature must be set as the Authorization header. The process will require subscriber_id, key_id, private key and the message body. The hashing and signing process as well as the format of the Authorization header is documented here.
- Any network participant when it receives a message from another participant must verify the signature to ensure that this is coming from the said participant and the message contents have not been modified. This process involves looking up the public key of the sender in the registry. The lookup endpoint is documented here. The process of verification is documented here.
- Authentication - Verification - Lookup cache: To reduce the load on the Registry, the network participant should use cache with a short expiry for the lookup api results. If the details of the required network participant are in the cache, the registry should not be contacted.
- All network participants must use https for communication towards the Beckn network. This ensures encryption of data in transit.
- Network Participants should support multiple versions of the core protocol.
- Layer 2 Config are machine encoded rules that are released by the network. These rules are an addition to the API rules defined by the core Beckn transaction API specification. Currently Layer 2 configurations are openapi compliant yaml format files similar to Core transaction API specification. The network might release one layer 2 config file for every domain the network participant can transcat in.
The software must provide a way to download and save multiple Layer 2 config released by the network. These layer 2 configurations must be used to enforce network defined rules. For the BAP/BPP mode, this might be validating incoming and outgoing messages as per the rules. - Layer 2 Config - Core version: Layer 2 Config file selection (in cases that involve message validation) should be cognisant of the core version(the value of the version attribute in the context of any message). If there is an available layer 2 config (released by network and downloaded by Network Particpant as specified above), specific to the core version in the message, that file should be used for validation.
- Health check: Network Participants must implement a health check endpoint (/health). When operational, the endpoint must return a 200 HTTP status code. Optionally a body with additional details might be returned as illustrated in this example.
- Observability- Telemetry: Network participants may implement mechanisms to monitor different aspects of execution from an observability standpoint. If implemented, it should follow the Opentelemetry convention.
- All Beckn messages that are sent or received by the Network Participant must be logged. This is recommended for dispute resolution, auditing and troubleshooting. This log should be stored in permanent storage for duration as might be required for potential dispute resolutions at the business level.
- Location: Software must allow location to be set (Country - City). This value must be used when required in the various messages.
- Port: Software should allow configuration of the port where it hosts its application server(endpoints). This allows flexibility in deployment.
- In addition to the Authentication requirements specified in the “Requirements for all modes” section, an on_subscribe endpoint must be made available for the registry to verify the public-key set there. The details are documented here.
- The software operating in the BAP mode must facilitate the consumer side of the commerce transaction workflow including all the four stages of Discovery, Order, Fulfillment and Post fulfillment as described here. The mandatory parts of these requirements are listed below and tagged as “Transaction API”.
- The software should implement or facilitate integration with additional business requirements associated with the transaction relevant to the consumer.
- In BAP mode the software must be able to send the following Transaction APIs (all POST messages) to the Beckn Network (by calling the below endpoints on the BPP or the Gateway (for search). These APIs are part of transaction workflow covering all the four stages of Discovery, Order, Fulfillment and Post fulfillment. The format of the outgoing request is detailed here. The endpoints to call and the contents of the payload that need to be sent are:
- search - search for product or service
- select - send cart
- init - initialize draft order
- confirm - confirm order
- status - get active order
- track - track order
- cancel - cancel order
- update - update order
- rating - provide rating
- support - get support contact details
- Software must ensure that outgoing requests and incoming responses (described below) are compliant with Layer 2 configuration rules as required by the network. The Layer 2 Config file to be used must be decided based on the context of the message (e.g. using the domain and version fields). In case no Layer 2 config file is found for a message, the software must use the matching version of Beckn Core Transaction API Specification to validate the messages.
- The description of the content of the messages provided in the Beckn Core Transaction API Spec must be followed by the software. Some of these attributes which have significant functionality attached, are described below. The Beckn Core Spec should be referred to for authoritative descriptions on all attributes.
- Receivers of Beckn messages will respond back to API calls with ACK(success) / NACK(failure) as described here. The software must handle these suitably with graceful degradation and appropriate handling for failure messages.
- The software in BAP mode must implement the following endpoints (all POST) at its subscriber_url. The formats of the incoming responses are documented here. The endpoints and the content of the payloads are:
- on_search - catalog response to a search request
- on_select - quote for cart/order sent in select
- on_init - draft order with payment terms
- on_confirm - confirmation of order created
- on_status - status of requested order
- on_track - tracking details of requested order
- on_update - updated order
- on_cancel - canceled order
- on_rating - acknowledgement for rating
- on_support - requested support information
- The software must validate the response with the appropriate Layer 2 config file and acknowledge the response with an ACK(success) or NACK(failure) as described here. Appropriate business logic may be triggered after this acknowledgement is sent to the sender.
- While the entire request-response process in Beckn is asynchronous, the software in BAP mode may wrap this up to provide a synchronous API to the caller.(optional)
- The software must refer to the Beckn Core Transaction API for the meaning of the context attributes and their usage. Some of attributes that have a major impact on functionality are listed here.
- message_id: The software should generate and use a new message_id for every new interaction. This message_id is guaranteed to be intact in all corresponding asynchronous responses.
- transaction_id: The software may use the transaction_id across messages (search, select… confirm) to act as a proxy for a user session. The transaction_id is guaranteed to be returned intact in all corresponding asynchronous responses.
- bap_id: The software in the BAP mode must fill its own subscriber_id here.
- bap_uri: The software in the BAP mode must fill its own subscriber_url here.
- bpp_id: When sending peer-to-peer messages (all Transaction API except search) as well as to send search message only to one BPP, target BPP subscriber id must be sent in this field.
- bpp_uri: When sending peer-to-peer messages (all Transaction API except search) as well as to send search message only to one BPP, target BPP subscriber URL must be sent in this field.
- ttl: This defines the amount of time the request is considered active to correlate responses. Any responses for this request after this ttl must be dropped.
- In case of error during the processing of requests, the BPP will return back error responses. The format of the error messages is defined in the Beckn Core Transaction Specification. The code to be used is specified in Error codes for BPP. These should be gracefully handled on the BAP.
- When the BPP needs more information from the consumer, it may use the XInput facility to redirect the user to a BPP defined form. The software in BAP mode should respect this request and the implementation should be as described in The XInput Schema.
- BPPs expose meta APIs to provide metadata that may be useful to the BAP in its user interaction. The BAP may call these meta APIs as required. These meta APIs are described here
- In addition to the Authentication requirements specified in the “Requirements for all modes” section, an on_subscribe endpoint must be made available for the registry to verify the public-key set there. The details are documented here.
- In addition to the Authentication-Verification requirements specified in the “Requirements for all modes” section, when the software in BPP mode receives a search message from the Gateway, there is an additional Proxy verification that must be done to ensure the message is sent by a valid Gateway and is not tampered. This involves lookup of the Gateway public key and is documented here
- The software operating in the BPP mode must facilitate the provider side of the commerce transaction workflow including all the four stages of Discovery, Order, Fulfillment and Post fulfillment as described here. The mandatory parts of these requirements are listed below and tagged as “Transaction API”.
- The software should implement or facilitate integration with additional business requirements associated with the transaction relevant to the provider.
- Software in BPP mode must implement the following endpoints (all POST) at the subscriber_url. These APIs are part of the transaction workflow covering all the four stages of Discovery, Order, Fulfillment and Post fulfillment. The format of the incoming requests is detailed here. The endpoints and the contents of the payloads are:
- search - search intent for product or service
- select - user’s cart or built order
- init - draft order from user
- confirm - order confirmation from user
- status - request for order status
- track - request for tracking url for order
- cancel - request for order cancellation
- update - request for order update
- rating - user rating
- support - request for support contact details
- Software must ensure that incoming requests and outgoing responses (described below) are compliant with Layer 2 configuration rules as required by the network. The Layer 2 Config file to be used must be decided based on the context of the message (e.g. using the domain and version fields). In case no Layer 2 config file is found for a message, the software must use the matching core version of Beckn Core Transaction API Specification to validate the messages.
- The description of the content of the messages provided in the Beckn Core Transaction API Spec should be followed by the software. Some of these attributes which have significant functionality attached, are described below. The Beckn Core Spec should be referred to for authoritative descriptions on all attributes.
- The software must validate the incoming request for syntax and acknowledge with a success or failure (ACK/NACK) as described here. Essentially an ACK means that the software will send a response in due course. The format of the incoming messages must be verified using the Layer 2 Config file as described above.
- After the software acknowledges the request, it may trigger business logic to process the request. If the acknowledgement was an ACK, the software must respond back with a response. The format of the response must be valid against the Layer 2 Config file. The software should send a response (by calling these endpoints on the BAP subscriber url) from the following corresponding to the request (on_search for search, on_select for select etc). The endpoints to call and the required payload contents are:
- on_search - search result catalog
- on_select - quote for cart/order sent in select
- on_init - draft order with payment terms
- on_confirm - confirmation of order created
- on_status - status of requested order
- on_track - tracking details of requested order
- on_update - updated order
- on_cancel - canceled order
- on_rating - acknowledgement for rating
- on_support - requested support information
- The recipient of the responses will send back an acknowledgement as described here. The software should suitably handle the failure cases (NACK).
- The software must refer to Beckn Core Transaction API for the meaning of the context attributes and their usage. Some of attributes that have a major impact on functionality are listed here.
- message_id: The software in BPP mode must return the message_id unaltered in the corresponding response. For example the on_select of a select message should have the same message_id as the select message. If the software is sending a on_xxxxx message without a corresponding request (e.g. on_status on change of order status), then it must use a new message_id
- transaction_id: The software in BPP mode must send back the transaction_id unaltered in the corresponding response.
- bap_id: The software in BPP mode must send back the bap_id unaltered in the corresponding response.
- bap_uri: The software in BPP mode must send back the bap_uri unaltered in the corresponding response.
- bpp_id: The software in BPP mode must fill in this attribute with its own subscriber id.
- bpp_uri: The software in BPP mode must fill in this attribute with its own subscriber url.
- ttl: This defines the amount of time the message is considered active to correlate responses. Any responses for this message after this ttl must be dropped.
- In certain use cases such as order status update, the software in BPP mode may send an on_xxxx (e.g. on_status) message to the BAP. The software in BPP mode must use a new message_id.
- When the BPP needs more information from the consumer, it may use the XInput facility to redirect the user to a BPP defined form. The implementation should be as described in The XInput Schema.
- In case of error during the processing of requests, the BPP must return back error responses. The format of the error messages is defined in the Beckn Core Transaction Specification. The codes to be used is specified in Error codes for BPP
- The software in BPP mode must implement Meta API as described here. These may be used by the BAP to assist in user interaction.
- Software in registry mode should allow Network Participant to register itself with a Subscriber ID and Subscriber URL
- Approval: Software in registry mode may have approval criteria for registrants. Once the criteria are met, the registrants may be considered as subscribers as described here.
- Ownership: Software in registry mode must allow organizations / users that register Network Participants to own and have rights to modify their network roles and participant keys. It must not allow a user to change other user’s network participant details.
- Software in registry mode must allow subscribers to create and alter their details including domain, role, location etc as described in Subscription and Subscriber objects through the subscribe endpoint described below.
- Software in registry mode must allow public key associated with network participants to be changed through the subscribe endpoint described below.
- Software in registry mode must support the modification of subscriber information through the subscribe endpoint as described in Beckn Protocol Registry Infrastructure API. It must support automatic verification of changed information through the call to on_subscribe as described in the API document.
- Software in registry mode must support the lookup of Subscriber information through the lookup endpoint as described in Beckn Protocol Registry Infrastructure API. The lookup is a synchronous API call and must return its result in the response. It must support the following while it may support filtering by the rest of the parameters in subscriber and subscription objects.
- lookup by subscriber_id and key_id
- lookup by domain and type
- All public key changes of the network participants must be logged and stored for extended duration. This is required for dispute resolutions at the trust layer.
- It should be possible to copy the network participant information present in the registry in bulk from one registry to another.
- In addition to the Authentication-Key-Pair general requirement for all modes, an on_subscribe endpoint must be made available for the registry to verify the public-key set there. The details are documented here.
- When the software in Gateway mode receives messages from the BAP to forward to the BPP, it must add its own signature and fill the X-Gateway-Authorization header. The process of hashing, signing and format of the header is documented here.
- The software in Gateway mode must expose the search endpoint at its Subscriber URL. The format of the message it receives is described here.
- When the Gateway receives a search request from the BAP, it must do the following:
- Use the lookup API of the Registry to fetch the BPPs that cater to the context of the received message.
- Forward the search request (after signing as described above) to the list of BPPs returned by the Registry.
- The software in Gateway mode should implement short term cache to reduce the load on the Registry lookup
The system should be engineered to deliver optimal performance, ensuring quick and responsive interactions under various operating conditions. It should efficiently utilize resources to maintain a consistent user experience, even during periods of peak usage.
The system's architecture should support seamless scalability, enabling it to handle increased workloads and user demand with minimal effort. Both horizontal and vertical scaling strategies should be considered to ensure the system can grow alongside the needs of the business.
Every new network Participant in the Beckn network could potentially bring in a large amount of consumers or providers. The software should be designed to be scalable with respect to number of parallel requests being processed as well as latency.
The lookup API of the software in registry mode might potentially be called multiple times in a single message flow. It should be highly scalable and have low latency.
In the gateway mode, the software should be scalable with respect to the total time it takes to forward a search as the number of search requests and the number of BPPs increase.
The software should be designed for high reliability, incorporating redundancy and fault-tolerant mechanisms to minimize downtime. It should maintain continuous availability, even in the event of hardware or software failures, ensuring users have consistent access to services.
The software should be intuitive and user-friendly, allowing users to complete tasks efficiently with minimal learning curve. The design should adhere to best practices in usability and accessibility, providing a positive experience for all users, including those with varying abilities.
The API and schemas specification can be found here:
https://github.com/beckn/protocol-specifications
The APIs can be browsed here: