> For the complete documentation index, see [llms.txt](https://docs.nfh.global/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.nfh.global/nfh-fabric/open-standards/beckn-protocol.md). # Beckn Protocol The Beckn Protocol specification defines a standard protocol stack that allows independently run applications to take part in trusted value exchange transactions. ## Introduction The Beckn Protocol specification defines a standard protocol stack that allows independently run applications to take part in trusted value exchange transactions. These transactions usually move through discovery, contracting, fulfillment, and post-fulfillment. This document explains NFH fabric v2 at a high level. It is an overview. It is meant to help a human or an AI agent understand how the parts fit together before going into the full API files and schema files. This protocol stack consists of the following layers (bottom to top) 1. Network Architecture 2. API Specification 3. Composable linked-data schema 4. Communication Protocol 5. Workflows Let us understand each of these layers briefly. {% hint style="info" icon="link" %} Refer to the protocol here - {% endhint %} ### Network Architecture An NFH fabric network is a set of separate services. Each service is run independently. The protocol gives them a common way to talk to each other. In beckn protocol v2 (Hereafter referred to as v2) the main actor roles are the following: 1. consumer node (consumer node) - the buyer side or user side platform 2. provider node (provider node) - the seller side or provider side platform. A provider node self-hosts and self-signs its own catalog data on infrastructure it controls, discoverable through its existing Registry-anchored identity 3. DS (Discovery Service) - the service that answers discovery queries from consumer nodes. It builds its own index by crawling and independently verifying every provider node's self-hosted catalog data 4. Registry - the trust directory that stores participant identity, endpoints, and public keys A consumer node discovers supply through a DS. A provider node makes its catalog discoverable by hosting signed catalog files and a signed catalog index on its own infrastructure and pointing to that index from its Registry record. A DS crawls that data directly from the provider node, verifies it independently, and builds its own index from what it verifies. After discovery, the consumer node usually talks directly to the provider node for the transaction. All actors use the Registry to find endpoints and public keys and to verify signatures. In v2 the Registry is a DeDi-compliant directory. This means the trust layer is treated as a proper public directory and not as a custom side system. The important point is this: v2 does not depend on a live multicast gateway for discovery, and it does not route catalog data through any centrally-operated relay either. Discovery is catalog-first and index-based, and trust is anchored directly in each provider node's own signature — verified independently by every Discovery Service that crawls it. ```mermaid flowchart TB subgraph TOP[Transaction Layer] direction TB CN <-->|discover / on_discover| DS CN <-->|Transaction API| PN DS -->|crawls self-signed catalog files| PN end subgraph BOTTOM[NFH fabric : Universal Value-Exchange Infrastructure] direction LR REG[Registry] end CN -.->|lookup| REG PN -.->|lookup| REG DS -.->|lookup| REG ``` ### API Specification The API specification defines the common shape of NFH fabric messages and endpoints. In v2, the endpoint pattern is simple: ``` /beckn/{becknEndpoint} ``` For example, a participant may expose endpoints such as: * `/beckn/discover` * `/beckn/on_discover` * `/beckn/select` * `/beckn/on_select` * `/beckn/confirm` * `/beckn/on_confirm` The exact actions a participant supports depend on its role. Every beckn API call carries a transport envelope and a business payload. The transport envelope is the fixed part of the protocol. It carries things like the action name, IDs, time, and routing data. The business payload is the domain data inside the message. Beckn protocol specifies `context`, `message`, `inReplyTo`, `status`, and signatures in the transport contract. They are fixed. They must not be renamed or redefined by domain schema. At a high level, the main action groups are: 1. Discovery - `discover`, `on_discover` 2. Contracting - `select`, `on_select`, `init`, `on_init`, `confirm`, `on_confirm` 3. Fulfillment - `status`, `on_status`, `update`, `on_update`, `track`, `on_track`, `cancel`, `on_cancel` 4. Post-fulfillment - `rate`, `on_rate`, `support`, `on_support` 5. Infrastructure - `publish` and Registry lookups ### Composable linked-data schema In Beckn v2, the business payload is not just plain JSON. It is JSON-LD. JSON-LD lets every type and field carry a shared meaning. It does this mainly through two ideas: * `@context` - tells the reader where the meaning of terms comes from * `@type` - tells the reader what kind of object it is This is important because NFH fabric is meant to work across domains, geographies, and networks. A machine should not only read the data. It should also understand what the data means. Beckn v2 separates schema into three layers: 1. The transport envelope layer - the API envelope and container schemas 2. The core schema layer - shared business types such as `Catalog`, `Item`, `Offer`, `Intent`, `Contract`, `Provider`, `Fulfillment` 3. The domain schema pack layer - domain specific extensions such as retail, mobility, health, logistics, and others Where possible, Beckn protocol maps types and fields to schema.org. When the protocol needs its own meaning, it uses the NFH fabric/protocol namespace. This gives global interoperability without losing NFH fabric-specific meaning. This layered design solves an important problem. The transport API can stay small and stable. At the same time, the business schema can grow over time. New domains can be added without changing the basic transport contract. The `schema.beckn.io` website is the public place where these schema resources can be published and browsed. It gives stable IRIs, JSON-LD contexts, RDF vocabularies, and versioned schema pages. In simple words, it is the public map of meaning for NFH fabric data. ### Communication Protocol The communication protocol defines how NFH fabric messages move over the network. At the transport level, v2 uses HTTPS and digital signatures. There are three main request modes: 1. POST - used for normal forward requests and callbacks 2. GET Body Mode - used when a GET request with a JSON body is allowed 3. GET Query Mode - used when the whole request must fit inside a URL, such as a QR code or a deep link Every request except GET Query Mode carries an NFH fabric Signature in the `Authorization` header. The receiver verifies that signature using the sender's public key from the Registry. The communication pattern is usually as follows: 1. The sender sends a signed request 2. The receiver immediately returns `Ack` or `Nack` 3. If the request is accepted, the business result usually comes later as a callback 4. The callback carries `inReplyTo` so it can be tied to the original request 5. The `Ack` carries a `counterSignature`, which works as a signed receipt ```mermaid sequenceDiagram participant Sender participant Receiver Sender->>Receiver: RequestContainer Note over Sender,Receiver: Request is signed Receiver-->>Sender: Ack or Nack Note over Receiver,Sender: Ack includes counterSignature Receiver->>Sender: CallbackContainer Note over Receiver,Sender: Callback includes inReplyTo Sender-->>Receiver: Ack ``` This means it is not just request-response in the usual web sense. It is mainly an asynchronous and event-driven protocol. At a practical level, protocol supports all of the following patterns: * **Same-session acknowledgement** - the receiver immediately says whether it received the message * **Asynchronous business response** - the actual business result comes later through a callback * **Synchronous business response in some cases** - for example, discovery results may also be returned synchronously depending on network policy * **Later state-driven messages** - a later message may be sent because the state changed, not because a user clicked a button at that moment GET Query Mode is a special case. It is used when the request must be a self-contained URL. In that mode, the server must not send an asynchronous callback. It only returns an acknowledgement. ### Workflows Workflows are the business paths built on top of the API actions. The protocol gives reusable actions. A network then combines those actions into a workflow. A simple workflow often looks like this: 1. A provider node publishes catalog data 2. A consumer node discovers that catalog through a DS 3. The consumer node starts a transaction with a provider node 4. The consumer node and provider node agree on terms 5. The provider node fulfills the contract 6. The parties may exchange rating or support information later Not every network uses every action. Not every domain needs every step. The protocol gives the building blocks. The network chooses the path. ## Understanding the NFH fabric API Specification This section gives the API picture at a level useful for implementation. It keeps the discussion short and clear. A separate document can go action by action in more detail. ### What changed in beckn v2 If you have seen older beckn material, these are the changes that matter most: 1. Discovery is no longer based on live gateway multicast. provider nodes self-host and self-sign their own catalog data; Discovery Services crawl and independently verify it directly from each provider node. 2. The API surface is simplified around the common endpoint pattern `/beckn/{becknEndpoint}`. 3. The transport contract and the business schema are now clearly separated. 4. The business payload is JSON-LD, with shared meaning through `@context` and `@type`. 5. The Registry is aligned to a DeDi-compliant directory model. 6. Non-repudiation is stronger because acknowledgements can carry `counterSignature` and callbacks can carry `inReplyTo`. ### What an NFH fabric network participant must do Any platform can take part in an NFH fabric network if it can do the following: 1. Register its identity, endpoint, and public keys in the Registry 2. Send signed NFH fabric messages 3. Verify signed NFH fabric messages from others 4. Implement the endpoints needed for its role 5. Read and produce the shared JSON-LD payloads ### The main actors Let us look at the main actors one by one. #### consumer node A consumer node is the buyer side platform. It is the platform where the user, buyer, or demand side experience lives. A consumer node usually does the following: 1. Sends discovery requests to a DS 2. Receives discovery results 3. Sends transaction requests to provider nodes 4. Receives callbacks from provider nodes 5. Shows the results to the end user #### provider node A provider node is the provider side platform. It is the platform where the provider's catalog, pricing, contract logic, and fulfillment logic live. A provider node usually does the following: 1. Hosts its own signed catalog files and a signed catalog index on infrastructure it controls, and points to that index from its Registry record — making its catalog discoverable without calling any beckn API 2. Receives transaction requests from consumer nodes 3. Sends callbacks to consumer nodes 4. Updates contract and fulfillment state over time #### DS (Discovery Service) A DS is the catalog discovery service. It resolves each provider node's Registry record, crawls the provider node's self-hosted catalog index and files directly, verifies every signature independently, and builds and maintains its own index from what it has verified. It then answers discovery requests from consumer nodes against that index. This is why NFH fabric v2 discovery is fast and does not need live fan-out to all provider nodes, and why no centrally-run catalog service sits between a provider node and a Discovery Service. #### Registry The Registry is the trust directory of the network. It stores participant records, endpoints, capabilities, and public keys. Before a participant sends a message, it can use the Registry to find where to send the message and how to verify the signature. ### What every NFH fabric packet contains Every NFH fabric request or callback contains two main parts: * `context` * `message` The `context` carries the routing and control data. The `message` carries the business data. A callback also carries `inReplyTo` so that it can be tied to the original request. A simplified NFH fabric packet looks like this: ```json { "context": { "domain": "beckn:retail", "action": "discover", "version": "2.0.0", "bapId": "bap.example.com", "bapUri": "https://bap.example.com/callback", "transactionId": "txn-123", "messageId": "msg-456", "timestamp": "2026-03-27T00:00:00Z", "ttl": "PT30S" }, "message": { "@context": [ "https://schema.org/", "https://schema.beckn.io/core/v2.0/context.jsonld" ], "@type": "Intent" } } ``` The important thing to remember is this: the transport envelope and the business payload are different concerns. * The transport envelope tells you how the message should move * The business payload tells you what the message means ### Transport envelope and business payload NFH fabric v2 keeps these two layers separate on purpose. The transport layer gives a stable message frame. It defines the container schemas such as `Context`, `RequestContainer`, `CallbackContainer`, `Ack`, `Nack`, `CounterSignature`, and `InReplyTo`. The business layer gives the actual domain objects such as `Catalog`, `Item`, `Offer`, `Intent`, `Contract`, `Fulfillment`, `Tracking`, `Rating`, and `Support`. This separation has a big benefit. The transport layer stays stable. The business layer can evolve across domains. ### A note on v2 words In older NFH fabric explanations, you will often see the word `Order`. In NFH fabric v2 core schema, the more exact word is `Contract`. The idea is similar. It is the formal record of what the parties agreed to. In the same way, `ContractItem` replaces the older `OrderItem`. This matters mainly at the schema layer. The transaction idea itself remains easy to understand: discovery leads to agreement, agreement leads to fulfillment, and fulfillment may be followed by support or rating. ### The main request modes The same NFH fabric action can be carried in different transport modes. #### POST POST is the normal mode for: * forward requests such as consumer node to DS or consumer node to provider node * callbacks such as DS to consumer node or provider node to consumer node #### GET Body Mode GET Body Mode lets a caller send an NFH fabric request in a GET request with a JSON body. This is useful in cases where GET semantics are needed but the caller can still send a body and expects a later callback. #### GET Query Mode GET Query Mode puts the full request and signature inside the URL query string. This is useful for: * QR codes * deep links * bookmarkable search links * simple browser or device clients In GET Query Mode there is no asynchronous callback. The server only returns an `Ack` or a `Nack`. ### How discovery works in NFH fabric v2 Discovery is one of the biggest changes in NFH fabric v2. In older models, discovery often depended on a gateway sending the query to many provider nodes in real time. In NFH fabric v2, discovery is catalog-first, and catalog data flows directly from a provider node to a Discovery Service — never through a shared intermediary: 1. A provider node hosts signed catalog files and a signed catalog index on storage it controls, and adds the index's URL to its Registry record 2. A Discovery Service resolves the provider node's Registry record and finds that pointer 3. The Discovery Service crawls the catalog index and catalog files directly from the provider node, verifying every signature before indexing anything 4. The Discovery Service builds and maintains its own index from what it has verified, re-crawling on its own schedule to pick up incremental changes 5. A consumer node sends a `discover` request to the DS 6. The DS returns matching catalog data from its own index 7. After discovery, the consumer node talks directly to the chosen provider node ```mermaid sequenceDiagram participant PN as Provider Node participant Reg as Registry participant DS as Discovery Service participant CN as Consumer Node PN->>PN: Host signed catalog files and index, add catalog_index_urls to Registry record DS->>Reg: Resolve PN's Registry manifest and Subscriber record DS->>PN: GET catalog index and catalog files, conditionally PN-->>DS: Signed catalog index and files DS->>DS: Verify signatures, build own index CN->>DS: discover DS-->>CN: Ack DS->>CN: on_discover or synchronous response ``` This design gives three major benefits: 1. Discovery becomes faster 2. provider nodes do not need to answer every live discovery query 3. A provider node has full sovereignty over how and where its own catalog data is hosted — no shared, centrally-operated service sits in the path, and none can become a single point of failure for the whole network's discovery phase > The full mechanism — catalog file and index schemas, signing and verification, incremental updates, and catalog lifecycle — is specified in the [Decentralized Catalog Publishing and Discovery RFC (NFH-014)](https://github.com/beckn/protocol-specifications-v2/blob/decentralised-catalog/docs/Catalog_Publishing_and_Discovery.md) and covered in NFH fabric by [Catalog Publishing and Discovery](/build/creating-a-network/catalog-publishing-and-discovery.md) and [DISCOVR](/product-documentation/products/discovr.md). ### The main action groups The NFH fabric actions are best understood by stage. | Stage | Main actions | What they do | | ---------------- | ---------------------------------------------------------------------------------------- | ----------------------------------------------------- | | Discovery | `discover`, `on_discover` | Find matching catalog data | | Contracting | `select`, `on_select`, `init`, `on_init`, `confirm`, `on_confirm` | Agree on scope, terms, price, and create the contract | | Fulfillment | `status`, `on_status`, `update`, `on_update`, `track`, `on_track`, `cancel`, `on_cancel` | Manage the live state of the contract | | Post-fulfillment | `rate`, `on_rate`, `support`, `on_support` | Handle rating and support | | Infrastructure | `publish`, Registry lookups | Publish supply and resolve trust data | A simple way to think about these stages is: 1. **Discovery** - find what is available 2. **Contracting** - agree what will happen 3. **Fulfillment** - do what was agreed 4. **Post-fulfillment** - rate, support, and close the loop ### A full NFH fabric flow at a glance ```mermaid sequenceDiagram participant Provider participant DS participant Consumer participant Registry Provider->>Registry: register identity, endpoint, and keys Provider->>Provider: host signed catalog files and index Provider->>Registry: add catalog index URL to Registry record Consumer->>Registry: lookup DS and Provider details DS->>Registry: resolve Provider's Registry record DS->>Provider: crawl and verify catalog index and files DS->>DS: build own index Consumer->>DS: discover DS->>Consumer: on_discover or synchronous result Consumer->>Provider: select Provider->>Consumer: on_select Consumer->>Provider: init Provider->>Consumer: on_init Consumer->>Provider: confirm Provider->>Consumer: on_confirm Consumer->>Provider: status / update / track / cancel Provider->>Consumer: on_status / on_update / on_track / on_cancel Consumer->>Provider: rate / support Provider->>Consumer: on_rate / on_support ``` Not every transaction uses every step. For example, some networks may not use `track`. Some domains may not need `support`. Some contracts may not change after confirmation, so `update` may never be used. ### What an implementer should build If you want to start implementing NFH fabric, it helps to think role by role. #### If you are building a consumer node You usually need to build the following: 1. A client for calling DS and provider node endpoints 2. Callback endpoints for receiving `on_` actions 3. Registry lookup support 4. Message signing and signature verification 5. JSON-LD payload handling 6. Contract and fulfillment state management on the buyer side #### If you are building a provider node You usually need to build the following: 1. A pipeline that generates, signs, and hosts your own catalog files and catalog index, and keeps your Registry record's `catalog_index_urls` current 2. Request endpoints for transaction actions 3. Callback sending to consumer nodes 4. Registry registration and key publication 5. Message signing and signature verification 6. Contract, payment, and fulfillment logic on the provider side #### If you are building a Discovery Service You need to build: 1. A crawler that resolves provider nodes' Registry records, fetches their catalog indexes and files, and verifies every signature before indexing anything 2. A `discover` endpoint 3. An index for `Catalog`, `Item`, `Offer`, and related graphs 4. Ranking, filtering, and query logic 5. Callback or synchronous response handling as allowed by the network policy #### If you are building any NFH fabric actor You should also remember the following: 1. Use HTTPS 2. Verify signatures on every incoming message 3. Use the Registry for public key resolution 4. Treat the transport envelope as fixed 5. Treat the `message` as the business payload 6. Load JSON-LD contexts in a controlled way. Do not trust unknown remote contexts blindly. ### Summary NFH fabric v2 becomes easy to understand once the separation of concerns is clear. * The **network architecture** tells you who talks to whom * The **API specification** tells you what endpoint and packet shape to use * The **linked-data schema** tells you what the payload means * The **communication protocol** tells you how signed requests, acknowledgements, and callbacks move * The **workflows** tell you how the actions are combined for a real business journey At a practical level, NFH fabric v2 works like this: 1. Providers publish catalog data 2. Discovery services index that data 3. Buyer side platforms discover matching supply 4. Buyer and provider platforms agree on terms 5. The provider fulfills the contract 6. The parties may exchange rating or support data after that If you understand these six ideas, you can start reading the NFH fabric transport files, schema files, and network guides with the right mental model. --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters: ``` GET https://docs.nfh.global/nfh-fabric/open-standards/beckn-protocol.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `build a script that syncs our docs to a CMS` lets GitBook tailor the answer to that use case. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.