ONDC Buyer App Utility APIsVersion 1.0.0

Relay Server Setup (Node.js + Express)

This sample demonstrates a lightweight relay server that forwards requests to ONDC BAP endpoints with the required authentication headers.

import express from "express"

const app = express()
const port = 3000

// Base URL of the ONDC BAP catalogue APIs
const bapRelayBase = "{{base_url}}/catalogue"

// API Key provided for ONDC authentication
const API_KEY = "API_KEY"

app.use(express.json())

/**
 * Generic relay handler
 * Example:
 *   GET  /search  ->  /catalogue/search
 *   POST  /search     ->  /catalogue/search
 */
app.use("/:action", async (req, res) => {
  try {
    const relayResponse = await fetch(
      `${bapRelayBase}/${req.params.action}`,
      {
        method: req.method,
        headers: {
          "Content-Type": "application/json",
          "X-API-KEY": API_KEY,
        },
        body:
          req.method !== "GET"
            ? JSON.stringify(req.body)
            : undefined,
      }
    )

    const contentType = relayResponse.headers.get("content-type")

    if (contentType && contentType.includes("application/json")) {
      const json = await relayResponse.json()
      res.status(relayResponse.status).json(json)
    } else {
      const text = await relayResponse.text()
      res.status(relayResponse.status).send(text)
    }
  } catch (error) {
    res.status(500).json({
      error: true,
      message: "Relay server error",
    })
  }
})

app.listen(port, () => {
  console.log(`ONDC relay server running on port ${port}`)
})

Relay Implementation Notes

• Replace API_KEY with the key provided by the integration team.
• Update bapRelayBase to match the ONDC endpoint you are relaying to.
• Supports POST-based BAP callbacks such as search, select, init, and confirm.
• You may extend this logic to support query parameters, additional HTTP methods, and custom routing.

Encryption & Decryption (TypeScript)

ONDC responses are encrypted using AES-256-CBC. Use the following utility functions to encrypt outgoing data and decrypt API responses.

import crypto from "crypto"

interface TransactionData {
  transactionId: string
  companyOrderId: string
}

/**
 * Decrypt encrypted ONDC responses
 */
export function decryptResponse(
  encryptedData: string,
  iv: string,
  key: Buffer
) {
  const decipher = crypto.createDecipheriv(
    "aes-256-cbc",
    key,
    Buffer.from(iv, "hex")
  )

  let decrypted = decipher.update(encryptedData, "base64", "utf8")
  decrypted += decipher.final("utf8")

  return JSON.parse(decrypted)
}

/**
 * Encrypt request payload before sending to ONDC
 */
export function encryptRequest(
  data: TransactionData,
  key: Buffer,
  iv: Buffer
) {
  const cipher = crypto.createCipheriv("aes-256-cbc", key, iv)

  const jsonData = JSON.stringify(data)
  let encrypted = cipher.update(jsonData, "utf8", "base64")
  encrypted += cipher.final("base64")

  return encrypted
}

Encryption Requirements

• Encryption Algorithm: AES-256-CBC
• Key: 32-byte hexadecimal string
• IV: 16-byte hexadecimal value provided with the response
• Use decryptResponse to process encrypted API payloads.
• Use encryptResponse to encrypt transaction data before placing orders.

Decryption Code (Go)

Use the following Go code snippet to decrypt ONDC responses using the providediv and your 32-byte encryption key. Thedata field in the response contains the encrypted payload, which must be decrypted to access the quote details.

package main

import (
	"crypto/aes"
	"crypto/cipher"
	"encoding/base64"
	"fmt"
)

// AES256CBCDecrypt decrypts data using AES-256-CBC.
func AES256CBCDecrypt(data, key, iv string) (string, error) {
	// Decode base64 encoded data
	ciphertext, err := base64.StdEncoding.DecodeString(data)
	if err != nil {
		return "", fmt.Errorf("failed to decode base64 data: %v", err)
	}

	// Convert key and IV from strings to byte slices
	keyBytes := []byte(key)
	ivBytes := []byte(iv)

	// Validate key length for AES-256
	if len(keyBytes) != 32 {
		return "", fmt.Errorf("invalid key length: expected 32 bytes for AES-256, got %d", len(keyBytes))
	}

	// Validate IV length
	if len(ivBytes) != aes.BlockSize {
		return "", fmt.Errorf("invalid IV length: expected %d bytes, got %d", aes.BlockSize, len(ivBytes))
	}

	// Create AES cipher block
	block, err := aes.NewCipher(keyBytes)
	if err != nil {
		return "", fmt.Errorf("failed to create AES cipher: %v", err)
	}

	// Create CBC decrypter
	mode := cipher.NewCBCDecrypter(block, ivBytes)

	// Decrypt the ciphertext
	plaintext := make([]byte, len(ciphertext))
	mode.CryptBlocks(plaintext, ciphertext)

	// Remove PKCS#7 padding
	plaintext, err = pkcs7Unpad(plaintext, aes.BlockSize)
	if err != nil {
		return "", fmt.Errorf("failed to unpad plaintext: %v", err)
	}

	return string(plaintext), nil
}

// pkcs7Unpad removes PKCS#7 padding from decrypted text
func pkcs7Unpad(data []byte, blockSize int) ([]byte, error) {
	length := len(data)
	if length == 0 {
		return nil, fmt.Errorf("data is empty")
	}

	padding := int(data[length-1])
	if padding > blockSize || padding == 0 {
		return nil, fmt.Errorf("invalid padding")
	}

	for i := 0; i < padding; i++ {
		if data[length-1-i] != byte(padding) {
			return nil, fmt.Errorf("invalid padding bytes")
		}
	}

	return data[:length-padding], nil
}

func main() {
	// Example usage
	data := "__ENCRYPTED__STRING__HERE__"
	key := "__KEY__HERE__"
	iv := "__IV__HERE__"

	decrypted, err := AES256CBCDecrypt(data, key, iv)
	if err != nil {
		fmt.Println("Error:", err)
		return
	}

	fmt.Println("Decrypted text:", decrypted)
}

Security Best Practices

Ensure API keys and encryption keys are securely stored and never exposed in client-side applications. Always encrypt sensitive payloads and validate incoming data to prevent unauthorized access.

Integration Support

For assistance during integration, contact at help@meribachat.in.