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.

Refer to the protocol here - https://github.com/beckn/protocol-specifications-v2

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.

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

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:

{
  "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

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) and covered in NFH fabric by Catalog Publishing and Discovery and DISCOVR.

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

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.