Bitcoin Newsletter Plugin

A comprehensive WordPress plugin that enables Bitcoin payments for newsletter subscriptions. Users can subscribe to newsletters by making Bitcoin payments through integrated payment gateways like CoinSnap and BTCPay Server.

Table of Contents

• Features
• Installation
• Configuration
• Creating Newsletter Forms
• Payment Gateway Setup
• Newsletter Provider Setup
• Managing Subscribers
• Shortcodes
• Advanced Customization
• Troubleshooting
• Support

Features

Core Functionality

• Bitcoin Payment Integration: Accept Bitcoin payments for newsletter subscriptions
• Multiple Payment Gateways: Support for CoinSnap and BTCPay Server
• Newsletter Provider Integration: Connect with MailPoet, Mailchimp, Sendinblue/Brevo, and ConvertKit
• Custom Forms: Create customizable newsletter subscription forms
• Subscriber Management: Comprehensive subscriber database and management
• GDPR Compliance: Built-in GDPR compliance features
• Test Mode: Test payments without real transactions

Payment Gateways

• CoinSnap: Lightning Network payments with instant confirmation
• BTCPay Server: Self-hosted Bitcoin payment processing

Newsletter Providers

• MailPoet: WordPress-native email marketing
• Mailchimp: Popular email marketing platform
• Sendinblue/Brevo: European email marketing service
• ConvertKit: Creator-focused email marketing

Installation

1. Upload Plugin Files

   • Upload the plugin folder to /wp-content/plugins/
   • Or install via WordPress admin → Plugins → Add New → Upload Plugin

2. Activate Plugin

   • Go to WordPress Admin → Plugins
   • Find "Bitcoin Newsletter" and click "Activate"

3. Verify Installation

   • Check that "Bitcoin Newsletter" appears in your WordPress admin sidebar

Configuration

Initial Setup

1. Access Settings

   • Go to WordPress Admin → Bitcoin Newsletter → Settings

2. General Settings

   • Default Payment Gateway: Choose between CoinSnap or BTCPay Server
   • Default Newsletter Provider: Select your preferred email service
   • Test Mode: Enable for testing (recommended during setup)

Payment Gateway Settings

CoinSnap Configuration

1. Get API Key

   • Sign up at CoinSnap.io
   • Generate an API key from your dashboard

2. Configure in WordPress

   • Go to Bitcoin Newsletter → Settings
   • Enter your CoinSnap API key
   • Set webhook URL

BTCPay Server Configuration

1. Set Up BTCPay Server

   • Install BTCPay Server or use a hosted service
   • Create a store and generate API credentials

2. Configure in WordPress

   • Go to Bitcoin Newsletter → Settings
   • Enter BTCPay Server URL
   • Add API key and store ID
   • Configure webhook URL

Newsletter Provider Settings

MailPoet Setup

1. Install MailPoet

   • Install the MailPoet plugin if not already installed
   • Create a list for newsletter subscribers

2. Configure Integration

   • Go to Bitcoin Newsletter → Settings
   • Select MailPoet as default provider
   • Choose the target list for subscribers

Mailchimp Setup

1. Get API Key

   • Log into your Mailchimp account
   • Go to Account → Extras → API keys
   • Create a new API key

2. Configure Integration

   • Enter Mailchimp API key in plugin settings
   • Select your audience (list) for subscribers

Sendinblue/Brevo Setup

1. Get API Key

   • Log into your Brevo account
   • Go to Settings → API Keys
   • Create a new API key

2. Configure Integration

   • Enter Brevo API key in plugin settings
   • Select your list for subscribers

ConvertKit Setup

1. Get API Key

   • Log into your ConvertKit account
   • Go to Account → Settings → API
   • Copy your API key

2. Configure Integration

   • Enter ConvertKit API key in plugin settings
   • Select your form for subscribers

Creating Newsletter Forms

Basic Form Creation

1. Create New Form

   • Go to Bitcoin Newsletter → Newsletter Forms
   • Click "Add New"

2. Configure Form Fields

   • Email Field: Customize email label (default: "Email Address")
   • Button Text: Set submit button text (default: "Subscribe with Bitcoin")
   • Additional Fields: Enable/disable first name, last name, phone, company
   • Custom Fields: Add up to 2 custom fields with various input types

3. Field Configuration Options

   • Enabled: Toggle field visibility
   • Required: Make field mandatory
   • Label: Customize field label
   • Type: Choose input type (text, email, tel, url, number, select, textarea)
   • Order: Set field display order

Payment Settings

1. Payment Configuration

   • Payment Gateway: Override default gateway for this form
   • Amount: Set Bitcoin payment amount
   • Currency: Choose display currency (converted to Bitcoin)
   • Description: Payment description for users

2. Payment Gateway Override

   • CoinSnap: Enter API key and webhook URL
   • BTCPay Server: Enter server URL, API key, and store ID

Email & Redirect Settings

1. Email Configuration

   • Success Email: Customize confirmation email content
   • Admin Notification: Email sent to admin on new subscription
   • Email Templates: Use placeholders for dynamic content

2. Redirect Settings

   • Success Page: Redirect after successful payment
   • Error Page: Redirect on payment failure
   • Thank You Message: Custom success message

GDPR & Compliance

1. GDPR Settings

   • Enable GDPR: Add consent checkbox
   • GDPR Text: Customize consent message
   • Required Consent: Make GDPR consent mandatory

2. Privacy Settings

   • Data Retention: Set how long to keep subscriber data
   • Right to be Forgotten: Enable data deletion requests

Newsletter Provider Override

1. Provider Selection

   • Override default newsletter provider for this form
   • Choose specific list/audience for subscribers

2. Provider-Specific Settings

   • MailPoet: Select specific list
   • Mailchimp: Choose audience and tags
   • Sendinblue: Select list and attributes
   • ConvertKit: Choose form and tags

Form Styling

1. Button Text

   • Customize submit button text
   • Default: "Subscribe with Bitcoin"

2. Advanced CSS

   • Add custom CSS for form styling
   • Use provided CSS classes for targeting elements
   • Live preview of changes

3. Available CSS Classes

   • .wpbn-form - Main form container
   • .wpbn-form-{ID} - Form with specific ID
   • .wpbn-field - Form field wrapper
   • .wpbn-input - Input fields
   • .wpbn-button - Submit button
   • .wpbn-label - Field labels
   • .wpbn-error - Error messages
   • .wpbn-success - Success messages

Payment Gateway Setup

CoinSnap Integration

1. Account Setup

   - Visit: https://coinsnap.io
   - Create account and verify email
   - Generate API key from dashboard

2. WordPress Configuration

   - Go to: Bitcoin Newsletter → Settings
   - Payment Gateway: Select "CoinSnap"
   - API Key: Enter your CoinSnap API key
   - Webhook URL: Automatically configured

3. Testing

   • Enable test mode in plugin settings
   • Use test invoices (prefixed with "test_")
   • Verify webhook delivery in CoinSnap dashboard

BTCPay Server Integration

1. Server Setup

   - Install BTCPay Server (self-hosted or hosted)
   - Create store and configure settings
   - Generate API key and store ID

2. WordPress Configuration

   - Go to: Bitcoin Newsletter → Settings
   - Payment Gateway: Select "BTCPay Server"
   - Server URL: Enter your BTCPay Server URL
   - API Key: Enter your API key
   - Store ID: Enter your store ID
   - Webhook URL: Configure in BTCPay Server

3. Webhook Configuration

   - In BTCPay Server: Store → Settings → Webhooks
   - Add webhook URL: https://yoursite.com/wp-json/wpbn/v1/webhook/btcpay
   - Select events: Invoice payment received

Newsletter Provider Setup

MailPoet Integration

1. Plugin Installation

   # Install MailPoet plugin
   wp plugin install mailpoet --activate

2. List Creation

   • Go to MailPoet → Lists
   • Create new list for Bitcoin subscribers
   • Note the list ID

3. Plugin Configuration

   • Go to Bitcoin Newsletter → Settings
   • Newsletter Provider: Select "MailPoet"
   • List ID: Enter your MailPoet list ID

Mailchimp Integration

1. API Key Generation

   • Log into Mailchimp
   • Account → Extras → API keys
   • Create new API key

2. Audience Selection

   • Note your audience ID
   • Available in Audience → Settings → Audience name and defaults

3. Plugin Configuration

   • Go to Bitcoin Newsletter → Settings
   • Newsletter Provider: Select "Mailchimp"
   • API Key: Enter your Mailchimp API key
   • Audience ID: Enter your audience ID

Sendinblue/Brevo Integration

1. API Key Generation

   • Log into Brevo
   • Settings → API Keys
   • Create new API key

2. List Creation

   • Go to Contacts → Lists
   • Create new list for Bitcoin subscribers
   • Note the list ID

3. Plugin Configuration

   • Go to Bitcoin Newsletter → Settings
   • Newsletter Provider: Select "Sendinblue"
   • API Key: Enter your Brevo API key
   • List ID: Enter your list ID

ConvertKit Integration

1. API Key Generation

   • Log into ConvertKit
   • Account → Settings → API
   • Copy your API key

2. Form Selection

   • Go to Forms
   • Create or select existing form
   • Note the form ID

3. Plugin Configuration

   • Go to Bitcoin Newsletter → Settings
   • Newsletter Provider: Select "ConvertKit"
   • API Key: Enter your ConvertKit API key
   • Form ID: Enter your form ID

Managing Subscribers

Subscriber Dashboard

1. Access Subscribers

   • Go to Bitcoin Newsletter → Subscribers
   • View all newsletter subscribers

2. Subscriber Information

   • Email address
   • Payment status
   • Payment gateway used
   • Newsletter provider
   • Subscription date
   • Form used

3. Bulk Actions

   • Resync: Re-synchronize subscribers with newsletter provider
   • Export: Export subscriber data
   • Delete: Remove subscribers

Payment Status Management

1. Payment Statuses

   • Pending: Payment not yet confirmed
   • Paid: Payment confirmed and processed
   • Failed: Payment failed or expired
   • Refunded: Payment refunded

2. Manual Actions

   • Resync Payment: Re-check payment status with gateway
   • Force Sync: Manually sync with newsletter provider
   • Mark as Paid: Manually mark payment as confirmed

Logs and Debugging

1. Access Logs

   • Go to Bitcoin Newsletter → Logs
   • View detailed operation logs

2. Log Levels

   • Error: Critical errors requiring attention
   • Warning: Non-critical issues
   • Info: General information
   • Debug: Detailed debugging information

3. Log Categories

   • Payment processing
   • Newsletter synchronization
   • Webhook handling
   • Form submissions

Shortcodes

Basic Form Shortcode

[wpbn_form id="123"]

Parameters:

• id (required): Form ID from Newsletter Forms

Advanced Shortcode Options

[wpbn_form id="123" class="custom-class" style="border: 2px solid #000;"]

Parameters:

• id (required): Form ID
• class: Additional CSS classes
• style: Inline CSS styles

Form Display Examples

1. Simple Form

   [wpbn_form id="1"]

2. Styled Form

   [wpbn_form id="1" class="newsletter-form" style="max-width: 400px; margin: 0 auto;"]

3. Multiple Forms

   [wpbn_form id="1"]
   [wpbn_form id="2"]

Advanced Customization

Custom CSS Styling

1. Form Styling

   .wpbn-form {
     background: #f9f9f9;
     padding: 30px;
     border-radius: 8px;
     box-shadow: 0 4px 6px rgba(0,0,0,0.1);
   }
   
   .wpbn-button {
     background: linear-gradient(45deg, #f7931a, #ff6b35);
     border: none;
     padding: 15px 30px;
     font-size: 18px;
     font-weight: bold;
   }

2. Field Styling

   .wpbn-input {
     border: 2px solid #e1e5e9;
     border-radius: 6px;
     padding: 12px 16px;
     font-size: 16px;
   }
   
   .wpbn-input:focus {
     border-color: #f7931a;
     box-shadow: 0 0 0 3px rgba(247, 147, 26, 0.1);
   }

Custom Hooks and Filters

1. Form Display Filter

   add_filter('wpbn_form_html', function($html, $form_id) {
       // Modify form HTML before display
       return $html;
   }, 10, 2);

2. Payment Success Action

   add_action('wpbn_payment_success', function($subscriber_id, $payment_data) {
       // Custom action after successful payment
       error_log('Payment successful for subscriber: ' . $subscriber_id);
   }, 10, 2);

3. Newsletter Sync Filter

   add_filter('wpbn_newsletter_sync_data', function($data, $subscriber_id) {
       // Modify data before syncing to newsletter provider
       $data['custom_field'] = 'custom_value';
       return $data;
   }, 10, 2);

Custom Payment Gateway

1. Create Custom Provider

   class Custom_Payment_Provider implements Payment_Provider_Interface {
       public function create_invoice($amount, $currency, $description) {
           // Implement invoice creation
       }
   
       public function check_invoice_status($invoice_id) {
           // Implement status checking
       }
   }

2. Register Provider

   add_filter('wpbn_payment_providers', function($providers) {
       $providers['custom'] = new Custom_Payment_Provider();
       return $providers;
   });

Troubleshooting

Common Issues

Payment Not Processing

Symptoms:

• Payment created but not confirmed
• Subscriber not added to newsletter

Solutions:

1. Check Webhook Configuration

   - Verify webhook URL is correct
   - Check webhook is enabled in payment gateway
   - Test webhook delivery

2. Verify API Credentials

   - Check API key is valid and active
   - Ensure proper permissions
   - Test API connection

3. Check Logs

   - Go to Bitcoin Newsletter → Logs
   - Look for error messages
   - Check payment gateway logs

Newsletter Sync Issues

Symptoms:

• Payment confirmed but subscriber not in newsletter
• Duplicate subscribers

Solutions:

1. Manual Resync

   - Go to Bitcoin Newsletter → Subscribers
   - Select affected subscribers
   - Click "Resync" button

2. Check Newsletter Provider Settings

   - Verify API credentials
   - Check list/audience ID
   - Test API connection

3. Review Sync Logs

   - Check logs for sync errors
   - Verify subscriber data format

Form Display Issues

Symptoms:

• Form not displaying
• Styling problems
• JavaScript errors

Solutions:

1. Check Shortcode

   - Verify form ID is correct
   - Check shortcode syntax
   - Test with default form

2. Clear Cache

   - Clear WordPress cache
   - Clear CDN cache
   - Clear browser cache

3. Check Theme Compatibility

   - Test with default theme
   - Check for CSS conflicts
   - Review JavaScript errors

Debug Mode

1. Enable Debug Mode

   - Go to Bitcoin Newsletter → Settings
   - Advanced Settings → Log Level
   - Set to "Debug"

2. Monitor Logs

   - Go to Bitcoin Newsletter → Logs
   - Watch for detailed debug information
   - Check for error patterns

3. Test Mode

   - Enable test mode in settings
   - Use test payment methods
   - Verify test data handling

Performance Optimization

1. Database Optimization

   -- Clean up old logs
   DELETE FROM wp_options WHERE option_name LIKE 'wpbn_log_%' 
   AND option_value < DATE_SUB(NOW(), INTERVAL 30 DAY);

2. Caching

   // Add caching for form data
   add_filter('wpbn_form_cache', '__return_true');

3. Webhook Optimization

   - Use efficient webhook handlers
   - Implement proper error handling
   - Monitor webhook performance

Support

Getting Help

1. Documentation

   • Review this README thoroughly
   • Check WordPress admin help sections
   • Consult payment gateway documentation

2. Logs and Debugging

   • Enable debug mode
   • Check plugin logs
   • Review server error logs

3. Community Support

   • WordPress.org support forums
   • GitHub issues (if applicable)
   • Community discussions

System Requirements

• WordPress: 5.0 or higher
• PHP: 7.4 or higher
• MySQL: 5.6 or higher
• SSL Certificate: Required for payment processing
• cURL: Required for API communications

Plugin Updates

1. Automatic Updates

   • Plugin updates automatically when available
   • Test updates on staging site first
   • Backup before major updates

2. Manual Updates

   • Download latest version
   • Deactivate current plugin
   • Upload new version
   • Reactivate plugin

Backup Recommendations

1. Before Updates

   • Full site backup
   • Database backup
   • Plugin settings export

2. Regular Backups

   • Daily automated backups
   • Weekly manual verification
   • Monthly disaster recovery test

---

Changelog

Version 1.0.0

• Initial release
• CoinSnap and BTCPay Server integration
• MailPoet, Mailchimp, Sendinblue, ConvertKit support
• Custom form builder
• Subscriber management
• GDPR compliance features

---

Plugin Version: 1.0.0
Last Updated: 2025
WordPress Compatibility: 5.0+
PHP Compatibility: 7.4+