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):

"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

# 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

# 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

{
  "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

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

Set environment variables in deployment:

-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

# Generate secure random API key
openssl rand -base64 32

# Example output: OCTk42VKenf5KZqKDDRAAskxf53yJsEby72j99Fc

Configure in SilverPay:

{
  "ApiKeys": {
    "DefaultKey": "OCTk42VKenf5KZqKDDRAAskxf53yJsEby72j99Fc"
  }
}

🔄 Payment Workflow

1. Order Creation

Customer creates order via TeleBot or Admin Panel:

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

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

2. Payment Initiation

Create crypto payment for order:

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

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

LittleShop calls SilverPay:

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:

{
  "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:

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):

// 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:

openssl rand -hex 32

# Example: a3f8c9d2e5b7a1f4c6d8e2b9f7a3c5d8

Configure in both systems:

• SilverPay: WebhookSecret setting
• LittleShop: SilverPay__WebhookSecret setting

🧪 Testing Integration

Manual API Test

# 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

# 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:

   docker ps | grep silverpay
   

2. Verify port binding:

   docker port silverpay
   # Should show: 5500/tcp -> 0.0.0.0:5500
   

3. Check firewall:

   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:

   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:

   docker exec silverpay curl http://littleshop:5000/api/version
   

2. Verify both containers on same network:

   docker network inspect littleshop-network
   docker network inspect silverpay-network
   

3. Check LittleShop webhook logs:

   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

# 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

# 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 procedures
• BOT_REGISTRATION.md - TeleBot setup
• 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.