PTDT Settlement API v0.1

Production-Ready Backend for Tokenized Ride-Sharing on Binance Smart Chain

---

Overview

The PTDT Settlement API is a complete backend solution enabling ride-hailing platforms to:

• Pay drivers in PTDT Token (BEP-20) directly to their wallets
• Convert PTDT to local fiat on-demand (JazzCash, Flutterwave, M-Pesa)
• Operate independently without central authority or intermediaries
• Scale globally with one unified codebase
• Track earnings in real-time with analytics

---

Quick Start

Docker (2 minutes)

docker-compose up -d
curl http://localhost:3000/api/v1/health

Local Development (5 minutes)

npm install
cp .env.example .env
npm run dev

Production (30 minutes)

npm run build
npm start

---

API Endpoints

Quote Endpoints

• POST /api/v1/quote - Generate ride quote in PTDT
• GET /api/v1/quote/:quoteId - Check quote validity

Payment Endpoints

• POST /api/v1/pay - Execute PTDT payment
• GET /api/v1/pay/:txId - Check transaction status

Withdrawal Endpoints

• POST /api/v1/payout - Initiate driver payout
• GET /api/v1/payout/:withdrawalId - Check payout status

Operator Endpoints

• GET /api/v1/operator/me - Get operator dashboard
• GET /api/v1/operator/stats - Get operator statistics

Analytics Endpoints

• GET /api/v1/analytics/network - Network-level metrics
• GET /api/v1/analytics/operator/:operatorId - Operator metrics

System Endpoints

• GET /api/v1/health - API health check
• POST /api/v1/webhook/payment - Payment webhooks
• POST /api/v1/webhook/settlement - Settlement webhooks
• POST /api/v1/webhook/payout - Payout webhooks

---

Architecture

┌──────────────────┐
│  Your Ride-Hailing App  │
└───────────┬───────┘
                    │
         ┌───────────────┐
         │ PTDT Settlement API  │
         └──────┬────────┘
                  │
      ┌───────────┐  ┌──────────┐
      │ PostgreSQL DB │  │ BSC Blockchain │
      │ Local Data   │  │ PTDT Token     │
      └───────────┘  └──────────┘

---

Tech Stack

Component	Technology
Runtime	Node.js 20+
Framework	Express.js 4.18+
Language	TypeScript 5.1+
Database	PostgreSQL 15+
Blockchain	ethers.js 6.7+
Validation	Joi 17.10+
Logging	Winston 3.10+
Security	Helmet 7.0+, JWT
Container	Docker & Docker Compose

---

Configuration

Environment Variables

# Blockchain Configuration
BSC_RPC_URL=https://bsc-dataseed1.binance.org:443
PTDT_CONTRACT_ADDRESS=0x66c6Fc5E7F99272134a52DF9E88D94eD83E89278
PTDT_DECIMALS=18

# Database
DATABASE_URL=postgresql://user:password@localhost:5432/ptdt_settlement

# API Configuration
PORT=3000
NODE_ENV=development
JWT_SECRET=your-secret-key-here-min-32-chars

# Rate Limiting
RATE_LIMIT_WINDOW_MS=900000  # 15 minutes
RATE_LIMIT_MAX_REQUESTS=100

# Fiat Payment Providers
YOUR_LOCAL_API_KEY=your-key
YOUR_LOCAL_MERCHANT_ID=your-id
FLUTTERWAVE_API_KEY=your-key
M_PESA_API_KEY=your-key

# Logging
LOG_LEVEL=info
LOG_DIR=./logs

# CORS
CORS_ORIGIN=*

---

Features

Quote Management

✅ Convert ride fare to PTDT amount ✅ Real-time PTDT pricing ✅ Apply promotional discounts ✅ Quote expiration handling

Payment Processing

✅ Direct PTDT transfer to driver wallet ✅ Automatic fee distribution ✅ Transaction verification ✅ Failure handling & rollback

Driver Payouts

✅ Multiple withdrawal methods (WALLET, FIAT) ✅ JazzCash, Flutterwave, M-Pesa integration ✅ Automatic PTDT burn ✅ Payout tracking

Multi-Currency

✅ PKR, KES, NGN, USD support ✅ Real-time exchange rates ✅ Regional payment gateways

Analytics

✅ Network metrics (total rides, volume) ✅ Operator dashboard (stats, revenue) ✅ Driver earnings (balance, transactions) ✅ Real-time data aggregation

Security

✅ JWT authentication ✅ API key validation ✅ Rate limiting (100 req/15min) ✅ Request logging & audit trail ✅ Input validation (Joi) ✅ SQL injection prevention (Prisma) ✅ HTTPS/TLS support ✅ Error sanitization

Reliability

✅ Health checks (API, DB, blockchain) ✅ Webhook verification ✅ Transaction confirmation ✅ Error boundary protection ✅ Graceful shutdown handling

---

Deployment

Docker

# Build image
docker build -t ptdt-api .

# Run container
docker run -p 3000:3000 \
  -e DATABASE_URL=postgresql://... \
  -e JWT_SECRET=... \
  ptdt-api

Railway (Recommended)

1. Connect GitHub repo
2. Set environment variables
3. Deploy automatically

Render

1. Create new Web Service
2. Connect GitHub repo
3. Set build command: npm run build
4. Set start command: npm start

AWS

1. Create EC2 instance
2. Install Node.js
3. Clone repository
4. Install dependencies
5. Configure environment
6. Start with PM2 or systemd

---

Testing

Health Check

curl http://localhost:3000/api/v1/health

Generate Quote

curl -X POST http://localhost:3000/api/v1/quote \
  -H "Authorization: Bearer YOUR_JWT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "rideFare": 100,
    "currency": "PKR",
    "discount": 5
  }'

Execute Payment

curl -X POST http://localhost:3000/api/v1/pay \
  -H "Authorization: Bearer YOUR_JWT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "quoteId": "QT_1234567890",
    "riderWallet": "0x...",
    "driverWallet": "0x...",
    "amountPtdt": 10.5
  }'

---

Documentation

• START_HERE.md - Quick start guide
• INTEGRATION_GUIDE.md - How to integrate with your app
• DEPLOYMENT.md - Production deployment guide
• QUICK_REFERENCE.md - API endpoint reference
• SECURITY.md - Security best practices

---

Support

• GitHub Issues: Report bugs and request features
• Email: dev@ptdt.taxi
• Documentation: Check docs folder

---

License

MIT License - See LICENSE file

---

Status: ✅ Production Ready

Version: 0.1.0

Last Updated: January 27, 2026