> For the complete documentation index, see [llms.txt](https://docs.onepay.country/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.onepay.country/readme.md).

# Multi-Chain Payment Gateway

A comprehensive multi-chain payment gateway supporting Ethereum, BSC, Arbitrum, Polygon, and Harmony with advanced dashboards, administrative controls, and easy-to-integrate client-side widgets.

## ✨ Features

### Multi-Chain Support

* **Ethereum Mainnet**: Native ETH, WBTC, WETH, USDT, DAI, USDC
* **Binance Smart Chain**: Native BNB, BTCB, USDT, DAI, USDC
* **Arbitrum One**: Native ETH, WBTC, WETH, USDT, DAI, USDC
* **Polygon**: Native MATIC, WBTC, WETH, USDT, DAI, USDC
* **Harmony One**: Native ONE, ETH, BTC, USDT, DAI, USDC

### Comprehensive Dashboards

* **Main Dashboard**: Real-time overview of all chains, payments, and system health
* **Administrative Dashboard**: Complete configuration management for chains, widgets, and security
* **Widget Management**: Create, configure, and manage client-side payment widgets
* **Multi-Chain Monitoring**: Live status of all blockchain networks with latency and block data

### Client-Side Widgets

* **Easy Integration**: Single script tag deployment
* **Customizable Themes**: Light and dark mode support
* **Multi-Chain Selection**: Users can choose their preferred blockchain
* **Payment Calculation**: Real-time amount calculation with discount support
* **Event-Driven**: Custom events for seamless integration with existing applications

### Advanced Features

* **Discount System**: Configurable discount codes and percentages
* **Transaction Verification**: Automatic blockchain verification of payments
* **Security**: Rate limiting, CORS protection, and secure headers
* **RESTful API**: Clean and well-documented endpoints
* **Real-time Updates**: Auto-refreshing dashboards with live data

## 🛠️ Installation

1. **Clone the repository**

   ```bash
   git clone https://github.com/Whostler/paymentGateway.git
   cd paymentGateway
   ```
2. **Install dependencies**

   ```bash
   npm install
   ```
3. **Set up environment variables**

   ```bash
   cp .env.example .env
   # Edit .env with your configuration
   ```
4. **Start the server**

   ```bash
   # Development mode
   npm run dev

   # Production mode
   npm start
   ```

## 🔧 Configuration

### Environment Variables

```env
# Server Configuration
PORT=3000
NODE_ENV=development

# Multi-Chain RPC Endpoints
ETH_RPC_URL=https://mainnet.infura.io/v3/YOUR_PROJECT_ID
BSC_RPC_URL=https://bsc-dataseed1.binance.org
ARB_RPC_URL=https://arb1.arbitrum.io/rpc
POLYGON_RPC_URL=https://polygon-rpc.com
HARMONY_RPC_URL=https://api.harmony.one

# Payment Settings
DEFAULT_DISCOUNT_PERCENT=0
MIN_PAYMENT_AMOUNT=1
MAX_PAYMENT_AMOUNT=1000000
```

### Supported Blockchains

| Blockchain | Native Token | Chain ID | Block Explorer                    |
| ---------- | ------------ | -------- | --------------------------------- |
| Ethereum   | ETH          | 1        | [Etherscan](https://etherscan.io) |
| BSC        | BNB          | 56       | [BSCScan](https://bscscan.com)    |
| Arbitrum   | ETH          | 42161    | [Arbiscan](https://arbiscan.io)   |

cd frontend pnpm install pnpm dev

Backend:

pnpm install pnpm dev

When developing locally run the backend at :3000 and the frontend Vite dev server (default :5173) or use `pnpm run frontend:dev` from project root which proxies `/api` to the backend.

\| Harmony | ONE | 1666600000 | [Harmony Explorer](https://explorer.harmony.one) |

## 📊 Dashboards

### Main Dashboard

Access the comprehensive dashboard at `http://localhost:3000/dashboard.html`

**Features:**

* **System Overview**: Real-time health, uptime, and environment status
* **Multi-Chain Status**: Connected chains, latency, and network health
* **Payment Statistics**: Transaction volume, success rates, and analytics
* **Widget Analytics**: Integration health and usage metrics
* **Blockchain Networks**: Live status of all supported chains

### Administrative Dashboard

Access admin controls at `http://localhost:3000/admin-dashboard.html`

**Features:**

* **Chain Management**: Enable/disable chains, configure settings
* **System Configuration**: Payment settings, security controls
* **Widget Management**: Create, configure, and delete widgets
* **Security Settings**: Rate limiting, CORS configuration

## 🔌 API Endpoints

### Base URL

```
http://localhost:3000/api
```

### Dashboard Endpoints

#### Get Dashboard Data

```http
GET /dashboard/data
```

#### Get Multi-Chain Statistics

```http
GET /dashboard/multichain
```

#### Get System Health

```http
GET /dashboard/health
```

### Admin Endpoints

#### Get Configuration

```http
GET /admin/config
```

#### Update Configuration

```http
PUT /admin/config
```

#### Chain Management

```http
GET /admin/chains
PUT /admin/chains/:chainName/toggle
PUT /admin/chains/:chainName/settings
```

### Widget Endpoints

#### Generate Widget

```http
POST /widgets/generate
```

**Request Body:**

```json
{
  "type": "payment",
  "theme": "light",
  "chains": ["ethereum", "bsc"],
  "domain": "yourdomain.com"
}
```

#### List Widgets

```http
GET /widgets/list
```

#### Serve Widget Script

```http
GET /widgets/:widgetId.js
```

## 🔗 Widget Integration

### Quick Integration

Add this script tag to your website:

```html
<script src="http://localhost:3000/widgets/WIDGET_ID.js"></script>
```

### Custom Container

Specify a custom container for the widget:

```html
<div id="my-payment-widget"></div>
<script src="http://localhost:3000/widgets/WIDGET_ID.js"></script>
<script>
  PaymentWidget.init('my-payment-widget');
</script>
```

### Event Handling

Listen for payment events:

```javascript
window.addEventListener('paymentRequested', (event) => {
  const { widgetId, token, amount, chain } = event.detail;
  // Handle payment processing
  console.log('Payment requested:', event.detail);
});
```

### Widget Configuration

Widgets support various configuration options:

* **Type**: `payment`, `calculator`
* **Theme**: `light`, `dark`
* **Chains**: Array of supported chains
* **Customization**: Colors, branding, styling

## 🧪 Testing

Run the test suite:

```bash
npm test
```

Test specific modules:

```bash
npm run test:unit
npm run test:integration
npm run test:e2e
```

## 🔐 Security Features

* **Multi-Chain Security**: Secure transaction verification across all chains
* **Rate Limiting**: Protects against abuse and DDoS attacks
* **CORS Protection**: Configurable origin whitelist
* **Security Headers**: Comprehensive security header configuration
* **Input Validation**: Strict validation of all requests
* **Environment Isolation**: Separate configurations for development and production

## 🚀 Deployment

### Production Setup

1. **Set environment to production**

   ```bash
   export NODE_ENV=production
   ```
2. **Configure production RPC endpoints**
   * Set up reliable RPC endpoints for all chains
   * Configure proper rate limits and security settings
   * Set secure JWT secrets and encryption keys
3. **Use process manager**

   ```bash
   npm install -g pm2
   pm2 start api/server.js --name "payment-gateway"
   ```

### Docker Deployment

```dockerfile
FROM node:18-alpine
WORKDIR /app
COPY package*.json ./
RUN npm ci --only=production
COPY . .
EXPOSE 3000
CMD ["npm", "start"]
```

## 🤝 Integration Examples

### E-commerce Integration

```javascript
// Initialize payment widget
const widget = new PaymentWidget({
  type: 'payment',
  theme: 'light',
  chains: ['ethereum', 'polygon'],
  customization: {
    colors: {
      primary: '#your-brand-color'
    }
  }
});

// Handle payment completion
window.addEventListener('paymentRequested', async (event) => {
  const { token, amount, chain } = event.detail;
  
  // Process payment with your backend
  const result = await processPayment({
    token,
    amount,
    chain,
    orderId: 'your-order-id'
  });
  
  if (result.success) {
    // Redirect to success page
    window.location.href = '/payment-success';
  }
});
```

### Subscription Service Integration

```javascript
// For recurring payments
const subscriptionWidget = new PaymentWidget({
  type: 'subscription',
  chains: ['polygon', 'bsc'], // Lower gas fees
  recurring: {
    interval: 'monthly',
    amount: 9.99
  }
});
```

## 📈 Monitoring and Analytics

The gateway provides comprehensive monitoring:

* **Real-time Chain Status**: Monitor all blockchain networks
* **Payment Analytics**: Track transaction volume and success rates
* **Widget Performance**: Monitor widget usage across domains
* **System Health**: CPU, memory, and network monitoring
* **Custom Metrics**: Configurable business metrics

## 🆘 Support and Documentation

* **API Documentation**: Available at `/api/docs` (when enabled)
* **Widget Documentation**: See `/widget-demo.html` for examples
* **Configuration Guide**: Detailed in this README
* **Troubleshooting**: Check logs and health endpoints

## 📝 License

MIT License - see [LICENSE](https://github.com/Whostler/paymentGateway/blob/dev/LICENSE/README.md) file for details.

## 🤝 Contributing

1. Fork the repository
2. Create a feature branch
3. Commit your changes
4. Push to the branch
5. Create a Pull Request

***

Built with ❤️ for the multi-chain future


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://docs.onepay.country/readme.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.