README.md (7496B)
1 # GNU Taler Turnstile 2 Contributors: gnutaler 3 Tags: payment, monetization, privacy, subscription 4 Requires at least: 6.3 5 Tested up to: 6.8 6 Stable tag: 1.1.0 7 Requires PHP: 8.0 8 License: GPLv2 or later 9 A WordPress plugin that adds price fields to posts and requires 10 payment via GNU Taler for access. 11 12 ## Description 13 14 GNU Taler Turnstile enables authors to monetize their WordPress 15 articles using the GNU Taler payment system. The plugin allows you to: 16 17 - Set prices for individual posts/pages 18 - Create price categories with different pricing tiers 19 - Support multiple currencies 20 - Offer subscription-based access 21 - Configure payment through GNU Taler merchant backend 22 23 ## Installation 24 25 1. Upload the `taler-turnstile` folder to the `/wp-content/plugins/` directory 26 2. Activate the plugin through the `Plugins` menu in WordPress 27 3. Configure your GNU Taler merchant backend in `Settings` > `Taler Turnstile` 28 4. Create price categories under `Taler Prices` 29 30 ## Configuration 31 32 ### Basic Settings 33 34 0. Make sure you have the credentials of your Taler merchant backend at hand 35 1. Navigate to `Settings` > `Taler Turnstile` 36 2. Select which post types should support paid content 37 3. Configure your payment backend URL (must end with `/`) 38 4. Enter your access token (must start with `secret-token:`) 39 5. Optionally enable "Disable Turnstile on Error" for graceful degradation 40 6. Save settings - this will automatically add price category fields to selected post types 41 42 ### Subscription Prices (optional) 43 44 After configuring the basic settings: 45 46 0. Make sure you have subscriptions configured in the Taler merchant backend 47 1. Navigate to `Settings` > `Taler Subscriptions` 48 2. Set prices for buying each subscription type in different currencies 49 3. Leave fields empty to prevent purchasing that subscription with that currency 50 4. Save subscription prices 51 52 ### Price Categories 53 54 1. Navigate to `Taler Prices` 55 2. Click "Add New" to create a price category 56 3. Set prices for users without a subscription and for different subscription types and currencies 57 (leave blank to not allow buying with that currency, use 0 if the article is 100% included 58 in the subscription). 59 4. Save the category 60 61 ### Sell articles 62 63 1. Select `Edit` on an individual post or page you want to monetize 64 2. Assign a price category to the individual post/page via the meta box in the editor 65 3. Save the article 66 67 ## Requirements 68 69 - WordPress 5.0 or higher 70 - PHP 8.2 or higher 71 - GNU Taler merchant backend instance 72 73 ## File Structure 74 75 ``` 76 taler-turnstile/ 77 ├── taler-turnstile.php # Main plugin file 78 ├── includes/ 79 │ ├── class-taler-merchant-api.php 80 │ ├── class-price-category.php 81 │ ├── class-field-manager.php 82 │ └── class-content-filter.php # Paywall logic 83 ├── admin/ 84 │ ├── class-admin-settings.php 85 │ ├── class-price-category-admin.php 86 │ └── class-subscription-prices-admin.php 87 ├── assets/ 88 │ ├── css/ 89 │ │ ├── admin.css 90 │ │ └── frontend.css # Paywall styles 91 │ └── js/ 92 │ ├── admin.js 93 │ ├── payment-button.js # QR code & polling 94 │ ├── qrcode.min.js # (download separately) 95 │ └── QRCODE-README.md 96 └── README.md 97 ``` 98 99 ## Features 100 101 - **Content Paywall**: Automatically restricts access to paid content, showing excerpt + payment button 102 - **Payment Link**: Opens the payment dialog in the merchant backend, which can automatically trigger the Taler WebExtension wallet 103 - **QR Code Payment**: Generates QR codes for easy mobile wallet payments 104 - **Payment Polling**: Real-time payment status checking with automatic page reload on completion 105 - **Session Management**: Tracks paid access and active subscriptions in per visitor session 106 - **Flexible Pricing**: Set prices per subscription type and currency 107 - **Multiple Currencies**: Support for EUR, USD, CHF, and more (fetched from GNU Taler merchant backend) 108 - **Subscription Support**: Offer subscription-based access with token families 109 - **Subscription Pricing**: Configure prices for purchasing subscriptions (user can buy article or subscribe and pay discounted price for the article) 110 - **Zero-Price Subscriptions**: Automatically grant access for subscriptions with zero price 111 - **Post Type Support**: Enable paid content for any public post type 112 - **Dynamic Field Management**: Automatically adds/removes price category fields when post types are enabled/disabled2 113 - **Meta Box Integration**: Easy price category selection in the post editor 114 - **Error Handling**: Graceful degradation when backend is unavailable 115 - **Cache Control**: Automatically disables caching for protected content 116 - **Caching**: Efficient caching of backend data using WordPress transients 117 118 ## How It Works 119 120 ### For Visitors 121 122 1. **View Protected Content**: When a visitor views a post with a price category assigned, they see: 123 - An excerpt/teaser of the content 124 - A payment button with QR code and a link for in-browser payments with GNU Taler 125 126 2. **Make Payment**: The visitor can: 127 - Scan the QR code with their Taler wallet app 128 - Click the payment button to open their wallet 129 - They will see payment options: 130 + pay full amount for individual article 131 + pay discounted amount with subscriptions (if they already have 132 a subscription that results in a discount) 133 + buy subscription 134 - Choose their preferred payment option (currency and subscription type) 135 - If they are already a subscriber with a discounted price of zero, 136 the wallet will automatically choose and execute that option 137 138 3. **Automatic Access**: Once payment is completed: 139 - The page automatically refreshes (via polling) 140 - Full content is displayed 141 - Access is stored in the session 142 - If a subscription was purchased, it's tracked for future visits 143 in this session and user only needs the wallet again after the 144 session ends 145 146 ### For Administrators 147 148 1. **Configure Backend**: Set up the GNU Taler merchant backend connection 149 2. **Set Subscription Prices**: Configure how much subscriptions cost to purchase 150 3. **Create Price Categories**: Define pricing tiers for content 151 4. **Assign Categories**: Select price categories when editing posts 152 5. **Publish**: Protected content automatically shows the paywall 153 154 ### Session Tracking 155 156 The plugin tracks: 157 - **Paid Access**: Which posts the visitor has paid for in this session 158 - **Active Subscriptions**: Which subscriptions are active and when they expire 159 - **Pending Orders**: Orders that haven't been paid yet (to avoid creating duplicates) 160 161 ### Subscription Logic 162 163 - If a subscription reduces the price to **zero**, full access is granted immediately 164 - If a subscription provides a **discount**, the visitor pays the reduced price 165 - Subscriptions can be **purchased** alongside content access 166 - Subscription expiration is tracked per-session 167 168 ### Hooks and Filters 169 170 The plugin provides several hooks for customization: 171 172 - `taler_turnstile_enabled_post_types` - Filter enabled post types 173 - `taler_turnstile_payment_choices` - Modify payment choices 174 - `taler_turnstile_currencies` - Add or modify supported currencies 175 176 ## Support 177 178 For issues and questions: 179 - GNU Taler: https://taler.net 180 - Documentation: https://docs.taler.net 181 182 ## License 183 184 This plugin is licensed under GNU GPL v2 or later. 185 186 ## Credits 187 188 The code is based on an initial AI-assisted transformation of 189 the GNU Taler Turnstile module for Drupal.