facilpay-api

Backend API service for FacilPay - Stellar-based multi-chain payment gateway. Handles payment processing, webhook management, settlement operations, and merchant integrations.

FacilPay API

Backend API built with NestJS.

---

🚀 Requirements

• Docker and Docker Compose for the fastest local setup
• Node.js 18+ and npm for running without Docker

---

Docker Quick Start

Start the API and PostgreSQL with hot reload:

docker compose up --build

The API will be available at http://localhost:3000.

Run database migrations inside the API container:

docker compose run --rm api migrate

Run E2E tests against a throwaway PostgreSQL database:

docker compose -f docker-compose.test.yml run --rm api test:e2e

Stop and remove local containers, networks, and volumes:

docker compose down -v

Local Setup

1. Install dependencies

npm install

Create environment file

cp .env.example .env

Run the application

npm run start:dev

The application will be available at:

http://localhost:3000

Common Commands

npm run dev
npm test
npm run test:e2e
npm run migrate
npm run docker:dev
npm run docker:test:e2e

## 🩺 Health Check

To verify the API is running correctly, use the health check endpoint:

```bash
curl -i http://localhost:3000/health 

Expected Response

Status: 200 OK

Body:

{
  "status": "ok"
}

🔐 Authentication

The API includes a JWT-based authentication system with the following endpoints:

Register a new user

curl -X POST http://localhost:3000/auth/register \
  -H "Content-Type: application/json" \
  -d '{"email":"user@example.com","password":"password123"}'

Login user

curl -X POST http://localhost:3000/auth/login \
  -H "Content-Type: application/json" \
  -d '{"email":"user@example.com","password":"password123"}'

Access protected route

curl -X GET http://localhost:3000/profile \
  -H "Authorization: Bearer YOUR_JWT_TOKEN"

## 📁 Project Structure

src/
├── modules/
│   ├── auth/
│   │   ├── auth.controller.ts
│   │   ├── auth.service.ts
│   │   ├── auth.module.ts
│   │   ├── jwt.strategy.ts
│   │   ├── guards/
│   │   └── decorators/
│   ├── users/
│   │   ├── user.entity.ts
│   │   ├── dto/
│   │   └── users.module.ts
│   └── health/
│       ├── health.controller.ts
│       ├── health.service.ts
│       └── health.module.ts
├── app.controller.ts
├── app.service.ts
├── app.module.ts
└── main.ts

🧪 Development

The server runs on port 3000 by default.

The port can be configured using the PORT variable in the .env file

📊 Logging

Logging is structured with Pino and writes rotating files under the log directory.

Environment variables:

• LOG_LEVEL (default: info in production, debug in development)
• LOG_DIR (default: logs)
• LOG_PRETTY (default: true in development, false in production)
• LOG_MAX_SIZE (default: 10m)
• LOG_RETENTION_DAYS (default: 14)
• LOG_BODY (default: false)
• LOG_BODY_MAX_LENGTH (default: 2048)
• LOG_RESPONSE_BODY (default: false)

🔒 Security Features

• JWT token-based authentication

• Password hashing with bcrypt

• Protected routes with guards

• Public route decorator

• Current user decorator

• Role-based access control (ready for implementation)

• Telegram: https://t.me/+afM9uh7GGtVkYmZk

Stellar Configuration structure

├── modules/
│   ├── auth/
│   ├── stellar/          <-- New Module
│   │   ├── stellar.service.ts
│   │   └── stellar.module.ts
│   ├── users/
│   └── health/