littleshop/SILVERPAY_MIGRATION_GUIDE.md

# SilverPAY Migration Guide for LittleShop

## Overview
This guide documents the migration from BTCPay Server to SilverPAY for cryptocurrency payment processing in LittleShop.

## Migration Status: ✅ COMPLETE

### What Has Been Implemented

#### 1. **Dual Payment Provider Support**
- LittleShop now supports both BTCPay Server and SilverPAY
- Easy switching via configuration setting
- No code changes required to switch providers

#### 2. **New SilverPAY Integration Components**
- `ISilverPayService.cs` - Service interface for SilverPAY API
- `SilverPayService.cs` - Implementation of SilverPAY client
- `SilverPayWebhookController.cs` - Webhook handler for payment notifications
- `SilverPayTestController.cs` - Testing endpoints for verification

#### 3. **Database Updates**
- Added `SilverPayOrderId` field to `CryptoPayment` model
- Updated DTOs to include new field
- Backwards compatible with existing BTCPay payments

#### 4. **Configuration**
```json
{
  "PaymentProvider": {
    "UseSilverPay": true  // Set to true for SilverPAY, false for BTCPay
  },
  "SilverPay": {
    "BaseUrl": "https://admin.thebankofdebbie.giize.com",
    "ApiKey": "",  // Add API key when provided
    "WebhookSecret": "",  // Add webhook secret when configured
    "DefaultWebhookUrl": "https://littleshop.silverlabs.uk/api/silverpay/webhook",
    "AllowUnsignedWebhooks": true  // For development only
  }
}
```

## Key Differences: BTCPay vs SilverPAY

| Feature | BTCPay Server | SilverPAY |
|---------|--------------|-----------|
| Payment Method | Checkout Link | Direct Wallet Address |
| Customer Experience | Redirect to BTCPay | In-app payment with address |
| Invoice ID | BTCPayInvoiceId | SilverPayOrderId |
| Webhook Format | HMAC-SHA256 "sha256=" | Standard HMAC or unsigned |
| Exchange Rates | Internal BTCPay rates | SilverPAY exchange API |
| Address Generation | BTCPay managed | HD wallet derivation |

## Testing the Integration

### 1. Check Current Provider
```bash
curl http://localhost:5000/api/silverpay-test/connection
```

### 2. Test SilverPAY Order Creation
```bash
curl -X POST http://localhost:5000/api/silverpay-test/create-order \
  -H "Content-Type: application/json" \
  -d '{"amount": 10.00, "currency": "BTC"}'
```

### 3. Get Exchange Rates
```bash
curl http://localhost:5000/api/silverpay-test/exchange-rate?crypto=BTC&fiat=GBP
```

### 4. Check Order Status
```bash
curl http://localhost:5000/api/silverpay-test/order/{orderId}
```

## Switching Between Providers

### To Use SilverPAY:
1. Edit `appsettings.json` (or environment-specific settings)
2. Set `"PaymentProvider:UseSilverPay": true`
3. Restart the application

### To Use BTCPay Server:
1. Edit `appsettings.json`
2. Set `"PaymentProvider:UseSilverPay": false`
3. Restart the application

## Production Deployment Checklist

- [ ] Configure SilverPAY API key in production settings
- [ ] Set up webhook secret for signature validation
- [ ] Update webhook URL to production domain
- [ ] Set `AllowUnsignedWebhooks` to `false`
- [ ] Test payment flow end-to-end
- [ ] Configure SSL certificates
- [ ] Set up monitoring for payment webhooks
- [ ] Test failover to BTCPay if needed

## Webhook Configuration

### SilverPAY Webhook Endpoint
```
POST https://littleshop.silverlabs.uk/api/silverpay/webhook
```

### Expected Webhook Payload
```json
{
  "order_id": "uuid",
  "external_id": "LittleShop order ID",
  "status": "paid|confirmed|expired",
  "address": "wallet_address",
  "tx_hash": "transaction_hash",
  "amount": 0.001,
  "confirmations": 3,
  "timestamp": "2025-01-20T10:00:00Z"
}
```

## Benefits of SilverPAY

1. **Direct Wallet Addresses** - Customers see the exact address to send payment
2. **Self-Hosted** - Full control over payment infrastructure
3. **Multi-Currency** - Same support for BTC, ETH, LTC, etc.
4. **Fiat Conversion** - Built-in GBP/USD/EUR support
5. **Unified Ecosystem** - Part of SilverLABS infrastructure

## Rollback Plan

If issues arise with SilverPAY:
1. Set `"PaymentProvider:UseSilverPay": false` in configuration
2. Restart application
3. System automatically reverts to BTCPay Server
4. No data loss - both payment IDs are stored

## Support and Monitoring

### Health Check Endpoints
- LittleShop: `http://localhost:5000/health`
- SilverPAY: `https://admin.thebankofdebbie.giize.com/health`

### Log Monitoring
- Look for `[SilverPAY]` tags in logs
- Payment creation: `"Created SilverPAY payment"`
- Webhook processing: `"Processing SilverPAY webhook"`
- Errors: `"Failed to create SilverPAY order"`

### Common Issues and Solutions

| Issue | Solution |
|-------|----------|
| Connection refused | Check SilverPAY URL and network access |
| 401 Unauthorized | Verify API key configuration |
| Invalid signature | Check webhook secret configuration |
| Order not found | Verify SilverPayOrderId is stored |
| Exchange rate unavailable | Check SilverPAY exchange service |

## Future Enhancements

1. **Automatic Failover** - Switch to backup provider on failure
2. **Load Balancing** - Distribute between multiple providers
3. **Advanced Monitoring** - Real-time payment tracking dashboard
4. **Multi-Provider Support** - Use different providers per currency

## Migration Complete! 🎉

The SilverPAY integration is now complete and ready for testing. The system supports both payment providers with easy configuration-based switching.

**Next Steps:**
1. Test the integration using the test endpoints
2. Configure production API keys and webhooks
3. Deploy to production environment
4. Monitor initial transactions closely