beckn-onix

Beckn-ONIX

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
• Signer: Ed25519 digital signature creation for outgoing requests
• SignValidator: Ed25519 signature validation for incoming requests
• SchemaValidator: JSON schema validation
• 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

1. Clone the repository

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

1. Build the application

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

1. Build plugins

./install/build-plugins.sh

1. Extract schemas

unzip schemas.zip

1. Start Redis (if not running)

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

1. 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

1. 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: Extract schemas before running: unzip schemas.zip (required for schema validation) and before running the automated setup, build the adapter image if required ,update docker-compose-adapter.yaml to use the correct onix image

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

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
          config:
            schemaDir: ./schemas
      steps:
        - validateSign
        - addRoute
        - validateSchema

Deployment Modes

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

API Endpoints

BAP Endpoints

BPP Endpoints

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