A reference architecture · Beckn protocol v2.0

An open commerce
network, ratified by a council.

ION layers governance, a network profile, and three core services on top of the Beckn protocol — connecting buyer apps, providers, and consumers across Indonesian commerce.

5
Layers
3
Core services
BAP ↔ BPP
Participant edge
v2.0
Beckn protocol
01 The picture

Five layers, one trunk.

The Council ratifies the network. The network profile codifies what's allowed. Three core services keep the directory, catalogue, and discovery live. Participants — buyer and provider platforms — speak the Beckn protocol across the shared rail. The consumer is the only layer that doesn't run code.

ION Network Architecture Five-tier diagram: Council, Network profile, Core services, Participants, Consumer. L1 · Governance L2 · Network profile L3 · Core services L4 · Participants L5 · End user ION Council Governance body ratifies ION Network ion.yaml — network profile Policy Registry Error Registry ION Registry on DeDi Catalogue Service Beckn Fabric Discover Service CDS registers publishes queries · subscribes BAP Buyer apps Pasar Sapa · Tokopedia · Shopee BPP Provider platforms Merchants · JNE · J&T · LSPs BAP Additional buyer apps Partner storefronts · niche apps /select /on_select Beckn Protocol Exchange /init · /confirm · /status · /track · /update · /reconcile Consumer — uses the app
fig. 01 Governance flows down. Catalogue and discovery flow sideways. Money and goods flow between the participants on the shared Beckn rail.
02 L1 · Governance

The ratifying body.

ION Council is the council. It sets policies, approves changes to the network profile, and arbitrates disputes between participants. Everything below this layer derives its authority from the Council's ratification.

Council decisions are encoded into ion.yaml (the next layer down) so that participants don't follow opinions — they follow the file.

03 L2 · Network profile

The network, in a file.

ion.yaml defines the network. The Policy Registry encodes what's allowed; the Error Registry standardises how participants report failure. Together they make the network legible to humans and machines alike.

Registry · policy
Policy Registry
What's allowed, by whom, when, and under what conditions. Manifest-derived rules referenced by every BPP and BAP.
drives  policy IRIs · allow/deny · annotations
Registry · errors
Error Registry
Standard error codes and shapes so two BPPs reporting "out of stock" use the same string and the same downstream behaviour.
drives  error codes · NACK shapes · auditor reporting
04 L3 · Core services

Three services, three jobs.

Participants register, providers publish, buyer apps discover. Everything in the protocol exchange below this layer presumes these three services are live.

L3 Core services directory · catalogue · discovery
ION Registry
The on-DeDi directory of every participant. BAPs and BPPs register here so the network knows who's authorised to transact.
Catalogue Service
BPPs publish their offerings to the Beckn Fabric so buyer apps can search across providers without point-to-point integrations.
Discover Service (CDS)
BAPs query and subscribe to discover catalogues, providers, and updates relevant to their users.
05 L4 · Participants

Two roles, symmetric shapes.

Every commerce event on the network is one BAP talking to one BPP, with verbs going one way and on_* callbacks coming back. Specific verticals (Trade, Logistics, Payment) define the message bodies; the shapes are always the same.

BAP · buyer side
Beckn Application Platform
The buyer-facing surface. Aggregates listings from many BPPs into a single buyer experience. Calls verbs like /select to express intent and consumes the /on_* callbacks.
examples  Pasar Sapa · Tokopedia · Shopee · partner apps
BPP · provider side
Beckn Provider Platform
The supply-side surface. Merchants and logistics providers expose inventory, fulfilment, and order-state through standard endpoints — the same endpoints regardless of who's calling.
examples  Merchants · JNE · J&T · LSPs · warehouses

The pattern is symmetric. For every verb a BAP calls, there is a matching on_* callback the BPP returns. Beckn is asynchronous by design, so callbacks may arrive seconds or minutes later from a different participant on the network.

06 Beckn protocol exchange

The shared rail.

Every BAP and every BPP speaks the same verbs across the same endpoints. The protocol carries no money and no goods — only messages — but those messages move the contract forward. 

# the shared protocol — every BAP ↔ BPP exchange uses these verbs
verbs:
  discover:     /search · /select
  commit:       /init · /confirm
  observe:      /status · /track · /update
  finalize:     /rate · /reconcile · /cancel

# every verb pairs with an on_* callback returned asynchronously
callbacks:     /on_search · /on_select · /on_confirm · /on_status · ...

See the trade × logistics walk-through for a worked example: thirty-two messages over fourteen phases joined by one linkedContractId.

07 L5 · End user

The point of the whole stack.

The consumer doesn't run code. The consumer opens a buyer app. Everything above this layer — Council, profile, services, participants, protocol — exists so a consumer in Jakarta can search one storefront and transact with any registered provider on the network.

That single mouse-click is the success criterion for the entire architecture.