BPP - Installing Protocol Server

UBI NETWORK GUIDE FOR INSTALLING PROTOCOL SERVER (BPP)

Installation of Beckn Protocol Adapter using BecknOnix Version 1.0

Once you have gone through all the information and documentation and have enough clarity, the next step is to install and set up the Beckn Protocol server. The installation and setup of Beckn Protocol server using Beckn-Onix is the suggested/recommended way before you can transact over the network.

Onboarding using a use case scenario (an Example Usecase)

The organization - FinAidIndia wants to onboard the UBI network as a Financial/Scholarship provider. By onboarding on to the UBI Network their services will be discoverable to all the beneficiaries (seekers) on the network.

The onboarding process includes:

1. Reading and understanding the documentation for the understanding of the specs, apis etc..

2. Preparing infrastructure and other prerequisites

3. Registering on to the UBI Sandbox

4. Installing the Beckn Onix

5. Setting up Webhook

6. Creating the provider modules to host the Beckn endpoint and accept and process incoming requests and send back the responses

1. Pre-Requisites

1	Virtual Servers	Provision cloud instances (e.g., AWS EC2). Ensure you have SSH administrator access. Configuration: 2 VCPS, 4GB RAM (minimum), 50GB Minimum NOTE:- Use AMD64 based architecture machine
2	Operating System	Supported and Tested OS: Ubuntu 20.04 / 22.04 /24.04 Debian 12 Amazon Linux 2
3	Docker	Latest Docker version Recommended. Minimum Version 18
4	Domain	For the Provider Platform (BPP) FinAidIndia, you’ll need two domains (or subdomains): Client Endpoint (BPP Client) This is where your internal client application connects. Example: https://finaidindia-bpp-client.org Network Endpoint (BPP Network) This is the public-facing endpoint through which the Beckn network will reach your BPP. Example: https://finaidindia-bpp-network.org IMP. Both domains must be publicly accessible, have SSL certificates, and be configured with NGINX reverse proxy.
5	SSL Certificates	Every Beckn endpoint must be secured with HTTPS. Obtain valid SSL certificates for your chosen domains (e.g., from Let’s Encrypt or your CA) and install them on the server.
6	NGINX Reverse Proxy	Use Nginx as a reverse proxy to route incoming HTTPS requests from the Beckn network to your BPP adapter or webhook service. (In most cases, your DevOps team will handle this configuration.)

2. Self-Registering on to the UBI Registry

Before you can install and configure your BPP (Provider Platform) with Beckn Onix, you must register yourself in the UBI Sandbox Registry.

This step is mandatory because the username and password you create here will be required during the installation process.

🔑 Steps to Register

1. Open the UBI Sandbox Registry portal: https://registry-sandbox.the-ubi.io

1. On the login page, click “I am a New User”. Enter a Username and Password of your choice, then complete the registration.

⚠️ Important Note

✅ Make sure to note down these credentials safely – you’ll need them later when running the installation

1. You can verify the registration by logging into the registry using this newly created username and password

3. BPP - installation of BPP Protocol server using BecknOnix

After completing the prerequisites and registry self-registration, the next step is to set up the BPP Protocol Server.

This server acts as the bridge between your application (FinAidIndia in our example) and the Beckn network, handling all network requests like search, select, confirm, and sending back the corresponding responses (on_search, on_select, etc.).

Beckn Onix provides an installer script that simplifies the entire setup. With just a few commands, you can:

• Download and configure the protocol server

• Register your BPP with the chosen network registry

• Link your webhook/application endpoints with the Beckn ecosystem

In the following steps, we’ll walk through the hands-on process to install the BPP protocol server for FinAidIndia.

4. Step-by-Step Installation of BPP Protocol Server (Beckn Onix v1.0)

⚠️ Important Note

✅ Make sure you have completed all the steps in the Prerequisites section before starting installation.

🔄 Beckn Onix has a newer version with a completely different architecture. Since that release is still under evaluation, this guide covers Beckn Onix v1.0 only.

📥 Clone the Repository (Specific Branch) Clone Beckn Onix v1.0

git clone https://github.com/Beckn-One/beckn-onix.git

#Move into the repo folder
cd beckn-onix

# Switch to the desired branch
git checkout fix/beckn-onix-typo

Run the Installation Script

# Go to the install folder
cd install
./beckn-onix.sh

You’ll be prompted for several inputs.

Select “1” for as you want to join an existing network (UBI in this case) and press Enter

Please select a Participant Type. Since you are a provider , select BPP in this case) and press Enter

Enter Subscriber ID (Enter the Subscriber Id. Generally this will be your URL without http. ) And Subscriber URL - this will be the network URL. (Please refer to the pre-requisite section if required for details)

Enter Webhook URL. Note: The webhook is a service endpoint that connects your BPP Protocol Server (Beckn Onix) with your actual provider application code.

• In simple terms: all incoming Beckn requests (search, select, etc.) will be forwarded by the protocol server to this webhook, and the webhook will respond back to the network.

How to provide the URL:

• ✅ If your webhook service runs on the same server as your BPP, you can use the IP address of the server.

• ✅ If your webhook is hosted elsewhere, enter the full URL (e.g., https://api.finaidindia.com/webhook).

• ⚠️ If your webhook is not ready yet, don’t worry — you can provide any placeholder IP address for now. Later, you can update the correct URL in the config file after installation.This way, even if your webhook isn’t live at installation time, you won’t be blocked — you can always configure it later.

Enter the Registry URL as shown below. The registry url for UBI is https://registry-sandbox.the-ubi.io/subscribers

Registry Username/Password Note: Use the same credentials you created during self-registration.

⚠️ Note: If prompted for “select a domain” or “install layer2 config”, simply skip/ignore and continue.

Now, this will start installing the protocol server and various dependencies

Once Done you will see a BPP installation Successful Message as shown in the below log

Verify the Installation You can verify the installation by using the docker command. You should see services like bpp-adapter, beckn-protocol-server, etc.

docker ps -a

Verify Registry You can also verify that there is an entry for your domain that is created in the registry with keys etc.. by login in to the registry using the username and password created

Activate your entry in the Registry by changing the status from “INITIATED” to “SUBSCRIBED”. Pls follow the steps below for the same Edit your entry in registry Select “Network Role” Click on the pencil to edit

Activate your entry in the Registry by changing the status from “INITIATED” to “SUBSCRIBED”.

Edit the “Network Domain” and select “UBI Financial Support” as the domain and Save the changes

Protocol Server Installed Successfully !

With the above steps, you have now successfully installed the BPP Protocol Server for FinAidIndia.

By default: BPP Client will be running on port 6001 BPP Network will be running on port 6002

You can verify that the containers are running using:

docker ps

5. Nginx Configuration (with SSL)

As part of the prerequisites, you should already have configured Nginx for both: The Client domain → https://finaidindia-bpp-client.org The Network domain → https://finaidindia-bpp-network.org

Your SSL certificates should also be attached to these domains.

Below is a sample Nginx configuration (before SSL blocks are added) for your reference. This can change as per your network settings/requirements

Client Config (Port 6001)

server {
listen 80;
server_name finaidindia-bpp-client.org;
location / {
proxy_pass http://127.0.0.1:6001; # Update port if different
proxy_http_version 1.1;
proxy_set_header Host $host;
proxy_set_header X-Real-IP $remote_addr;
proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
proxy_set_header X-Forwarded-Proto $scheme;
client_max_body_size 30m;
proxy_read_timeout 700s;
}
}

Network Config (Port 6002)

server {
listen 80;
server_name finaidindia-bpp-network.org;
location / {
resolver 1.1.1.1 ipv6=off;
proxy_pass http://127.0.0.1:6002/;
client_max_body_size 30m;
proxy_read_timeout 700s;
proxy_set_header Host $host;
proxy_set_header X-Real-IP $remote_addr;
proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
proxy_set_header X-Forwarded-Proto $scheme;
proxy_set_header Connection "";
proxy_buffer_size 128k;
proxy_buffers 4 256k;
proxy_busy_buffers_size 256k;
proxy_headers_hash_max_size 1024;
proxy_headers_hash_bucket_size 512;
}
}

Testing Your Setup

Once you add your SSL certificate, these blocks will be updated with
listen 443 ssl;
and the certificate paths (ssl_certificate and ssl_certificate_key).
To Test
After finishing Nginx and SSL configuration, test that your services are running correctly:
# Test the local ports
curl http://localhost:6001
curl http://localhost:6002
# Test via your domains (with SSL enabled)
curl -k https://finaidindia-bpp-client.org
curl -k https://finaidindia-bpp-network.org
If you see a response (even an empty JSON), your BPP Protocol Server and Nginx setup are working correctly.

6. Reference Webhook

The Webhook is a service endpoint that connects your BPP Protocol Server (Beckn Onix) with your provider’s application code.

In simple words: The protocol server receives incoming Beckn requests (search, select, etc.)

• It forwards them to the webhook

• The webhook then communicates with your provider app and sends back the appropriate on_search, on_select, etc. responses

Normally, providers are expected to write their own webhook code. However, Beckn also provides a reference webhook implementation you can use if you don’t want to build one from scratch.

🛠 Steps to Set Up the Reference Webhook

Clone the repository

git clone https://github.com/beckn/integration-webhook.git

Check out the correct commit

git checkout -b ubi-webhook 9501802
(Here ubi-webhook is your new branch name; you can choose a different one if you like.)

Install dependencies and start the webhook

npm install
npm run dev

By default, the webhook will start on port 3000 of your server.

🔧 Configure the Webhook URL in BPP Client

Now you need to tell your BPP Client where this webhook is running. Update the default.yaml configuration:

# Open a shell into the bpp-client container

docker exec -it bpp-client sh

# Edit the config file

vi config/default.yaml

Find the webhook URL field and update it,

for example: webhook_url: "http://<server_ip>:3000"

Replace <server_ip> with the actual IP address or domain of your server.

Save the file and restart the container if needed.

At this point, your protocol server will forward incoming Beckn requests to the reference webhook, which you can test and extend as per your provider needs.

7. Enabling Layer 2 Config in Beckn

In the Beckn ecosystem, the Layer 2 config allows network specific schema customization in case required. Basically It allows you to extend the base schema with network-specific configurations.

The Layer 2 config must be present in the schemas/ folder of both the client and network containers of your protocol server (BAP or BPP).

The filename should match the domain name of the network. For example:

• Domain → ubi:financial-support

• Config file → ubi_financial-support_1.1.0.yaml

Steps to Enable Layer 2 Config

Step 1. Enter the Docker container

Run the following for each container (client and network):

docker exec -it <bap-or-bpp>-<client-or-network> sh

Example for a BAP client:

docker exec -it bap-client sh

Step 2. Go to the schemas folder

cd schemas

Step 3. Copy the Core Schema and Rename Duplicate the base schema file (core_1.1.0.yaml) and rename it to match your network domain.

cp core_1.1.0.yaml ubi_financial-support_1.1.0.yaml

This new file will act as the Layer 2 config, where the network-specific rules can be added.

Step 4. Repeat for All Containers

Do the same in:

• bap-client

• Bap-network

• (or bpp-client and bpp-network if you’re setting up a BPP).

Step 5. Restart the Containers

Once the Layer 2 config files are created, exit the container and restart both client and network containers one by one:

Example:

Restart the Containers

docker restart bap-client
docker restart bap-network