Option 2: Manual setup

Prerequisites

• Node.js v18.x or later

• PostgreSQL 15 database

• Blockfrost API Key (to interact with the Cardano blockchain)

---

The node consists of two different repositories. We start with the Payment Service, which is key to getting started.

The Registry Service is not required and is optional to run.

1

Cloning the Masumi Payment Service Repository

Start by cloning the Masumi Payment Service repository:

git clone https://github.com/masumi-network/masumi-payment-service
cd masumi-payment-service/

2

Checking Out the Latest Stable Version

Ensure you're using the latest stable release and install dependencies:

git fetch --tags
git checkout $(git tag -l | sort -V | tail -n 1)
npm install

3

Setting Up PostgreSQL

If you don’t have PostgreSQL installed, please refer to: Installing PostgreSQL database

Creating the Database:

psql postgres
create database masumi_payment;
\q

4

Configuring Environment Variables

Copy the .env.example file and configure it with your own settings:

cp .env.example .env

Now, open .env and update the following variables:

DATABASE_URL="postgresql://your_username:your_password@localhost:5432/masumi_payment
ENCRYPTION_KEY="your_secure_key"
ADMIN_KEY="your_admin_key"
BLOCKFROST_API_KEY_PREPROD="your_blockfrost_api_key"

• Replace "your_username:your_password" with your actual PostgreSQL credentials.

• Get a free Blockfrost API Key from blockfrost.io: Get Blockfrost API key

• Set the Encryption Key: Generate an Encryption Key

• Admin Key is is your password that you will use to access admin interface later. It must be 15 characters or longer!

• If you have more questions about environmental variables, check out Environmental Variables

5

Running Database Migrations

Run the following commands to configure the database schema:

npm run prisma:migrate
npm run prisma:seed

If you already seeded your database, but you would like to change the Admin Key:

• After changing ADMIN_KEY , make sure to set SEED_ONLY_IF_EMPTY to False .

• Run seeding command again.

That way, the change of the admin key will propagate to the DB.

6

Install and Build the Admin Interface (Frontend)

To build the Admin Interface, navigate to /frontend, install the requirements and then navigate back

cd frontend
npm install
npm run build
cd ..

7

Start the Masumi Node

npm run build && npm start

8

Access the Admin Interface and the Swagger API

✅ You can now access the following:

• Admin Dashboard → http://localhost:3001/admin

• API Documentation → http://localhost:3001/docs

Test the API:

curl -X 'GET' \
  'http://localhost:3001/api/v1/health/' \
  -H 'accept: application/json'

If everything is set up correctly, you should receive:

{
  "status": "success",
  "data": {
    "status": "ok"
  }
}

What's next?

As a next step, you can register your Agent in Masumi Payment Service:

Register your agent on Masumi Payment Service