diff --git a/README.md b/README.md index 8b13789..b4c8b98 100644 --- a/README.md +++ b/README.md @@ -1 +1,353 @@ +# Beckn-ONIX +
+ +[![Go Version](https://img.shields.io/badge/Go-1.23-blue.svg)](https://golang.org) +[![License](https://img.shields.io/badge/License-Apache%202.0-green.svg)](LICENSE) +[![CI Status](https://img.shields.io/github/actions/workflow/status/beckn/beckn-onix/ci.yml)](https://github.com/beckn/beckn-onix/actions) +[![Coverage](https://img.shields.io/badge/Coverage-90%25-brightgreen.svg)](https://codecov.io/gh/beckn/beckn-onix) + +**A production-ready, plugin-based middleware adapter for the Beckn Protocol** + +[Overview](#overview) • [Features](#features) • [Architecture](#architecture) • [Quick Start](#quick-start) • [Documentation](#documentation) • [Contributing](#contributing) + +
+ +--- + +## 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 +- **Signer/SignValidator**: Ed25519 signature handling +- **SchemaValidator**: JSON schema validation +- **KeyManager**: HashiCorp Vault integration +- **Publisher**: RabbitMQ message publishing +- **Encrypter/Decrypter**: AES encryption/decryption +- **ReqPreprocessor**: Request preprocessing (UUID generation, headers) + +## Quick Start + +### Prerequisites + +- Go 1.23 or higher +- Redis (for caching) +- Docker (optional, for containerized deployment) +- HashiCorp Vault (optional, for production key management) +- RabbitMQ (optional, for async messaging) + +### Installation + +1. **Clone the repository** +```bash +git clone https://github.com/beckn/beckn-onix.git +cd beckn-onix +``` + +2. **Build the application** +```bash +go build -o server cmd/adapter/main.go +``` + +3. **Build plugins** +```bash +./build-plugins.sh +``` + +4. **Start Redis** (if not running) +```bash +docker run -d -p 6379:6379 redis:alpine +``` + +5. **Run the application** +```bash +./server --config=config/local-dev.yaml +``` + +The server will start on `http://localhost:8081` + +### Docker Deployment + +```bash +# Build the Docker image +docker build -f Dockerfile.adapter -t beckn-onix:latest . + +# Run the container +docker run -p 8080:8080 \ + -v $(pwd)/config:/app/config \ + -v $(pwd)/schemas:/app/schemas \ + beckn-onix:latest +``` + +### Basic Usage Example + +#### 1. Search for Products (BAP → BPP) + +```bash +curl -X POST http://localhost:8081/bap/caller/search \ + -H "Content-Type: application/json" \ + -H "Authorization: Signature keyId=\"bap.example.com|key1|ed25519\",algorithm=\"ed25519\",created=\"1234567890\",expires=\"1234567990\",headers=\"(created) (expires) digest\",signature=\"base64signature\"" \ + -d '{ + "context": { + "domain": "nic2004:60221", + "country": "IND", + "city": "std:080", + "action": "search", + "core_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 + +```yaml +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/`) +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**: Simplified configuration (`config/local-dev.yaml`) + +## 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](SETUP.md)**: Complete installation, configuration, and deployment instructions +- **[Contributing](CONTRIBUTING.md)**: Guidelines for contributors +- **[Governance](GOVERNANCE.md)**: Project governance model +- **[License](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 + +```bash +# 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](CONTRIBUTING.md) for details on: +- Code of Conduct +- Development process +- Submitting pull requests +- Reporting issues + +## Support + +- **Issues**: [GitHub Issues](https://github.com/beckn/beckn-onix/issues) +- **Discussions**: [GitHub Discussions](https://github.com/beckn/beckn-onix/discussions) +- **Documentation**: [Wiki](https://github.com/beckn/beckn-onix/wiki) + +## License + +This project is licensed under the Apache License 2.0 - see the [LICENSE](LICENSE) file for details. + +## Acknowledgments + +- [Beckn Foundation](https://beckn.org) for the protocol specifications +- All contributors and community members + +--- + +
+Built with ❤️ for the open commerce ecosystem +
\ No newline at end of file diff --git a/SETUP.md b/SETUP.md new file mode 100644 index 0000000..a402531 --- /dev/null +++ b/SETUP.md @@ -0,0 +1,1802 @@ +# Beckn-ONIX Setup Guide + +This comprehensive guide walks you through setting up Beckn-ONIX from development to production deployment. + +## Table of Contents + +1. [Prerequisites](#prerequisites) +2. [Development Setup](#development-setup) +3. [Production Setup](#production-setup) +4. [Configuration Guide](#configuration-guide) +5. [External Services Setup](#external-services-setup) +6. [GUI Component Setup](#gui-component-setup) +7. [Docker Deployment](#docker-deployment) +8. [Kubernetes Deployment](#kubernetes-deployment) +9. [Testing Your Setup](#testing-your-setup) +10. [Troubleshooting](#troubleshooting) +11. [Sample Payloads](#sample-payloads) + +--- + +## Prerequisites + +### System Requirements + +- **Operating System**: Linux, macOS, or Windows (with WSL2) +- **CPU**: 2+ cores recommended +- **RAM**: 4GB minimum, 8GB recommended +- **Disk Space**: 2GB free space + +### Software Requirements + +#### Required +- **Go 1.23+**: [Download Go](https://golang.org/dl/) +- **Git**: [Download Git](https://git-scm.com/downloads) +- **Redis 6.0+**: For caching functionality + +#### Optional (for production) +- **Docker 20.10+**: For containerized deployment +- **HashiCorp Vault 1.12+**: For secrets management +- **RabbitMQ 3.10+**: For async messaging +- **Kubernetes 1.25+**: For orchestrated deployment + +### Verify Installation + +```bash +# Check Go version +go version +# Expected: go version go1.23.x + +# Check Git +git --version + +# Check Docker (optional) +docker --version + +# Check Redis +redis-cli --version +``` + +--- + +## Development Setup + +### Step 1: Clone the Repository + +```bash +git clone https://github.com/beckn/beckn-onix.git +cd beckn-onix +``` + +### Step 2: Install Dependencies + +```bash +# Download Go dependencies +go mod download + +# Verify dependencies +go mod verify +``` + +### Step 3: Build the Application + +```bash +# Build the main server binary +go build -o server cmd/adapter/main.go + +# Make it executable +chmod +x server +``` + +### Step 4: Build Plugins + +The application uses a plugin architecture. Build all plugins: + +```bash +# Make the build script executable +chmod +x build-plugins.sh + +# Build all plugins +./build-plugins.sh +``` + +This creates `.so` files in the `plugins/` directory: +- `cache.so` - Redis caching +- `router.so` - Request routing +- `signer.so` - Message signing +- `signvalidator.so` - Signature validation +- `schemavalidator.so` - JSON schema validation +- `keymanager.so` - Vault integration +- `publisher.so` - RabbitMQ publishing +- `encrypter.so` / `decrypter.so` - Encryption/decryption +- `reqpreprocessor.so` - Request preprocessing + +### Step 5: Setup Redis (Local) + +#### Option A: Using Docker +```bash +docker run -d \ + --name redis-onix \ + -p 6379:6379 \ + redis:alpine +``` + +#### Option B: Native Installation + +**macOS:** +```bash +brew install redis +brew services start redis +``` + +**Ubuntu/Debian:** +```bash +sudo apt update +sudo apt install redis-server +sudo systemctl start redis-server +sudo systemctl enable redis-server +``` + +**Verify Redis:** +```bash +redis-cli ping +# Expected: PONG +``` + +### Step 6: Create Required Directories + +```bash +# Create schemas directory for validation +mkdir -p schemas + +# Create logs directory (optional) +mkdir -p logs +``` + +### Step 7: Configure for Local Development + +Create or modify `config/local-dev.yaml`: + +```yaml +appName: "onix-local" +log: + level: debug + destinations: + - type: stdout + contextKeys: + - transaction_id + - message_id + - subscriber_id + - module_id +http: + port: 8081 + timeout: + read: 30 + write: 30 + idle: 30 +pluginManager: + root: ./plugins +modules: + - name: bapTxnReceiver + path: /bap/receiver/ + handler: + type: std + role: bap + registryUrl: http://localhost:8080/reg + plugins: + cache: + id: cache + config: + addr: localhost:6379 + schemaValidator: + id: schemavalidator + config: + schemaDir: ./schemas + signValidator: + id: signvalidator + router: + id: router + config: + routingConfig: ./config/local-routing.yaml + middleware: + - id: reqpreprocessor + config: + uuidKeys: transaction_id,message_id + role: bap + steps: + - addRoute + - validateSchema + + - name: bapTxnCaller + path: /bap/caller/ + handler: + type: std + role: bap + registryUrl: http://localhost:8080/reg + plugins: + cache: + id: cache + config: + addr: localhost:6379 + router: + id: router + config: + routingConfig: ./config/local-routing.yaml + signer: + id: signer + middleware: + - id: reqpreprocessor + config: + uuidKeys: transaction_id,message_id + role: bap + steps: + - addRoute + - sign + + - name: bppTxnReceiver + path: /bpp/receiver/ + handler: + type: std + role: bpp + registryUrl: http://localhost:8080/reg + plugins: + cache: + id: cache + config: + addr: localhost:6379 + schemaValidator: + id: schemavalidator + config: + schemaDir: ./schemas + signValidator: + id: signvalidator + router: + id: router + config: + routingConfig: ./config/local-routing.yaml + steps: + - validateSign + - addRoute + - validateSchema + + - name: bppTxnCaller + path: /bpp/caller/ + handler: + type: std + role: bpp + registryUrl: http://localhost:8080/reg + plugins: + cache: + id: cache + config: + addr: localhost:6379 + router: + id: router + config: + routingConfig: ./config/local-routing.yaml + signer: + id: signer + steps: + - addRoute + - sign +``` + +### Step 8: Create Routing Configuration + +Create `config/local-routing.yaml`: + +```yaml +routingRules: + - domain: "nic2004:60221" # Mobility domain + version: "0.9.4" + targetType: "url" + target: + url: "http://localhost:9001/beckn" + endpoints: + - search + - select + - init + - confirm + - status + - track + - cancel + - update + - rating + - support + + - domain: "nic2004:52110" # Retail domain + version: "1.0.0" + targetType: "url" + target: + url: "http://localhost:9002/beckn" + endpoints: + - search + - select + - init + - confirm + - status + - track + - cancel + - update + - rating + - support +``` + +### Step 9: Run the Application + +```bash +# Run with local configuration +./server --config=config/local-dev.yaml + +# Or using go run +go run cmd/adapter/main.go --config=config/local-dev.yaml +``` + +The server will start on `http://localhost:8081` + +### Step 10: Verify Setup + +```bash +# Check health endpoint +curl http://localhost:8081/health + +# Check if modules are loaded +curl http://localhost:8081/bap/receiver/ +# Expected: 404 with proper error (means module is loaded) +``` + +--- + +## Production Setup + +### Additional Requirements for Production + +1. **HashiCorp Vault** for key management +2. **RabbitMQ** for message queuing +3. **TLS certificates** for secure communication +4. **Load balancer** for high availability + +### Step 1: Setup HashiCorp Vault + +#### Install Vault +```bash +# Download and install +wget https://releases.hashicorp.com/vault/1.15.0/vault_1.15.0_linux_amd64.zip +unzip vault_1.15.0_linux_amd64.zip +sudo mv vault /usr/local/bin/ +``` + +#### Configure Vault +```bash +# Start Vault in dev mode (for testing only) +vault server -dev -dev-root-token-id="root" + +# In production, use proper configuration +cat > vault-config.hcl < + +# Or use different port in config +``` + +#### 6. Vault Authentication Issues + +**Error**: `vault: authentication failed` + +**Solution**: +```bash +# Check Vault status +vault status + +# Verify authentication +vault login -method=approle \ + role_id=${VAULT_ROLE_ID} \ + secret_id=${VAULT_SECRET_ID} + +# Check policy permissions +vault policy read beckn-policy +``` + +### Debug Mode + +Enable debug logging: + +```yaml +log: + level: debug + destinations: + - type: stdout + config: + pretty: true + includeCalller: true +``` + +Or via environment variable: +```bash +LOG_LEVEL=debug ./server --config=config/adapter.yaml +``` + +### Performance Tuning + +#### System Limits +```bash +# Increase file descriptors +ulimit -n 65536 + +# Add to /etc/security/limits.conf +beckn soft nofile 65536 +beckn hard nofile 65536 +``` + +#### Go Runtime +```bash +# Set GOMAXPROCS +export GOMAXPROCS=8 + +# Enable profiling +./server --config=config/adapter.yaml --profile +``` + +#### Redis Optimization +```bash +# Redis configuration +redis-cli CONFIG SET maxclients 10000 +redis-cli CONFIG SET tcp-keepalive 60 +redis-cli CONFIG SET timeout 300 +``` + +--- + +## Sample Payloads + +### Search Request (Retail) + +```json +{ + "context": { + "domain": "nic2004:52110", + "country": "IND", + "city": "std:080", + "action": "search", + "core_version": "1.0.0", + "bap_id": "buyerapp.com", + "bap_uri": "https://buyerapp.com/beckn", + "transaction_id": "6d5f4c3b-2a1e-4b8c-9f7d-3e2a1b5c8d9f", + "message_id": "a9f8e7d6-c5b4-3a2e-1f0d-9e8c7b6a5d4f", + "timestamp": "2024-01-15T10:30:00.000Z", + "ttl": "PT30S" + }, + "message": { + "intent": { + "item": { + "descriptor": { + "name": "Laptop" + } + }, + "fulfillment": { + "type": "Delivery", + "end": { + "location": { + "gps": "12.9715987,77.5945627", + "area_code": "560001" + } + } + }, + "payment": { + "buyer_app_finder_fee_type": "percent", + "buyer_app_finder_fee_amount": "3" + } + } + } +} +``` + +### Select Request + +```json +{ + "context": { + "domain": "nic2004:52110", + "country": "IND", + "city": "std:080", + "action": "select", + "core_version": "1.0.0", + "bap_id": "buyerapp.com", + "bap_uri": "https://buyerapp.com/beckn", + "bpp_id": "sellerapp.com", + "bpp_uri": "https://sellerapp.com/beckn", + "transaction_id": "6d5f4c3b-2a1e-4b8c-9f7d-3e2a1b5c8d9f", + "message_id": "b8e7f6d5-c4a3-2b1e-0f9d-8e7c6b5a4d3f", + "timestamp": "2024-01-15T10:31:00.000Z", + "ttl": "PT30S" + }, + "message": { + "order": { + "provider": { + "id": "P1", + "locations": [ + { + "id": "L1" + } + ] + }, + "items": [ + { + "id": "I1", + "quantity": { + "count": 2 + } + } + ], + "fulfillment": { + "end": { + "location": { + "gps": "12.9715987,77.5945627", + "address": { + "door": "21A", + "name": "ABC Apartments", + "building": "Tower 1", + "street": "100 Feet Road", + "locality": "Indiranagar", + "city": "Bengaluru", + "state": "Karnataka", + "country": "India", + "area_code": "560001" + } + }, + "contact": { + "phone": "9876543210", + "email": "customer@example.com" + } + } + } + } + } +} +``` + +### Init Request + +```json +{ + "context": { + "domain": "nic2004:52110", + "country": "IND", + "city": "std:080", + "action": "init", + "core_version": "1.0.0", + "bap_id": "buyerapp.com", + "bap_uri": "https://buyerapp.com/beckn", + "bpp_id": "sellerapp.com", + "bpp_uri": "https://sellerapp.com/beckn", + "transaction_id": "6d5f4c3b-2a1e-4b8c-9f7d-3e2a1b5c8d9f", + "message_id": "c7f6e5d4-b3a2-1e0f-9d8e-7c6b5a4d3e2f", + "timestamp": "2024-01-15T10:32:00.000Z", + "ttl": "PT30S" + }, + "message": { + "order": { + "provider": { + "id": "P1", + "locations": [ + { + "id": "L1" + } + ] + }, + "items": [ + { + "id": "I1", + "quantity": { + "count": 2 + }, + "fulfillment_id": "F1" + } + ], + "billing": { + "name": "John Doe", + "address": { + "door": "21A", + "name": "ABC Apartments", + "building": "Tower 1", + "street": "100 Feet Road", + "locality": "Indiranagar", + "city": "Bengaluru", + "state": "Karnataka", + "country": "India", + "area_code": "560001" + }, + "email": "john.doe@example.com", + "phone": "9876543210", + "created_at": "2024-01-15T10:32:00.000Z", + "updated_at": "2024-01-15T10:32:00.000Z" + }, + "fulfillment": { + "id": "F1", + "type": "Delivery", + "tracking": false, + "end": { + "location": { + "gps": "12.9715987,77.5945627", + "address": { + "door": "21A", + "name": "ABC Apartments", + "building": "Tower 1", + "street": "100 Feet Road", + "locality": "Indiranagar", + "city": "Bengaluru", + "state": "Karnataka", + "country": "India", + "area_code": "560001" + } + }, + "contact": { + "phone": "9876543210", + "email": "customer@example.com" + } + } + }, + "payment": { + "type": "ON-ORDER", + "collected_by": "BAP", + "buyer_app_finder_fee_type": "percent", + "buyer_app_finder_fee_amount": "3", + "settlement_details": [ + { + "settlement_counterparty": "seller-app", + "settlement_phase": "sale-amount", + "settlement_type": "neft", + "settlement_bank_account_no": "1234567890", + "settlement_ifsc_code": "SBIN0001234", + "beneficiary_name": "Seller Name", + "bank_name": "State Bank of India", + "branch_name": "Koramangala" + } + ] + } + } + } +} +``` + +### Confirm Request + +```json +{ + "context": { + "domain": "nic2004:52110", + "country": "IND", + "city": "std:080", + "action": "confirm", + "core_version": "1.0.0", + "bap_id": "buyerapp.com", + "bap_uri": "https://buyerapp.com/beckn", + "bpp_id": "sellerapp.com", + "bpp_uri": "https://sellerapp.com/beckn", + "transaction_id": "6d5f4c3b-2a1e-4b8c-9f7d-3e2a1b5c8d9f", + "message_id": "d8f7e6d5-c4b3-2a1e-0f9d-8e7c6b5a4d3f", + "timestamp": "2024-01-15T10:33:00.000Z", + "ttl": "PT30S" + }, + "message": { + "order": { + "id": "ORDER123", + "state": "Created", + "provider": { + "id": "P1", + "locations": [ + { + "id": "L1" + } + ] + }, + "items": [ + { + "id": "I1", + "fulfillment_id": "F1", + "quantity": { + "count": 2 + } + } + ], + "quote": { + "price": { + "currency": "INR", + "value": "4000" + }, + "breakup": [ + { + "item_id": "I1", + "item_quantity": { + "count": 2 + }, + "title_type": "item", + "title": "Laptop", + "price": { + "currency": "INR", + "value": "3800" + } + }, + { + "item_id": "F1", + "title_type": "delivery", + "title": "Delivery charges", + "price": { + "currency": "INR", + "value": "100" + } + }, + { + "item_id": "F1", + "title_type": "packing", + "title": "Packing charges", + "price": { + "currency": "INR", + "value": "50" + } + }, + { + "item_id": "I1", + "title_type": "tax", + "title": "Tax", + "price": { + "currency": "INR", + "value": "50" + } + } + ], + "ttl": "P1D" + }, + "payment": { + "uri": "https://ondc.transaction.com/payment", + "tl_method": "http/get", + "params": { + "transaction_id": "TXN123456", + "amount": "4000", + "currency": "INR" + }, + "type": "ON-ORDER", + "status": "PAID", + "collected_by": "BAP", + "buyer_app_finder_fee_type": "percent", + "buyer_app_finder_fee_amount": "3", + "settlement_details": [ + { + "settlement_counterparty": "seller-app", + "settlement_phase": "sale-amount", + "settlement_type": "neft", + "settlement_bank_account_no": "1234567890", + "settlement_ifsc_code": "SBIN0001234", + "beneficiary_name": "Seller Name", + "bank_name": "State Bank of India", + "branch_name": "Koramangala" + } + ] + }, + "fulfillment": { + "id": "F1", + "type": "Delivery", + "tracking": true, + "start": { + "location": { + "id": "L1", + "descriptor": { + "name": "Seller Store" + }, + "gps": "12.9715987,77.5945627", + "address": { + "locality": "Koramangala", + "city": "Bengaluru", + "area_code": "560034", + "state": "Karnataka" + } + }, + "time": { + "range": { + "start": "2024-01-15T11:00:00.000Z", + "end": "2024-01-15T12:00:00.000Z" + } + }, + "contact": { + "phone": "9988776655", + "email": "seller@example.com" + } + }, + "end": { + "location": { + "gps": "12.9715987,77.5945627", + "address": { + "door": "21A", + "name": "ABC Apartments", + "building": "Tower 1", + "street": "100 Feet Road", + "locality": "Indiranagar", + "city": "Bengaluru", + "state": "Karnataka", + "country": "India", + "area_code": "560001" + } + }, + "time": { + "range": { + "start": "2024-01-15T14:00:00.000Z", + "end": "2024-01-15T18:00:00.000Z" + } + }, + "person": { + "name": "John Doe" + }, + "contact": { + "phone": "9876543210", + "email": "customer@example.com" + } + } + }, + "created_at": "2024-01-15T10:33:00.000Z", + "updated_at": "2024-01-15T10:33:00.000Z" + } + } +} +``` + +### Authorization Header Structure + +All requests must include proper authorization: + +``` +Authorization: Signature keyId="{subscriber_id}|{key_id}|{algorithm}",algorithm="{algorithm}",created="{created}",expires="{expires}",headers="(created) (expires) digest",signature="{base64_signature}" +``` + +Example generation in bash: +```bash +#!/bin/bash + +# Variables +SUBSCRIBER_ID="buyerapp.com" +KEY_ID="key1" +ALGORITHM="ed25519" +CREATED=$(date +%s) +EXPIRES=$((CREATED + 300)) +PRIVATE_KEY="path/to/private_key.pem" + +# Create string to sign +STRING_TO_SIGN="(created): ${CREATED} +(expires): ${EXPIRES} +digest: SHA-256=${DIGEST}" + +# Sign with Ed25519 +SIGNATURE=$(echo -n "$STRING_TO_SIGN" | \ + openssl pkeyutl -sign -inkey $PRIVATE_KEY -rawin | \ + base64 -w 0) + +# Create header +AUTH_HEADER="Signature keyId=\"${SUBSCRIBER_ID}|${KEY_ID}|${ALGORITHM}\",algorithm=\"${ALGORITHM}\",created=\"${CREATED}\",expires=\"${EXPIRES}\",headers=\"(created) (expires) digest\",signature=\"${SIGNATURE}\"" + +echo $AUTH_HEADER +``` + +--- + +## Conclusion + +This setup guide covers all aspects of deploying Beckn-ONIX from local development to production. Key points: + +1. **Start Simple**: Begin with local development setup +2. **Test Thoroughly**: Use provided test scripts and payloads +3. **Scale Gradually**: Move from single instance to clustered deployment +4. **Monitor Continuously**: Use logs and metrics for observability +5. **Secure Always**: Implement proper authentication and encryption + +For additional help: +- Check [GitHub Issues](https://github.com/beckn/beckn-onix/issues) +- Join [Community Discussions](https://github.com/beckn/beckn-onix/discussions) +- Review [API Documentation](https://docs.beckn.org) + +Happy deploying! 🚀 \ No newline at end of file