Rozo Payment Manager

A TypeScript backend API service for managing multichain stablecoin payment lifecycle and dispatching all relevant microservice components.

Overview

Rozo Payment Manager is designed to accept crypto from any chain, coin, or wallet instantly. It maximizes conversion with a call-to-action that is:

• Intuitive: Let your customers use any token on any chain
• Fast: Payments complete in seconds
• Simple: Pay in a single step from any wallet
• Secure: No extra counterparties. Never holds user funds

Features

• 🔗 Multichain Support: Ethereum, Base, Optimism, Arbitrum, Polygon, BSC
• 💰 Any Token: Accept payments in any supported token
• 🔄 Cross-chain Swaps: Automatic conversion between chains and tokens
• 🔐 Secure: Enterprise-grade security with API key authentication
• 📊 Real-time Tracking: Complete payment lifecycle monitoring
• 🔔 Webhooks: Real-time payment status notifications
• ⚡ Fast: Sub-second payment detection and processing
• 🛡️ Rate Limited: Built-in DDoS protection and rate limiting

Architecture

Core Components

1. Payment Manager: Main API service for payment lifecycle management
2. PayIn Service: Monitors blockchain for incoming payments
3. PayOut Service: Executes outbound payments and cross-chain swaps

API Reference

Based on Daimo's Payment API, providing:

• Payment creation and management
• Real-time status tracking
• Webhook notifications
• Comprehensive payment history

Quick Start

Prerequisites

• Node.js 18+
• Supabase account
• API keys for blockchain RPC providers

Installation

1. Clone the repository

git clone https://github.com/rozo/payment-manager.git
cd rozo-payment-manager

2. Install dependencies

npm install

3. Set up environment variables

cp .env.example .env
# Edit .env with your configuration

4. Initialize Supabase

npm run supabase:start
npm run supabase:reset

5. Start development server

npm run dev

Environment Variables

Variable	Description	Required
SUPABASE_URL	Supabase project URL	Yes
SUPABASE_ANON_KEY	Supabase anonymous key	Yes
SUPABASE_SERVICE_ROLE_KEY	Supabase service role key	Yes
API_KEY_SECRET	Secret for API key generation	Yes
WEBHOOK_SECRET	Secret for webhook signatures	Yes
PAYIN_SERVICE_URL	URL of PayIn microservice	Yes
PAYOUT_SERVICE_URL	URL of PayOut microservice	Yes
BASE_URL	Public URL of this service	Yes

API Endpoints

Payments

• POST /api/payment - Create a new payment
• GET /api/payment/:id - Get payment by ID
• GET /api/payment/external-id/:externalId - Get payment by external ID
• GET /api/payment/stats - Get payment statistics

System

• GET /api/health - Health check
• POST /api/callbacks/payin - PayIn service callback (internal)
• POST /api/callbacks/payout - PayOut service callback (internal)

Authentication

All API endpoints require an API key in the header:

Api-Key: your-api-key-here

Or:

X-Api-Key: your-api-key-here

Usage Examples

Create Payment

const response = await fetch('https://your-api.com/api/payment', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'Api-Key': 'your-api-key'
  },
  body: JSON.stringify({
    display: {
      intent: "Pay for Premium Subscription",
      paymentValue: "10.00",
      currency: "USD"
    },
    destination: {
      destinationAddress: "0x742d35cc6ab4925a59b2a6923e87e11d2a1e3b1f",
      chainId: 8453, // Base
      tokenAddress: "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913", // USDC
      amountUnits: "10.00"
    },
    externalId: "sub_123456789",
    metadata: {
      userId: "user_123",
      planType: "premium"
    }
  })
});

const payment = await response.json();
console.log('Payment URL:', payment.url);

Get Payment Status

const response = await fetch(`https://your-api.com/api/payment/${paymentId}`, {
  headers: {
    'Api-Key': 'your-api-key'
  }
});

const payment = await response.json();
console.log('Payment status:', payment.status);

Payment Flow

1. Create Payment: API call creates payment record
2. PayIn Monitoring: PayIn service monitors blockchain for payment
3. Payment Detection: Incoming payment detected and verified
4. PayOut Execution: PayOut service executes cross-chain swap if needed
5. Completion: Payment marked as complete, webhook sent

Payment Statuses

• payment_unpaid: User has not paid yet
• payment_started: Payment detected, processing
• payment_completed: Payment successfully completed
• payment_bounced: Payment failed, funds refunded

Webhooks

Configure webhook URLs to receive real-time payment notifications:

{
  "id": "webhook_123",
  "type": "payment.completed",
  "createdAt": "2024-01-15T10:30:00Z",
  "payment": {
    "id": "pay_123",
    "status": "payment_completed",
    "externalId": "order_456"
  }
}

Webhook events:

• payment.created
• payment.started
• payment.completed
• payment.bounced

Development

Project Structure

src/
├── config/         # Configuration files
├── controllers/    # API controllers
├── middleware/     # Express middleware
├── routes/         # API routes
├── services/       # Business logic services
├── types/          # TypeScript type definitions
└── utils/          # Utility functions

supabase/
├── migrations/     # Database migrations
└── functions/      # Edge functions

Database Schema

The application uses Supabase PostgreSQL with the following main tables:

• payments - Payment records
• webhooks - Webhook delivery tracking
• payin_logs - PayIn service logs
• payout_logs - PayOut service logs
• service_health - Microservice health monitoring

Scripts

• npm run dev - Start development server
• npm run build - Build for production
• npm run start - Start production server
• npm run test - Run tests
• npm run lint - Run linter
• npm run supabase:start - Start local Supabase
• npm run supabase:generate-types - Generate TypeScript types

Deployment

Supabase Edge Functions

Deploy as a Supabase Edge Function:

supabase functions deploy rozo-payment-manager

Environment Setup

1. Set environment variables in Supabase dashboard
2. Configure database with migrations
3. Set up webhook endpoints
4. Configure microservice URLs

Security

• API key authentication for all endpoints
• Rate limiting with configurable limits
• Webhook signature verification
• Row Level Security (RLS) in database
• Input validation with Zod schemas
• Comprehensive logging and monitoring

Monitoring

• Health check endpoints for all services
• Real-time service health monitoring
• Payment statistics and analytics
• Comprehensive logging with Winston
• Error tracking and alerting

Support

• Documentation: GitHub Wiki
• Issues: GitHub Issues
• Email: support@rozo.com

License

MIT License - see LICENSE file for details.

Contributing

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Add tests
5. Submit a pull request

---

Built with ❤️ by the Rozo team.