littleshop/SILVERPAY_SETUP.md

# SilverPay Integration Setup Guide

This guide covers configuring LittleShop to integrate with SilverPay cryptocurrency payment gateway.

## 📋 Overview

SilverPay is a self-hosted cryptocurrency payment processor that handles:
- Multi-cryptocurrency payment processing (BTC, XMR, ETH, etc.)
- Payment address generation
- Blockchain monitoring and confirmations
- Webhook notifications for payment status updates

## 🚨 Current Status

### CT109 Pre-Production (10.0.0.51)

**Status:** ❌ **SilverPay NOT RUNNING**

According to E2E test results:
- Expected endpoint: `http://10.0.0.51:5500/api/health`
- Response: **HTTP 404 Not Found**
- Impact: Payment creation is currently blocked

**Configuration (appsettings.Development.json):**
```json
"SilverPay": {
  "BaseUrl": "http://10.0.0.51:5500",
  "ApiKey": "OCTk42VKenf5KZqKDDRAAskxf53yJsEby72j99Fc",
  "WebhookSecret": "webhook_secret_dev",
  "DefaultWebhookUrl": "http://localhost:5000/api/orders/payments/webhook",
  "AllowUnsignedWebhooks": true
}
```

### Production VPS (srv1002428.hstgr.cloud)

**Status:** ✅ Uses BTCPay Server instead

Production uses BTCPay Server (v2.2.1) for cryptocurrency payments:
- Host: https://thebankofdebbie.giize.com
- Store ID: CvdvHoncGLM7TdMYRAG6Z15YuxQfxeMWRYwi9gvPhh5R
- Supported currencies: BTC, DOGE, XMR, ETH, ZEC

## 🔧 SilverPay Installation (CT109)

### Prerequisites

- Docker installed on CT109
- PostgreSQL or SQLite for SilverPay database
- Redis for caching/session management
- Network access to blockchain nodes or public APIs

### Quick Install with Docker

```bash
# SSH to CT109
ssh sysadmin@10.0.0.51

# Create SilverPay directory
mkdir -p ~/silverpay
cd ~/silverpay

# Clone SilverPay repository (replace with actual repo URL)
git clone https://github.com/your-org/silverpay.git .

# Create docker-compose.yml
cat > docker-compose.yml << 'EOF'
version: '3.8'

services:
  silverpay:
    build: .
    image: silverpay:latest
    container_name: silverpay
    restart: unless-stopped
    ports:
      - "5500:5500"
    environment:
      - ASPNETCORE_ENVIRONMENT=Development
      - ASPNETCORE_URLS=http://+:5500
      - ConnectionStrings__DefaultConnection=Data Source=/app/data/silverpay.db
      - ApiKeys__DefaultKey=OCTk42VKenf5KZqKDDRAAskxf53yJsEby72j99Fc
    volumes:
      - silverpay-data:/app/data
    networks:
      - silverpay-network

networks:
  silverpay-network:
    external: true

volumes:
  silverpay-data:
    driver: local
EOF

# Create network (if not already exists)
docker network create silverpay-network

# Start SilverPay
docker-compose up -d

# Verify startup
docker logs silverpay -f
```

### Verify Installation

```bash
# Test health endpoint
curl http://localhost:5500/api/health

# Expected response:
# {"status":"healthy","version":"1.0.0"}

# Test from LittleShop container
docker exec littleshop curl http://10.0.0.51:5500/api/health
```

## ⚙️ Configuration

### LittleShop Configuration

#### Development Environment (CT109)

**File:** `LittleShop/appsettings.Development.json`

```json
{
  "SilverPay": {
    "BaseUrl": "http://10.0.0.51:5500",
    "ApiKey": "OCTk42VKenf5KZqKDDRAAskxf53yJsEby72j99Fc",
    "WebhookSecret": "webhook_secret_dev",
    "DefaultWebhookUrl": "http://littleshop:5000/api/orders/payments/webhook",
    "AllowUnsignedWebhooks": true
  }
}
```

**Important Notes:**
- `BaseUrl`: Must be accessible from LittleShop container
- `WebhookUrl`: Uses container name `littleshop` not `localhost`
- `AllowUnsignedWebhooks`: Set to `true` for development, `false` for production

#### Production Environment

**File:** `LittleShop/appsettings.Production.json`

```json
{
  "SilverPay": {
    "BaseUrl": "${SILVERPAY_BASE_URL}",
    "ApiKey": "${SILVERPAY_API_KEY}",
    "WebhookSecret": "${SILVERPAY_WEBHOOK_SECRET}",
    "DefaultWebhookUrl": "${SILVERPAY_WEBHOOK_URL}",
    "AllowUnsignedWebhooks": false
  }
}
```

Set environment variables in deployment:
```bash
-e SilverPay__BaseUrl=https://pay.your domain.com \
-e SilverPay__ApiKey=your-production-api-key \
-e SilverPay__WebhookSecret=your-webhook-secret \
-e SilverPay__DefaultWebhookUrl=https://admin.dark.side/api/orders/payments/webhook
```

### API Key Generation

```bash
# Generate secure random API key
openssl rand -base64 32

# Example output: OCTk42VKenf5KZqKDDRAAskxf53yJsEby72j99Fc
```

Configure in SilverPay:
```json
{
  "ApiKeys": {
    "DefaultKey": "OCTk42VKenf5KZqKDDRAAskxf53yJsEby72j99Fc"
  }
}
```

## 🔄 Payment Workflow

### 1. Order Creation

Customer creates order via TeleBot or Admin Panel:

```bash
POST /api/orders
Content-Type: application/json

{
  "customerIdentityReference": "telegram_12345678",
  "items": [
    {
      "productId": "guid",
      "quantity": 2
    }
  ]
}
```

### 2. Payment Initiation

Create crypto payment for order:

```bash
POST /api/orders/{orderId}/payments
Content-Type: application/json

{
  "cryptocurrency": "BTC",
  "amount": 0.001
}
```

**LittleShop calls SilverPay:**
```http
POST http://10.0.0.51:5500/api/payments
Authorization: Bearer OCTk42VKenf5KZqKDDRAAskxf53yJsEby72j99Fc
Content-Type: application/json

{
  "orderId": "guid",
  "cryptocurrency": "BTC",
  "fiatAmount": 100.00,
  "fiatCurrency": "GBP",
  "webhookUrl": "http://littleshop:5000/api/orders/payments/webhook"
}
```

**SilverPay responds:**
```json
{
  "paymentId": "guid",
  "paymentAddress": "bc1q...",
  "amount": 0.001,
  "cryptocurrency": "BTC",
  "qrCode": "data:image/png;base64,...",
  "expiresAt": "2025-11-18T18:00:00Z"
}
```

### 3. Customer Payment

Customer sends cryptocurrency to the provided address.

### 4. Blockchain Monitoring

SilverPay monitors blockchain for incoming transactions.

### 5. Webhook Notification

SilverPay sends webhook when payment confirmed:

```http
POST http://littleshop:5000/api/orders/payments/webhook
Content-Type: application/json
X-Webhook-Signature: sha256=...

{
  "paymentId": "guid",
  "status": "Confirmed",
  "transactionId": "blockchain_tx_hash",
  "confirmations": 6,
  "timestamp": "2025-11-18T17:45:00Z"
}
```

**LittleShop updates order status** to PaymentReceived.

## 🔐 Webhook Security

### Signature Verification

**Development (AllowUnsignedWebhooks: true):**
- Signature verification skipped
- Useful for testing without crypto operations

**Production (AllowUnsignedWebhooks: false):**
```csharp
// LittleShop verifies webhook signature
var signature = Request.Headers["X-Webhook-Signature"];
var payload = await new StreamReader(Request.Body).ReadToEndAsync();
var expectedSignature = ComputeHMACSHA256(payload, webhookSecret);

if (signature != $"sha256={expectedSignature}")
{
    return Unauthorized("Invalid webhook signature");
}
```

### Webhook Secret

**Generate secure secret:**
```bash
openssl rand -hex 32

# Example: a3f8c9d2e5b7a1f4c6d8e2b9f7a3c5d8
```

**Configure in both systems:**
- SilverPay: `WebhookSecret` setting
- LittleShop: `SilverPay__WebhookSecret` setting

## 🧪 Testing Integration

### Manual API Test

```bash
# Test payment creation (from CT109)
curl -X POST http://localhost:5100/api/orders/ORDER_ID/payments \
  -H "Content-Type: application/json" \
  -d '{"cryptocurrency":"BTC"}'

# Expected response:
# {
#   "paymentId": "guid",
#   "paymentAddress": "bc1q...",
#   "amount": 0.001,
#   "qrCode": "data:image/png;base64,..."
# }
```

### Test Webhook Delivery

```bash
# Simulate webhook from SilverPay
curl -X POST http://localhost:5100/api/orders/payments/webhook \
  -H "Content-Type: application/json" \
  -d '{
    "paymentId": "test-payment-id",
    "status": "Confirmed",
    "transactionId": "test-tx-hash",
    "confirmations": 6
  }'

# Check LittleShop logs
docker logs littleshop --tail 50
```

### TeleBot Payment Flow

```
1. User: /start
2. Bot: Welcome! Browse products...
3. User: Select product + quantity
4. Bot: Create order
5. User: Confirm checkout
6. Bot: Request cryptocurrency preference
7. User: Select BTC
8. Bot: Display payment address + QR code + amount
9. User: Send payment
10. SilverPay: Monitor blockchain
11. SilverPay: Send webhook to LittleShop
12. LittleShop: Update order status
13. Bot: Notify user "Payment confirmed!"
```

## 🛠️ Troubleshooting

### SilverPay Not Accessible

**Symptom:** `curl: (7) Failed to connect to 10.0.0.51 port 5500`

**Solutions:**
1. Check SilverPay container is running:
   ```bash
   docker ps | grep silverpay
   ```

2. Verify port binding:
   ```bash
   docker port silverpay
   # Should show: 5500/tcp -> 0.0.0.0:5500
   ```

3. Check firewall:
   ```bash
   sudo ufw status
   sudo ufw allow 5500/tcp
   ```

### HTTP 404 Not Found

**Symptom:** `curl http://10.0.0.51:5500/api/health` returns 404

**Solutions:**
1. Check SilverPay logs:
   ```bash
   docker logs silverpay --tail 100
   ```

2. Verify API endpoint exists in SilverPay codebase

3. Confirm base URL configuration matches actual endpoint

### Webhook Not Received

**Symptom:** Payment confirmed on blockchain but order status not updated

**Solutions:**
1. Check webhook URL is accessible from SilverPay container:
   ```bash
   docker exec silverpay curl http://littleshop:5000/api/version
   ```

2. Verify both containers on same network:
   ```bash
   docker network inspect littleshop-network
   docker network inspect silverpay-network
   ```

3. Check LittleShop webhook logs:
   ```bash
   docker logs littleshop | grep webhook
   ```

### API Key Invalid

**Symptom:** `401 Unauthorized` from SilverPay

**Solutions:**
1. Verify API key matches in both systems
2. Check Authorization header format:
   ```
   Authorization: Bearer YOUR_API_KEY
   ```

3. Regenerate API key if compromised

## 📊 Monitoring

### Health Checks

```bash
# SilverPay health
curl http://10.0.0.51:5500/api/health

# LittleShop health
curl http://10.0.0.51:5100/api/version

# Check payment processing
curl http://10.0.0.51:5100/api/orders | jq '.items[] | select(.status == "PendingPayment")'
```

### Log Monitoring

```bash
# Real-time logs
docker logs -f silverpay
docker logs -f littleshop

# Payment-specific logs
docker logs silverpay | grep payment
docker logs littleshop | grep SilverPay
```

## 🔗 Related Documentation

- [DEPLOYMENT.md](./DEPLOYMENT.md) - Deployment procedures
- [BOT_REGISTRATION.md](./BOT_REGISTRATION.md) - TeleBot setup
- [CT109_E2E_TEST_RESULTS.md](./CT109_E2E_TEST_RESULTS.md) - Test results showing SilverPay status

## 💡 Alternative: Use BTCPay Server

If SilverPay is not available, consider using BTCPay Server (production VPS already uses this):

**Advantages:**
- Mature, battle-tested platform
- Extensive cryptocurrency support
- Active community and documentation
- Built-in merchant tools

**Setup:**
See BTCPay Server integration in `appsettings.Hostinger.json` for reference configuration.