ankitjh4/ondc-buyer

ONDC Buyer Skill

This skill helps you deploy and manage ONDC (Open Network for Digital Commerce) buyer applications. ONDC is India's digital commerce network enabling buyers to discover and purchase from sellers across multiple platforms.

What This Skill Does

• Deploy ONDC Buyer Apps: Set up the complete buyer reference application
• Product Discovery: Search and browse products across ONDC network
• Shopping Cart: Manage cart, apply customizations, and handle variants
• Checkout Flow: Handle select, init, confirm, and payment flows
• Order Tracking: Track orders in real-time with GPS/URL-based tracking
• Returns & Cancellations: Process returns, cancellations, and refunds
• IGM Support: File and track issues/complaints with sellers

Architecture Overview

The ONDC Buyer App uses microservice architecture:

• biap-client-node-js: Node.js backend API layer
• biap-app-ui-front: React web application (served via nginx)
• py-ondc-protocol: Python protocol layer for ONDC communication
• biap-igm-node-js: Node.js IGM service for issue management
• biap-bugzilla-service: Bugzilla integration for ticket management
• catalog-service: Catalog indexing and search service

Prerequisites

Before using this skill, ensure you have:

1. Docker & Docker Compose installed
2. Git with submodule support
3. Domain name or ngrok for public endpoint
4. Required service accounts:
   • Firebase (authentication)
   • Juspay or other payment gateway
   • Map My India (location services)
5. MongoDB (included in docker-compose)
6. ONDC Registry Access (for production deployment)

Quick Start

1. Clone and Initialize

cd /home/workspace
git clone https://github.com/ONDC-Official/ondc-sdk.git ondc-buyer-app
cd ondc-buyer-app
git submodule init
git submodule update

2. Generate Cryptographic Keys

bun /home/workspace/Skills/ondc-buyer/scripts/generate-keys.ts

This creates signing and encryption keys required for ONDC registration.

3. Configure Environment

bun /home/workspace/Skills/ondc-buyer/scripts/setup-env.ts \
  --domain "https://buyerapp.example.com" \
  --firebase-key "YOUR_KEY" \
  --juspay-merchant-id "MERCHANT_ID" \
  --mmi-client-id "MMI_CLIENT"

4. Deploy Locally (Development)

cd /home/workspace/ondc-buyer-app
docker-compose -f docker-compose-for-local.yaml --env-file .env-local up -d

Access the app at http://localhost (or your configured domain).

5. Register with ONDC

Once deployed, use the registration helper:

bun /home/workspace/Skills/ondc-buyer/scripts/register.ts \
  --subscriber-url "https://buyerapp.example.com" \
  --signing-key "path/to/signing_public.pem" \
  --crypto-key "path/to/crypto_public.pem"

Common Operations

Check Application Status

bun /home/workspace/Skills/ondc-buyer/scripts/check-status.ts

Shows the status of all services (client, frontend, protocol, IGM, catalog).

Search Products

# Search across ONDC network
bun /home/workspace/Skills/ondc-buyer/scripts/search.ts --query "smartphones" --city "Bangalore"

# Search by category
bun /home/workspace/Skills/ondc-buyer/scripts/search.ts --category "Grocery" --location "110001"

# Get provider details
bun /home/workspace/Skills/ondc-buyer/scripts/search.ts --provider-id "PROVIDER123"

Manage Orders

# List user orders
bun /home/workspace/Skills/ondc-buyer/scripts/view-orders.ts --user-id "USER123" --limit 10

# Get order details and tracking
bun /home/workspace/Skills/ondc-buyer/scripts/view-orders.ts --order-id "ORDER456"

# Track order status
bun /home/workspace/Skills/ondc-buyer/scripts/track-order.ts --order-id "ORDER456"

Handle Returns & Cancellations

# Initiate cancellation
bun /home/workspace/Skills/ondc-buyer/scripts/cancel-order.ts --order-id "ORDER789" --reason "Changed mind"

# Request return
bun /home/workspace/Skills/ondc-buyer/scripts/return-order.ts --order-id "ORDER789" --items "ITEM1,ITEM2"

# Check cancellation status
bun /home/workspace/Skills/ondc-buyer/scripts/check-cancellation.ts --order-id "ORDER789"

Manage IGM Issues

# List user issues
bun /home/workspace/Skills/ondc-buyer/scripts/manage-igm.ts --action list --user-id "USER123"

# File new issue
bun /home/workspace/Skills/ondc-buyer/scripts/manage-igm.ts --action create \
  --order-id "ORDER123" \
  --type "PRODUCT_QUALITY" \
  --description "Product damaged"

# Track issue status
bun /home/workspace/Skills/ondc-buyer/scripts/manage-igm.ts --action track --issue-id "IGM456"

Environment Variables

Key environment variables required (store in Settings > Advanced):

# ONDC Registry
BAP_URL="https://buyerapp.example.com"
BAP_ID="buyerapp.example.com"
BAP_PRIVATE_KEY="signing_private_key"
BAP_PUBLIC_KEY="signing_public_key"
BAP_UNIQUE_KEY_ID="unique_key_id_from_registry"

# Firebase Auth
FIREBASE_ADMIN_SERVICE_ACCOUNT="/path/to/firebase-service-account.json"
REACT_APP_FIREBASE_API_KEY="firebase_api_key"
REACT_APP_FIREBASE_AUTH_DOMAIN="buyerapp.example.com"

# Juspay Payment Gateway
JUSPAY_SECRET_KEY_PATH="/path/to/juspay-creds.pem"
JUSPAY_BASE_URL="https://sandbox.juspay.in"
JUSPAY_MERCHANT_ID="merchant_id"
JUSPAY_API_KEY="access_key"
JUSPAY_WEBHOOK_USERNAME="webhook_user"
JUSPAY_WEBHOOK_PASSWORD="webhook_pass"

# Web App Payment Config
REACT_APP_JUSTPAY_CLIENT_AND_MERCHANT_KEY="merchant_id"
REACT_APP_MERCHANT_KEY_ID="merchant_id"
REACT_APP_PAYMENT_SDK_ENV="sandbox"
REACT_APP_PAYMENT_SERVICE_URL="https://api.juspay.in"

# Map My India
MMI_CLIENT_SECRET="mmi_secret"
MMI_CLIENT_ID="mmi_client_id"
MMI_ADVANCE_API_KEY="mmi_api_key"

# MongoDB
MONGO_DB_URL="mongodb://mongo:27017/ondc"

Feature Support Matrix

The ONDC Buyer App implements ONDC Retail v1.2 specification:

| Feature | Status | |---------|--------| | Incremental catalog refresh | ✅ Available | | Full catalog refresh | ✅ Available | | Product search & discovery | ✅ Available | | Shopping cart management | ✅ Available | | Checkout flow (select/init/confirm) | ✅ Available | | Payment integration (Juspay) | ✅ Available | | Order tracking (GPS-based) | ✅ Available | | Live order tracking | ✅ Available | | Customization (selection) | ✅ Available | | Variants support | ✅ Available | | Return with liquidation | ✅ Available | | Cancellation flows | ✅ Available | | RTO (Return to Origin) | ✅ Available | | IGM issue management | ✅ Available | | Order history | ✅ Available | | Multi-store cart | ✅ Available | | Address management | ✅ Available | | Customization (free text) | 📅 Future scope | | Subscription orders | 📅 Future scope | | Offers & discounts | 📅 Future scope |

Payment Gateway Integration

Juspay Setup

1. Create account at https://dashboard.juspay.in
2. Generate API credentials from console
3. Download merchant certificate (.pem file)
4. Configure environment variables
5. Set up webhook endpoints for payment callbacks

Alternative Payment Gateways

To integrate other payment gateways (Razorpay, Paytm, etc.):

# Modify payment service integration
vim /home/workspace/ondc-buyer-app/biap-client-node-js/src/payment/

Update the payment service to match your gateway's API.

Map My India Integration

MMI provides:

• Address autocomplete
• PIN code lookup
• State/city detection
• Geocoding (lat/long from address)

Required APIs:

• https://outpost.mapmyindia.com/api - Authentication
• https://atlas.mapmyindia.com/api/places/search/json - Search
• https://explore.mappls.com - Explore places
• https://apis.mapmyindia.com/advancedmaps/v1 - Advanced mapping
• https://atlas.mappls.com/api/places/geocode - Geocoding

Bugzilla Setup (Optional)

For IGM ticket management:

1. After deployment, visit https://yourdomain.com/bugzilla/admin
2. Login with username admin and password password
3. Configure SMTP settings for email notifications
4. Generate API key from dashboard
5. Add BUGZILLA_API_KEY to environment variables
6. Restart bugzilla container

Note: Bugzilla is optional but recommended for full IGM functionality.

Troubleshooting

Services Not Starting

# Check logs
docker logs ondc-buyer-client
docker logs ondc-buyer-frontend
docker logs ondc-buyer-protocol
docker logs ondc-catalog-service

# Restart specific service
docker-compose restart biap-client-node-js

Search Not Working

• Verify protocol layer is running
• Check ONDC registry connectivity
• Review /search request/response logs
• Ensure catalog service is indexed

Payment Failures

• Verify Juspay credentials
• Check webhook configuration
• Review payment service logs
• Test with Juspay sandbox first

Order Tracking Issues

• Confirm seller provides tracking URLs
• Check GPS coordinate format
• Verify /track endpoint responses
• Review order status updates

Security Notes

• Store all secrets in Zo's Settings > Advanced
• Never commit .env files or credentials to version control
• Use HTTPS for all endpoints
• Implement rate limiting on public APIs
• Validate payment webhook signatures
• Sanitize user inputs
• Regular security audits

Deployment Options

Local Development (with ngrok)

# Install ngrok
brew install --cask ngrok

# Start tunnel
ngrok http 5555

# Use ngrok URL in BAP_URL and PROTOCOL_BASE_URL

Production Deployment (with SSL)

# Use docker-compose with SSL
docker-compose -f docker-compose.yaml --env-file .env-prod up -d

# Initialize Let's Encrypt
./init-letsencrypt.sh

Ansible Deployment

cd deploying_ansible
ansible-playbook -i ansible_hosts buyer-app-install-for-ssl.yaml
ansible-playbook -i ansible_hosts buyer-app-run.yaml

References

See the references/ folder for:

• ONDC API Contract v1.2 documentation
• Buyer app user manual
• Feature implementation guide
• Integration requirements
• Payment gateway setup guides

Support

• ONDC Documentation: https://docs.ondc.org
• Buyer App Repo: https://github.com/ONDC-Official/ondc-sdk
• ONDC Slack: https://witsinnovationlab.slack.com/archives/C0280AR5CUQ
• Registry Form: https://forms.gle/registrationform
• Juspay Docs: https://developer.juspay.in

When to Use This Skill

Use this skill when you need to:

• Deploy an ONDC-compliant buyer application
• Build a consumer-facing shopping experience on ONDC
• Integrate payment gateways with ONDC flows
• Implement product search and discovery
• Handle end-to-end order management
• Process returns and cancellations
• File and track customer issues (IGM)
• Scale buyer operations across India