How to Test

Get the API mockup example repository onto your server:

git clone git@github.com:InformationSystemsAgency/bank-declaration-api-mockup.git
cd bank-declaration-api-mockup

1.3 Create a Virtual Environment

Isolate the project dependencies in a Python virtual environment:

# Create the virtual environment
python3 -m venv venv

# Activate it
# On Linux / macOS:
source venv/bin/activate

# On Windows:
venv\Scripts\activate

Alternatively, use the provided setup script which handles this automatically:

chmod +x setup_env.sh
./setup_env.sh

1.4 Install Dependencies

Install all required Python packages:

pip install -r requirements.txt

This installs: Flask, Flask-CORS, PyYAML, Gunicorn, and python-dotenv.

Alternatively, if you have Docker installed, you can skip the Python setup above and run:

# Build and start the container
docker compose up --build -d

The server will start on port 8080. Skip to step 1.5 to configure your environment variables.

Copy the example environment file and edit it for your bank:

# Copy the example config
cp .env.example .env

# Edit with your settings
nano .env

Or use the interactive setup script to generate it:

chmod +x setup_env.sh
./setup_env.sh

Key settings to configure in .env:

Option A: Using the start script

chmod +x start.sh
./start.sh

This script automatically sets up the virtual environment, installs dependencies, and starts the server.

Option B: Direct

python run.py

The server will start on http://0.0.0.0:8080 by default.

Option C: With Gunicorn

gunicorn --bind 0.0.0.0:8080 --workers 4 "app:create_app()"

Option D: With Docker

docker compose up -d

Confirm everything is running correctly:

# From your server (local check):
curl http://localhost:8080/

If the setup is correct, you should see the API info page or a JSON response.

1 Go to your Security Server's admin dashboard.

2 Click Clients in the navigation menu.

3 Find your bank client in the list.

1 Click the Add Subsystem button.

2 Fill in the fields:

3 Click Add to create the subsystem.

After adding, you will see the new subsystem listed under your bank client.

1 Click on your newly created subsystem to open the Subsystem Details page.

2 Go to the Services tab.

3 Click the Add REST button.

1 In the opened window, fill in:

2 Click Save.

3 After adding, you will see your service listed (initially disabled). Endpoints will be automatically loaded from OpenApi specification.

4 Enable the service by clicking the toggle switch to turn it on.

1 Click on the BankingData service to open its details.

2 Go to the Access Rights tab.

3 Click Save.

5 Click Add Subjects.

1 In the search dialog, fill in the fields to find the SRC subsystem:

2 Select the DECLARATION subsystem from the search results.

3 Click Add Selected to grant access.

1 Go to the Internal Servers tab in your subsystem.

2For HTTPS connection you need to configure mTLS between security server and information system (software). . More info: X-Road TLS Certificate Handling

3You can use also HTTP connection for testing purposes.

At this stage, the ISAA must approve your Subsystem registration. Your bank needs to wait until confirmation is received before proceeding.

After completing all steps, verify that everything is working:

Check Service Status:

• Service should show as enabled (green toggle)
• Access rights should list the SRC consumer subsystem

Test the Connection:

Once your X-Road configuration is complete, go to the SRC Test Console to verify the connection. Authenticate with your API token and follow the testing flow (Initiate Request, Poll Status, Retrieve Data) described below.

For any issues related to X-Road connection, please contact us at x-road@isaa.am.

• Subsystem created under bank client
• Subsystem registered
• REST service added with OpenApi specification
• Service enabled (toggle on)
• Access rights granted to SRC consumer subsystem
• Connection type set appropriately (HTTP/HTTPS)

1 Initiate Request

Send a request with a citizen's PSN (Personal Social Number). The API returns a sessionID to track the request.

POST /src/initiate
{"psn": "1234567890"}

2 Poll Status

Use the sessionID to check if the data is ready. Keep polling until the status changes from PENDING.

POST /src/poll
{"session_id": "<sessionID>"}

3 Retrieve Data

Once the status is READY, retrieve the actual banking data.

POST /src/retrieve
{"psn": "1234567890", "session_id": "<sessionID>"}

1 Authenticate

Enter your bank API token in the Authentication section on the Test Console page.

2 Enter a PSN

Type one of the sample PSNs above (e.g. 1234567890) in the Citizen PSN field.

3 Click "Initiate Request"

The response panel will show the result and a sessionID will be populated automatically.

4 Click "Poll Status"

Check the session status. If PENDING, wait a moment and poll again.

5 Click "Retrieve Data"

Once the status is READY, retrieve the banking data. The full response will be displayed in the response panel.