Content
# ZeroPay
<div align="center">
[](https://www.gnu.org/licenses/gpl-3.0)
[](https://hub.docker.com/r/zeropaydev/zeropay)
[](https://www.rust-lang.org)
An open-source, self-hosted payment gateway for stablecoins and cryptocurrency payments.
[Features](#features) • [Quick Start](#quick-start) • [Documentation](#documentation) • [Platform](#managed-platform) • [Contributing](#contributing)
</div>
---
## Overview
ZeroPay is a lightweight, self-hosted payment gateway that enables merchants to accept stablecoin and cryptocurrency payments with minimal setup. Built with Rust for performance and reliability, it supports multiple EVM-compatible blockchains and provides real-time webhook notifications for payment events.
### Key Features
- **Self-Hosted**: Full control over your payment infrastructure
- **Multi-Chain Support**: Compatible with Ethereum, Polygon, BSC, and other EVM chains
- **Stablecoin Focused**: Built for USDT, USDC, and other stablecoins
- **Real-Time Notifications**: Webhook integration for payment events
- **Automatic Settlement**: Funds automatically transferred to your wallet (minus commission)
- **Secure**: HMAC-based webhook authentication
- **Easy Integration**: RESTful API with comprehensive documentation
- **Docker Ready**: One-command deployment with Docker
## Quick Start
### Using Docker Compose (Recommended)
The easiest way to run ZeroPay with all dependencies:
1. **Configure your settings:**
Edit `docker-compose.yml` environment variables:
```yaml
environment:
- MNEMONICS=your twelve or twenty four word mnemonic phrase
- WALLET=0xYourWalletAddress
- APIKEY=your-secure-api-key
- WEBHOOK=https://your-webhook-url.com
```
2. **Configure blockchain:**
Edit `config.toml` with your chain settings (RPC URL, tokens, etc.)
3. **Start all services:**
```bash
docker-compose up -d
```
4. **Check logs:**
```bash
docker-compose logs -f zeropay
```
### Using Docker Standalone
```bash
# Pull the latest image
docker pull zeropaydev/zeropay:latest
# Run with environment variables
docker run -d \
--name zeropay \
-p 9000:9000 \
-e DATABASE_URL=postgres://user:pass@host:5432/zeropay \
-e REDIS_URL=redis://host:6379 \
-e MNEMONICS="your mnemonic phrase" \
-e WALLET=0xYourWallet \
-e APIKEY=your-api-key \
-v $(pwd)/config.toml:/app/config.toml \
zeropaydev/zeropay:latest
```
See [DEPLOYMENT.md](./DEPLOYMENT.md) for detailed setup instructions.
## Documentation
- **[Deployment Guide](./DEPLOYMENT.md)** - Complete setup instructions for Docker and source builds
- **[API Reference](./API.md)** - REST API endpoints and webhook events
- **[Configuration Guide](#configuration)** - Environment and chain configuration
## Managed Platform
For a hassle-free experience, use our managed platform at [zeropay.dev](https://zeropay.dev):
**Benefits:**
- No infrastructure management required
- Automatic updates and security patches
- Public payment UI for customers
- Multiple chain support out of the box
- Enterprise-grade reliability
**Setup:**
1. Register your merchant account at [zeropay.dev](https://zeropay.dev)
2. Use `https://api.zeropay.dev` as your API endpoint
3. Start accepting payments immediately
**Note:** The platform charges a small commission for gas fees and hosting.
## Architecture
```
┌─────────────┐
│ Client │
│ Application │
└──────┬──────┘
│ REST API
▼
┌─────────────┐
│ ZeroPay │◄──────┐
│ API │ │
└──────┬──────┘ │
│ │
├──────────────┤
│ │
▼ ▼
┌──────────┐ ┌──────────┐
│PostgreSQL│ │ Redis │
└──────────┘ └──────────┘
│
│ Scanner
▼
┌─────────────────┐
│ Blockchain │
│ (Ethereum, │
│ Polygon, etc) │
└─────────────────┘
```
## Features
### Payment Processing
- Create unique payment addresses for each transaction
- Support for multiple stablecoins (USDT, USDC, DAI, etc.)
- Automatic payment detection and confirmation
- Configurable confirmation blocks for security
### Blockchain Support
- **EVM-Compatible Chains**: Ethereum, Polygon, BSC, Arbitrum, Optimism, Avalanche, etc.
- **Extensible**: Easy to add new chains via configuration
- **Multi-Token**: Support any ERC-20 token
### Webhook Events
- `session.paid` - Customer completed payment
- `session.settled` - Funds transferred to merchant
- `unknow.paid` - Unlinked payment received
- `unknow.settled` - Unlinked payment settled
### Security
- HMAC-SHA256 webhook signatures
- API key authentication
- HD wallet derivation for payment addresses
- Configurable confirmation requirements
## Configuration
### Environment Variables
**For Docker Compose:** Edit the `environment` section in `docker-compose.yml`
**For local development:** Create a `.env` file or set as environment variables
Key configuration options:
```bash
PORT=9000 # API server port
DATABASE_URL=postgres://user:pass@host:5432/zeropay # PostgreSQL connection
REDIS_URL=redis://host:6379 # Redis connection
MNEMONICS=your twelve or twenty-four word phrase # BIP39 seed phrase
WALLET=0xa0..00 # Settlement wallet address
APIKEY=your-secure-api-key # API authentication key
WEBHOOK=https://your-app.com/webhook # Webhook endpoint URL
SCANNER_CONFIG=config.toml # Chain config file path
```
### Chain Configuration
Configure supported blockchains in `config.toml`:
```toml
[[chains]]
chain_type = "evm"
chain_name = "ethereum"
latency = 6 # Confirmation blocks
estimation = 72 # Seconds to confirm
commission = 5 # 5% commission
commission_min = 50 # $0.50 minimum
commission_max = 200 # $2.00 maximum
admin = "0xYourPrivateKey" # Gas payment account
rpc = "https://eth-mainnet.g.alchemy.com/v2/YOUR-KEY"
tokens = [
"USDT:0xdAC17F958D2ee523a2206206994597C13D831ec7",
"USDC:0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48"
]
```
See [DEPLOYMENT.md](./DEPLOYMENT.md) for complete configuration details.
## API Usage
### Create Payment Session
```bash
curl -X POST "http://localhost:9000/sessions?apikey=your-api-key" \
-H "Content-Type: application/json" \
-d '{
"customer": "user123",
"amount": 1000
}'
```
### Check Payment Status
```bash
curl "http://localhost:9000/sessions/12345?apikey=your-api-key"
```
See [API.md](./API.md) for complete API documentation.
## Development
### Prerequisites
- Rust 1.75 or higher
- PostgreSQL 12+
- Redis 6+
### Build from Source
```bash
# Clone the repository
git clone https://github.com/ZeroPayDev/zeropay.git
cd zeropay
# Build
cargo build --release
# Run
./target/release/api
```
### Project Structure
```
zeropay/
├── api/ # REST API server
├── scanner/ # Blockchain scanner
├── config.toml # Chain configuration
├── Dockerfile # Container build file
└── .env-template # Environment template
```
## Contributing
We welcome contributions!
### Reporting Vulnerabilities
If you discover a security vulnerability, please email hi@zeropay.dev instead of using the issue tracker.
### Best Practices
- Never commit `.env` files or private keys
- Use strong, randomly generated API keys
- Verify webhook HMAC signatures
- Keep dependencies updated
- Use secure RPC endpoints
- Enable firewall rules
## License
This project is licensed under the GNU General Public License v3.0 - see the [LICENSE](LICENSE) file for details.
## Support
- **Documentation**: [DEPLOYMENT.md](./DEPLOYMENT.md) | [API.md](./API.md)
- **Issues**: [GitHub Issues](https://github.com/ZeroPayDev/zeropay/issues)
- **Discussions**: [GitHub Discussions](https://github.com/ZeroPayDev/zeropay/discussions)
- **Platform Support**: hi@zeropay.dev
<div align="center">
Made with ❤️ by the ZeroPay community
[Website](https://zeropay.dev) • [GitHub](https://github.com/ZeroPayDev/zeropay) • [Twitter](https://twitter.com/zeropaydev)
</div>
