Dude Paywall Documentation

Dude Paywall — User Guide

This guide is for site owners and administrators who sell access to individual posts and pages with Dude Paywall. It explains setup, paywalls, checkout, access recovery, and day-to-day use. Current product version: 1.0.29.

What Dude Paywall does

Dude Paywall lets you:

• Sell one-off access to a post or page via Stripe Checkout (payment happens on Stripe’s pages, not inside WordPress).
• Show a free preview, then a paywall gate (Gutenberg Dude Paywall Break block or shortcode).
• Unlock content with a passwordless magic link and a secure browser session cookie.
• Manage purchases under Transactions and access under Entitlements.

You do not need WooCommerce or a membership plugin. There is no shopping cart—each purchase unlocks one piece of content for that customer email.

Requirements

Paid checkouts use Stripe Checkout only. Card data is never stored on your WordPress site.

Installation

1. Install Dude Paywall from the WordPress plugin directory, or upload the plugin ZIP under Plugins → Add New → Upload Plugin.
2. Activate the plugin.
3. In the admin sidebar, open Dude Paywall.

On first use you may see a Freemius opt-in screen. You can skip it—the free plugin works without a licence. A Pro licence (purchased separately) unlocks advanced features described below.

Quick start (about five minutes)

1. Connect Stripe — Dude Paywall → Settings. Add your Stripe test publishable and secret keys, leave Test mode enabled, and click Save and test Stripe connection. See Connecting Stripe.
2. Webhooks — Add a Stripe webhook endpoint (Test mode) pointing at your Paywall webhook URL and paste the signing secret. See Webhook endpoint.
3. Protect a post — Edit a post or page → Dude Paywall sidebar → enable the paywall, set price and currency → insert the Dude Paywall Break block (or ) where free preview should end → Update.
4. Test — Open the post in a private/incognito window. Use Stripe test card 4242 4242 4242 4242 with any future expiry and CVC.

Admin menu overview

Administrator capability (manage_options) is required for these screens.

Connecting Stripe

Dude Paywall uses manual API keys from your Stripe Dashboard.

Test mode (recommended first)

1. In Stripe Dashboard, enable Test mode (toggle in the dashboard).
2. Go to Developers → API keys and copy the Publishable key and Secret key (test).
3. In WordPress, open Dude Paywall → Settings.
4. Enable Use Stripe test keys (Test mode).
5. Paste keys into Test publishable key and Test secret key.
6. Click Save and test Stripe connection. In test mode this also probes inbound webhooks. You should see a success message when keys and webhooks are healthy.

Keys show masked placeholders after saving so you can confirm the correct keys are stored. Leave a field blank when saving to keep the existing value.

Webhook endpoint (live sites and reliable local testing)

Stripe notifies WordPress when a payment succeeds. The plugin shows your webhook URL on the Settings screen:

https://YOUR-SITE/wp-json/dude-paywall/v1/webhooks/stripe

This is not the same URL as Dude Downloads. Each plugin needs its own Stripe webhook endpoint and signing secret.
On a public live site:

1. In Stripe: Developers → Webhooks → Add endpoint (use the same Test / Live mode as the plugin).
2. Paste the URL above.
3. Subscribe to only these events (do not select all events):
   • checkout.session.completed
   • checkout.session.async_payment_succeeded
   • checkout.session.async_payment_failed
   • checkout.session.expired
   • charge.refunded
4. Copy the Signing secret (whsec_…) into Test webhook secret or Live webhook secret in plugin settings (matching test vs live mode).

On Local WP or other offline dev sites: Stripe cannot reach your machine. Either use the Stripe CLI to forward events to the webhook URL, or use Allow confirming payments via Stripe API when webhooks are unavailable (test mode only)—see Troubleshooting.

Going live

1. Complete Stripe account activation and switch the Dashboard to Live mode.
2. In plugin settings, disable Test mode and enter Live publishable, secret, and webhook signing secrets.
3. Create a Live webhook endpoint with the same URL and five events; paste the live whsec_….
4. Disable local “confirm without webhooks”—live sites must rely on webhooks.
5. Run a real small-value purchase to confirm unlock and email delivery.

Protecting a post or page

1. Ensure the post type is enabled under Dude Paywall → Settings → Enabled post types (defaults: post and page).
2. Edit the content → open the Dude Paywall sidebar meta box.
3. Enable the paywall and set price (major units, e.g. 4.99) and currency.
4. Optionally set a Featured image on the post—it can appear on Stripe Checkout.
5. Insert the Dude Paywall Break where free preview should end.
6. Update / Publish.

Posts with the paywall on show a shield icon on the Posts / Pages list (and a “Paywalled” state next to the title).

Paywall break (block or shortcode)

Content above the break is free. Content below is locked until purchase (or a valid access session).

Use one break per post. Do not wrap content inside the shortcode—place it as a self-closing marker between free and paid sections.
If no break is present, the gate still appears and the entire body is treated as paid.

What your customers experience

1. Visitor sees free preview content, then the paywall gate (headline, description, price, unlock button).
2. They click unlock and are redirected to Stripe Checkout.
3. If Stripe Tax is enabled, Checkout collects a billing address and shows calculated tax before payment.
4. After payment, Stripe returns them to your site.
5. When the webhook confirms payment, they receive a magic link email and a browser session that unlocks the paid content.
6. Later visits with the same browser session keep access. They can use Already purchased? on the gate to recover access by email.

If confirmation is still pending for a few seconds, the return page may wait for the webhook. On Local test mode, use Confirm payment (local test) when enabled.

Cancelled checkout

If the customer abandons Stripe Checkout, they return without access and no payment is taken.

Access model

• One purchase → one post/page entitlement.
• One magic-link session can open all active entitlements for that email.
• Recovery requests are rate-limited.
• The WordPress REST API applies the same free/paid split to content.rendered for locked posts.

Editors are not unlocked on the public front end. Use Post Preview or ?dudepw_preview=1 to preview unlocked content.

Transactions

Dude Paywall → Transactions lists checkouts and purchases.

• Open a row for customer email, amounts, Stripe IDs, and status.
• Pro: advanced filters (status, post, email, date range) and Export CSV.

Transaction statuses

Entitlements

Dude Paywall → Entitlements shows who can access which post.

• Free plan: view the list.
• Pro: manually grant or revoke access, bulk revoke / resend, and per-row resend of access email.

A full Stripe refund (via charge.refunded) revokes the related entitlement.

Settings reference

Stripe

• Test mode — Use test API keys and test webhooks.
• Allow confirming payments when webhooks are unavailable — Test mode only; shows Confirm payment (local test) on the return page. Do not use on production.
• Stripe Tax — Enable Collect tax with Stripe Tax, then set Price tax behavior (exclusive or inclusive). Requires Tax registrations in the Stripe Dashboard.
• Default currency — Default for new paywalls.
• Webhook endpoint — Copy into Stripe Dashboard (Paywall URL, not Downloads).
• API keys / webhook secrets — Leave blank when saving to keep the stored value (masked placeholders).
• Save and test Stripe connection — Verifies keys; in test mode also probes inbound webhooks.

Paywall / content

• Enabled post types — Which types show the Dude Paywall meta box and can be gated.
• Success / cancel pages — Optional pages after Checkout.
• Session lifetime / magic link TTL / recovery rate limit — Access and recovery behaviour.

Outgoing webhooks (Pro)

Send signed JSON events to automation tools (Make, n8n, Zapier, custom URL). Configure under Settings; use Tools to send a test and view delivery logs.

Logging & data

• Log level / Log retention — Plugin diagnostic logging.
• Delete plugin data on uninstall — When enabled, removing the plugin deletes tables, meta, and settings. Use with care.

Dude Paywall Pro

Pro is a separate package licensed through Freemius. The free plugin includes unlimited protected posts/pages, Stripe Checkout, the break block/shortcode, magic-link access, inbound webhooks, and basic transactions/entitlements lists.

Pro adds:

Activate Pro from Dude Paywall → Account (Freemius) after purchase.

Email delivery

Access and notification emails are sent with WordPress’s wp_mail(). If customers do not receive mail:

• Install and configure an SMTP plugin (common on shared hosting).
• Check spam folders.
• Confirm Settings → General site email is valid.
• On local dev, use a mail catcher (e.g. Mailhog) or an SMTP relay.

Troubleshooting

“Connected to Stripe” fails

• Confirm you copied the full secret key (sk_test_… or sk_live_…).
• Ensure test vs live keys match the Test mode checkbox.
• Check PHP can make outbound HTTPS requests (firewall, hosting restrictions).

Payment succeeded in Stripe but content stays locked

• Webhook not configured, wrong mode (Test vs Live), or wrong signing secret for this endpoint.
• Webhook URL must be the Paywall URL (…/dude-paywall/v1/webhooks/stripe), not Dude Downloads.
• Webhook URL must be publicly reachable (not localhost without CLI forwarding).
• Open Transactions—if status is still pending, the webhook did not complete.
• On local test mode: enable confirm-without-webhooks and click Confirm payment (local test).
• Hosting firewall / CDN: allow Stripe POSTs to /wp-json/dude-paywall/.

Gate never appears

• Paywall must be enabled on the post.
• Post type must be in Enabled post types.
• View as a logged-out visitor (or private window).

Paid content still visible without paying

• Insert a Paywall Break (or shortcode) so free vs paid is split.
• Confirm you are not viewing with an active entitlement session or ?dudepw_preview=1.

Tax is £0.00 or “Enter address to calculate”

• Confirm Stripe Tax is enabled in plugin settings and you have active Tax registrations in Stripe Dashboard → Tax for that mode (test vs live).
• The buyer must enter a billing address on Checkout.

Need technical details for support

Open Dude Paywall → System Status and note plugin version, webhook URL, whether the webhook secret is configured, and last webhook received time. Share WordPress/PHP versions and test vs live mode—never paste secret keys.

Privacy and external services

• Stripe processes payments under Stripe’s terms and privacy policy.
• Freemius (optional opt-in / licensing) may collect usage data per their policy when you connect an account.
• Customer email addresses are stored with transactions and entitlements for fulfilment and admin visibility.

Frequently asked questions

Do I need WooCommerce?
No. Dude Paywall is standalone.

Is this a membership / subscription plugin?
No. Each purchase is a one-off unlock for one post or page.

Can one purchase unlock the whole site?
No. One purchase unlocks one post/page. One browser session can access all active entitlements for that email.

Can I change the price after someone bought?
Existing transactions keep the amount paid. New checkouts use the current price.

Does it work with page builders?
Use in an HTML or shortcode widget between free and paid content. Some builders that bypass the_content may need a theme that outputs post content through WordPress filters.

Where is card data stored?
On Stripe’s servers only, not in WordPress.

Does the plugin calculate VAT / sales tax?
No. Optionally enable Stripe Tax so Stripe calculates and collects tax from the buyer’s location. Register jurisdictions in the Stripe Tax dashboard.

How is this different from Dude Downloads?
Dude Downloads sells files. Dude Paywall sells access to post/page content. They use different webhook URLs and settings.