Beckn-ONIX

A production-ready, plugin-based middleware adapter for the Beckn Protocol

Overview • Features • Architecture • Quick Start • Documentation • Contributing

Latest Update

In August 2025, a completely new Beckn-ONIX adapter was made available. This version introduces a Plugin framework at it's core. The ONIX Adapter previous to this release is archived to a separate branch, main-pre-plugins for reference.

Overview

Beckn-ONIX is an enterprise-grade middleware adapter system designed to facilitate seamless communication in any Beckn-enabled network. It acts as a protocol adapter between Beckn Application Platforms (BAPs - buyer applications) and Beckn Provider Platforms (BPPs - seller platforms), ensuring secure, validated, and compliant message exchange across various commerce networks.

What is Beckn Protocol?

The Beckn Protocol is an open protocol that enables location-aware, local commerce across any platform and any domain. It allows creation of open, decentralized networks where:

Platform Independence: Buyers and sellers can transact regardless of the platforms they use
Interoperability: Seamless communication between different systems using standardized protocols
Domain Agnostic: Works across retail, mobility, healthcare, logistics, and other domains
Network Neutral: Can be deployed in any Beckn-compliant network globally

Key Concepts

BAP (Beckn Application Platform): Buyer-side applications that help users search for and purchase products/services (e.g., consumer apps, aggregators)
BPP (Beckn Provider Platform): Seller-side platforms that provide products/services (e.g., merchant platforms, service providers)
Beckn Network: Any network implementing the Beckn Protocol for enabling open commerce

Features

🔌 Plugin-Based Architecture

Dynamic Plugin Loading: Load and configure plugins at runtime without code changes
Extensible Design: Easy to add new functionality through custom plugins
Hot-Swappable Components: Update plugins without application restart (in development)

🔐 Enterprise Security

Ed25519 Digital Signatures: Cryptographically secure message signing and validation
HashiCorp Vault Integration: Centralized secrets and key management
Request Authentication: Every message is authenticated and validated
TLS/SSL Support: Encrypted communication channels

✅ Protocol Compliance

JSON Schema Validation: Ensures all messages comply with Beckn protocol specifications
Version Management: Support for multiple protocol versions simultaneously
Domain-Specific Schemas: Tailored validation for different business domains

🚀 High Performance

Redis Caching: Response caching for improved performance
RabbitMQ Integration: Asynchronous message processing via message queues
Connection Pooling: Efficient resource utilization
Configurable Timeouts: Fine-tuned performance controls

📊 Observability

Structured Logging: JSON-formatted logs with contextual information
Transaction Tracking: End-to-end request tracing with unique IDs
Metrics Support: Performance and business metrics collection
Health Checks: Liveness and readiness probes for Kubernetes

🌐 Multi-Domain Support

Retail & E-commerce: Product search, order management, fulfillment tracking
Mobility Services: Ride-hailing, public transport, vehicle rentals
Logistics: Shipping, last-mile delivery, returns management
Healthcare: Appointments, telemedicine, pharmacy services
Financial Services: Loans, insurance, payments

Architecture

┌─────────────────────────────────────────────────────────┐
│                    HTTP Request                          │
└────────────────────────┬────────────────────────────────┘
                         │
┌────────────────────────▼────────────────────────────────┐
│                   Module Handler                         │
│  (bapTxnReceiver/Caller or bppTxnReceiver/Caller)      │
└────────────────────────┬────────────────────────────────┘
                         │
┌────────────────────────▼────────────────────────────────┐
│                 Processing Pipeline                      │
│  ┌─────────────┐  ┌─────────────┐  ┌─────────────┐    │
│  │ Middleware  │→ │   Steps     │→ │   Plugins   │    │
│  │(preprocess) │  │(validate,   │  │(cache,router│    │
│  └─────────────┘  │route, sign) │  │validator...)│    │
│                   └─────────────┘  └─────────────┘    │
└────────────────────────┬────────────────────────────────┘
                         │
┌────────────────────────▼────────────────────────────────┐
│              External Services/Response                  │
└─────────────────────────────────────────────────────────┘

Core Components

1. Transaction Modules

bapTxnReceiver: Receives callback responses at BAP
bapTxnCaller: Sends requests from BAP to BPP
bppTxnReceiver: Receives requests at BPP
bppTxnCaller: Sends responses from BPP to BAP

2. Processing Steps

validateSign: Validates digital signatures on incoming requests
addRoute: Determines routing based on configuration
validateSchema: Validates against JSON schemas
sign: Signs outgoing requests
cache: Caches requests/responses
publish: Publishes messages to queue

3. Plugin Types

Cache: Redis-based response caching
Router: YAML-based routing rules engine for request forwarding (supports domain-agnostic routing for Beckn v2.x.x)
Signer: Ed25519 digital signature creation for outgoing requests
SignValidator: Ed25519 signature validation for incoming requests
SchemaValidator: JSON schema validation
Schemav2Validator: OpenAPI 3.x schema validation with action-based matching
KeyManager: HashiCorp Vault integration for production key management
SimpleKeyManager: Embedded key management for local development (no external dependencies)
Publisher: RabbitMQ message publishing for asynchronous processing
Encrypter: AES encryption for sensitive data protection
Decrypter: AES decryption for encrypted data processing
ReqPreprocessor: Request preprocessing (UUID generation, headers)
Registry: Standard Beckn registry lookup for participant information
DeDiRegistry: DeDi registry to lookup public keys for NP.

Quick Start

Prerequisites

Go 1.24 or higher
Redis (for caching)
Docker (optional, for containerized deployment)

Build and Run

Clone the repository

git clone https://github.com/beckn/beckn-onix.git
cd beckn-onix

Build the application

go build -o server cmd/adapter/main.go

Build plugins

./install/build-plugins.sh

Extract schemas

unzip schemas.zip

Start Redis (if not running)

docker run -d -p 6379:6379 redis:alpine

Update the config file

Note: You can modify the configuration file to suit your environment before starting the server. ONIX adapter/server must be restarted to reflect any change made to the config file.

The following config change is required to all cache related entries in order to connect to redis that was started earlier.

        cache:
          id: cache
          config:
            addr: localhost:6379

Run the application

./server --config=config/local-simple.yaml

The server will start on http://localhost:8081

Automated Setup (Recommended)

For local setup, starts only redis and onix adapter:

# Clone and setup everything automatically
git clone https://github.com/beckn/beckn-onix.git
cd beckn-onix/install
chmod +x setup.sh
./setup.sh

This automated script will:

Start Redis container
Build all plugins with correct Go version
Build the adapter server
Start ONIX adapter in Docker
Create environment configuration

Note:

Schema Validation: Extract schemas before running: unzip schemas.zip (required for schemavalidator plugin)
Alternative: You can use schemav2validator plugin instead, which fetches schemas from a URL and doesn't require local schema extraction. See CONFIG.md for more configuration details.
Optional: Before running the automated setup, build the adapter image and update docker-compose-adapter.yaml to use the correct image

# from the repository root
docker build -f Dockerfile.adapter-with-plugins -t beckn-onix:latest .

For detailed setup instructions, see SETUP.md

Services Started:

Redis: localhost:6379
ONIX Adapter: http://localhost:8081

Docker Deployment

Note: Start redis before before running onix adapter.

# Build the Docker image
 docker build -t beckn-onix:latest -f Dockerfile.adapter-with-plugins .

# Run the container
docker run -p 8081:8081 \
  -v $(pwd)/config:/app/config \
  -v $(pwd)/schemas:/app/schemas \
  -e CONFIG_FILE="/app/config/local-simple.yaml" \
  beckn-onix:latest

Basic Usage Example

1. Search for Products (BAP → BPP)

curl -X POST http://localhost:8081/bap/caller/search \
  -H "Content-Type: application/json" \
  -d '{
    "context": {
      "domain": "nic2004:60221",
      "country": "IND",
      "city": "std:080",
      "action": "search",
      "version": "0.9.4", 
      "bap_id": "bap.example.com",
      "bap_uri": "https://bap.example.com/beckn",
      "transaction_id": "550e8400-e29b-41d4-a716-446655440000",
      "message_id": "550e8400-e29b-41d4-a716-446655440001",
      "timestamp": "2023-06-15T09:30:00.000Z",
      "ttl": "PT30S"
    },
    "message": {
      "intent": {
        "fulfillment": {
          "start": {
            "location": {
              "gps": "12.9715987,77.5945627"
            }
          },
          "end": {
            "location": {
              "gps": "12.9715987,77.5945627"
            }
          }
        }
      }
    }
  }'

Configuration

Configuration Structure

appName: "beckn-onix"
log:
  level: debug
  destinations:
    - type: stdout
http:
  port: 8080
  timeout:
    read: 30
    write: 30
    idle: 30
pluginManager:
  root: ./plugins
modules:
  - name: bapTxnReceiver
    path: /bap/receiver/
    handler:
      type: std
      role: bap
      plugins:
        cache:
          id: cache
          config:
            addr: localhost:6379
        router:
          id: router
          config:
            routingConfig: ./config/routing.yaml
        schemaValidator:
          id: schemavalidator  # or schemav2validator 
          config:
            schemaDir: ./schemas  # for schemavalidator
            # type: url           # for schemav2validator
            # location: https://example.com/spec.yaml
      steps:
        - validateSign
        - addRoute
        - validateSchema

Deployment Modes

Combined Mode: Single instance handling both BAP and BPP (config/onix/) - Uses secretskeymanager (HashiCorp Vault) for production key management
BAP-Only Mode: Dedicated buyer-side deployment (config/onix-bap/)
BPP-Only Mode: Dedicated seller-side deployment (config/onix-bpp/)
Local Development Combined Mode: Simplified configuration (config/local-simple.yaml) - Uses simplekeymanager with embedded Ed25519 keys, no vault setup needed.
Local Development Combined Mode (Alternative): Development configuration (config/local-dev.yaml) - Uses keymanager vault setup needed

API Endpoints

BAP Endpoints

Method	Endpoint	Description
POST	`/bap/caller/search`	Search for products/services
POST	`/bap/caller/select`	Select specific items
POST	`/bap/caller/init`	Initialize order
POST	`/bap/caller/confirm`	Confirm order
POST	`/bap/caller/status`	Check order status
POST	`/bap/caller/track`	Track order/shipment
POST	`/bap/caller/cancel`	Cancel order
POST	`/bap/caller/update`	Update order
POST	`/bap/caller/rating`	Submit rating
POST	`/bap/caller/support`	Get support

BPP Endpoints

Method	Endpoint	Description
POST	`/bpp/receiver/*`	Receives all BAP requests
POST	`/bpp/caller/on_*`	Sends responses back to BAP

Documentation

Setup Guide: Complete installation, configuration, and deployment instructions
Configuration Guide: Description of Configuration concepts and all config parameters
Contributing: Guidelines for contributors
Governance: Project governance model
License: Apache 2.0 license details

GUI Component

The project includes a Next.js-based GUI component located in onix-gui/ that provides:

Visual configuration management
Request/response monitoring
Plugin status dashboard
Routing rules editor

Testing

# Run all tests
go test ./...

# Run tests with coverage
go test -coverprofile=coverage.out ./...
go tool cover -html=coverage.out

# Run specific test
go test ./pkg/plugin/implementation/cache -v

# Run tests with race detection
go test -race ./...

Contributing

We welcome contributions! Please see our Contributing Guide for details on:

Code of Conduct
Development process
Submitting pull requests
Reporting issues

Support

Issues: GitHub Issues
Discussions: GitHub Discussions
Documentation: Wiki

License

This project is licensed under the Apache License 2.0 - see the LICENSE file for details.

Acknowledgments

Beckn Foundation for the protocol specifications

Contributor	Organization	Github ID
Ashish Guliya	Google Cloud	ashishkgGoogle
Pooja Joshi	Google Cloud	poojajoshi2
Deepa Mulchandani	Google Cloud	Deepa-Mulchandani
Ankit	FIDE	ankitShogun
Abhishek	FIDE	em-abee
Viraj Kulkarni	FIDE	viraj89
Amay Pandey	Google Cloud
Dipika Prasad	Google Cloud	DipikaPrasad
Tanya Madaan	ONDC	tanyamadaan
Binu	ONDC
Faiz M	FIDE	faizmagic
Ravi Prakash	FIDE	ravi-prakash-v
Siddharth Prakash	Google Cloud
Namya Patiyal	Google Cloud
Saksham Nagpal	Google Cloud	sakshamGoogle
Arpit Bharadwaj	Google Cloud
Pranoy	Google Cloud
Mayuresh Nirhali	FIDE Volunteer	nirmay
Madhuvandhini B	Google Cloud	madhuvandhini5856
Siddhartha Banerjee	Google Cloud	sidb85

Built with ❤️ for the open Value Network ecosystem

Name		Name	Last commit message	Last commit date
Latest commit History 619 Commits
.github		.github
Deployment		Deployment
cmd		cmd
config		config
core/module		core/module
install		install
pkg		pkg
validation-scripts		validation-scripts
.gitignore		.gitignore
CONFIG.md		CONFIG.md
CONTRIBUTING.md		CONTRIBUTING.md
Dockerfile.adapter		Dockerfile.adapter
Dockerfile.adapter-with-plugins		Dockerfile.adapter-with-plugins
GOVERNANCE.md		GOVERNANCE.md
LICENSE		LICENSE
README.md		README.md
SETUP.md		SETUP.md
go.mod		go.mod
go.sum		go.sum
schemas.zip		schemas.zip
test.go		test.go

License

Beckn-One/beckn-onix

Folders and files

Latest commit

History

Repository files navigation

Beckn-ONIX

Latest Update

Overview

What is Beckn Protocol?

Key Concepts

Features

🔌 Plugin-Based Architecture

🔐 Enterprise Security

✅ Protocol Compliance

🚀 High Performance

📊 Observability

🌐 Multi-Domain Support

Architecture

Core Components

1. Transaction Modules

2. Processing Steps

3. Plugin Types

Quick Start

Prerequisites

Build and Run

Automated Setup (Recommended)

Docker Deployment

Basic Usage Example

1. Search for Products (BAP → BPP)

Configuration

Configuration Structure

Deployment Modes

API Endpoints

BAP Endpoints

BPP Endpoints

Documentation

GUI Component

Testing

Contributing

Support

License

Acknowledgments

About

Resources

License

Contributing

Uh oh!

Stars

Watchers

Forks

Releases 6

Packages 0

Uh oh!

Contributors 25

Uh oh!

Languages

Packages