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

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

curl http://localhost:5000/api/silverpay-test/connection

2. Test SilverPAY Order Creation

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

curl http://localhost:5000/api/silverpay-test/exchange-rate?crypto=BTC&fiat=GBP

4. Check Order Status

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

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