taler-docs

wordpress-paivana-manual.rst (23924B)

---

 ..
   This file is part of GNU TALER.
 
   Copyright (C) 2026 Taler Systems SA
 
   TALER is free software; you can redistribute it and/or modify it under the
   terms of the GNU Affero General Public License as published by the Free Software
   Foundation; either version 2.1, or (at your option) any later version.
 
   TALER is distributed in the hope that it will be useful, but WITHOUT ANY
   WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR
   A PARTICULAR PURPOSE.  See the GNU Affero General Public License for more details.
 
   You should have received a copy of the GNU Affero General Public License along with
   TALER; see the file COPYING.  If not, see <http://www.gnu.org/licenses/>
 
   @author Christian Grothoff
 
 .. _wordpress-paivana:
 
 
 Wordpress integration
 =====================
 
 .. note::
 
   This chapter is still early work in progress.
 
 This chapter documents the installation and operation of the
 ``taler-turnstile`` Wordpress plugin.  The plugin gates individual Wordpress
 posts (and any other selected public post type) behind a GNU Taler paywall:
 visitors who have not yet paid are shown a teaser plus a payment widget, and
 once their wallet has paid the associated merchant template the full post
 content is unlocked.
 
 Like its :ref:`Drupal counterpart <drupal-paivana>`, the plugin is built
 around the same Paivana-style flow as :ref:`paivana-httpd <Paivana-httpd>`: a
 static, cacheable paywall page references a *payment template* in the merchant
 backend, no order is created when a visitor merely loads a paywalled article,
 and no PHP session is started for unauthenticated traffic.  This keeps bot
 traffic from polluting the merchant backend and lets Wordpress' page cache (or
 any reverse-proxy cache in front of it) serve the paywall page to anonymous
 visitors without per-request work.
 
 
 Architecture overview
 ---------------------
 
 A Wordpress site using Turnstile combines three independent
 components:
 
 1. **The Wordpress site.**  An ordinary Wordpress 6.3+ installation
    serving one or more public post types (``post``, ``page``, custom
    post types, ...).  The ``taler-turnstile`` plugin adds a
    *Price Category* meta field (stored as the post meta key
    ``_taler_price_category``) to the post types you select, and
    hooks ``the_content`` and ``template_redirect`` to intercept
    rendering of posts that carry a non-empty value.
 2. **A GNU Taler merchant backend** (``taler-merchant-httpd``).
    The backend stores one *payment template* per price category
    defined in Wordpress, manages orders, talks to one or more Taler
    exchanges, and ultimately reports back whether a given order
    has been paid.  See the
    :ref:`Taler Merchant Backend Operator Manual
    <taler-merchant-backend-operator-manual>` for full details.
 3. **The visitor's GNU Taler wallet.**  The wallet scans the QR
    code shown on the paywall page (or follows the
    ``taler://pay-template/…`` link), pays the merchant template
    and triggers the unlock.
 
 Turnstile itself stores no per-visitor state in the Wordpress database; once
 the merchant backend confirms a payment, Turnstile mints a short-lived HMAC
 cookie (``taler_turnstile_paivana``, keyed by Wordpress' built-in
 ``wp_salt('auth')``) that the browser presents on subsequent requests to the
 same fulfillment URL.  Clearing cookies forgets paid access, but GNU Taler
 wallet's repurchase detection will restore the cookie if the user attempts to
 pay for the same article again.
 
   .. note::
 
     This feature likely does not interact well with expiration
     periods for article purchases. This is a bug that will
     require further work to fully address. See #11443.
 
 
 Installation
 ------------
 
 Requirements
 ^^^^^^^^^^^^
 
 - Wordpress 6.3 or later
 - PHP 8.0 or later
 - **Pretty permalinks must be enabled.**  With the default plain
   permalinks (``?p=123``) every post is served from path ``/``,
   which means the path-scoped access cookie cannot be isolated
   per article; the plugin therefore refuses to paywall posts in
   that configuration and shows an admin notice on the settings
   pages until pretty permalinks are turned on under
   *Settings → Permalinks*.
 - A reachable GNU Taler merchant backend supporting the v29 (or
   newer) ``paivana`` template type and the public
   ``/sessions/$SESSION_ID`` endpoint
 - An access token for the merchant instance with the
   ``templates-write`` and ``orders-read`` permissions
 
 
 Obtaining the plugin
 ^^^^^^^^^^^^^^^^^^^^
 
 The plugin sources are available from the GNU Taler Git repository as well as
 Wordpress' own plugin directory.  Download the latest release and extract it
 into your Wordpress installation's ``wp-content/plugins/`` directory so that
 the resulting layout is:
 
 .. code-block:: shell-session
 
    $ ls wp-content/plugins/taler-turnstile/
    admin/      assets/      includes/
    COPYING     README.md    taler-turnstile.php
 
 There is no build step and no Composer package: the plugin is plain PHP and a
 handful of JavaScript files.  The QR code library ``assets/js/qrcode.min.js``
 is vendored from `davidshimjs/qrcodejs
 <https://github.com/davidshimjs/qrcodejs>`__ and must be present for the QR
 code to render; see ``assets/js/QRCODE-README.md`` in the plugin directory for
 the download instructions if you are building from source.
 
 
 Activating the plugin
 ^^^^^^^^^^^^^^^^^^^^^
 
 Once the directory is in place, activate the plugin from
 *Plugins → Installed Plugins* and press *Activate* on the
 *GNU Taler Turnstile* row:
 
 .. image:: screenshots/wordpress-turnstile-plugin-activate.png
 
 Activation registers the plugin's options with their defaults
 (by default, the ``post`` post type is enabled and the backend
 URL/token are left blank) and adds three new admin menu entries:
 
 - *Settings → Taler Turnstile* (main settings),
 - *Settings → Taler Subscriptions* (subscription purchase prices),
 - *Taler Prices* (top-level menu, price-category management).
 
 Deactivating the plugin removes the meta box and stops the
 paywall from rendering, but it does currently **not** delete templates
 already published to the merchant backend; remove those manually
 if desired (see :ref:`template`).
 
 
 Configuring the basics
 ----------------------
 
 The main settings page lives at
 ``wp-admin/options-general.php?page=taler-turnstile-settings``
 and is also reachable through *Settings → Taler Turnstile*.  It
 collects the four pieces of information Turnstile needs to talk
 to the merchant backend and to know which types of content to gate:
 
 .. image:: screenshots/wordpress-turnstile-settings-form.png
 
 The fields are:
 
 - **Enabled Post Types** — a list of checkboxes derived from
   every *public* post type registered on the site (the built-in
   ``post`` and ``page``, plus any custom post types).  Each
   ticked post type gains the *Taler Turnstile Price Category*
   sidebar meta box on its editor screen, and gets it removed
   again when unticked.  Disabling every post type triggers a
   one-shot cleanup that drops the ``_taler_price_category`` meta
   from every post on the site, so re-enabling a post type later
   starts from a clean slate.
 - **Payment Backend URL** — the HTTP(S) base URL of the merchant
   backend.  Instance-specific URLs ending in ``/instances/$ID/``
   are accepted; the URL **must end with a trailing slash**.  When
   you save the form with a non-empty value, Turnstile contacts
   the backend's ``/config`` endpoint to verify reachability and
   refuses to save the value if the backend does not respond as a
   ``taler-merchant`` instance.
 - **Access Token** — the Bearer token used for every call to the
   backend.  It **must begin with** ``secret-token:`` (following
   RFC 8959, see :ref:`Access control
   <taler-merchant-backend-operator-manual>` in the merchant
   manual).  When both URL and token are present, the form
   performs a live authentication check against the backend and
   surfaces the HTTP status as an admin notice if the access
   token is wrong (401/403), the instance does not exist (404),
   or the backend is otherwise unreachable.
 - **Disable Turnstile on Error** (fail-open toggle, off by
   default) — when the merchant backend cannot be reached, this
   controls whether visitors see the unpaywalled article
   (checked) or an error message in place of the payment widget
   (unchecked).  The settings form warns you with an admin
   notice if you leave the toggle off while the backend URL or
   access token is missing, so a misconfiguration cannot
   silently break the live site.
 
 The first time you save a working backend URL and access token,
 Turnstile pushes a ``paivana``-style template to the merchant
 backend for every price category that already exists.  Each
 template carries the ID ``turnstile-{category_id}``.  You do not
 need to create those templates by hand, and you do not need to
 visit the merchant backend's SPA to manage them — Turnstile keeps
 them in sync as you edit the categories (see
 :ref:`wordpress-paivana-price-categories` below).  Saving a new
 backend URL or access token also republishes every existing
 price-category template, on the assumption that the new instance
 does not have them yet.
 
 Before continuing, make sure that the merchant backend instance
 itself is ready to take payments:
 
 - The instance has at least one configured
   :ref:`bank account <instance-bank-account>`.
 - Any legitimization required by the chosen payment service
   provider has been completed.
 
 
 .. _wordpress-paivana-subscription-prices:
 
 Configuring subscription prices
 -------------------------------
 
 .. note::
 
   The term *subscription* is slightly misleading, as it is not
   auto-renewing. We are in the process of renaming this to *passes* which is
   clearer. However, the current plugin uses subscription and thus so does this
   manual.
 
 Turnstile supports the GNU Taler subscription model, in which a visitor buys a
 *subscription token* once and the token is then consumed to unlock individual
 articles for some validity period.  The catalogue of available *token
 families* is configured on the merchant backend (see the merchant manual
 section on :ref:`templates <template>` and the wider Taler concept of
 subscription tokens); Turnstile reads the catalogue live from
 ``private/tokenfamilies`` and asks you to set the *purchase price* per token
 family per currency.
 
 Navigate to *Settings → Taler Subscriptions* (URL
 ``wp-admin/admin.php?page=taler-subscription-prices``).  The page refuses to
 render until the backend is configured and reachable — it needs the live
 token-family list and a complete currency inventory from ``/config``.  When
 the backend is ready, the page lists one *postbox* block per token family
 advertised by the backend, with one numeric input per supported currency:
 
 .. image:: screenshots/wordpress-turnstile-subscription-list.png
 
 Leaving a field empty disables the *Buy subscription in
 {currency}* payment choice for that combination — the
 subscription will then not be offered for sale in that currency
 on any article.
 
 If the merchant backend has no token families configured, the page shows a
 warning and offers nothing to edit.  In that case you can still operate
 Turnstile in pure pay-per-article mode; simply skip this configuration step.
 
 Whenever this page is saved, Turnstile republishes **every** price-category
 template against the backend so the new subscription prices appear in the
 wallet's *Buy subscription* choices immediately.
 
 .. note::
 
   GNU Taler token families offer more flexible payment options,
   not just subscriptions. However, only subscriptions are
   supported by Turnstile at this time.
 
 
 .. _wordpress-paivana-price-categories:
 
 Defining price categories
 -------------------------
 
 A *price category* is a named set of payment options that can be attached to
 posts.  Categories are managed under the top-level *Taler Prices* menu in the
 admin sidebar (URL ``wp-admin/admin.php?page=taler-price-categories``).  The
 list page shows the existing categories together with their descriptions and
 offers *Edit*, *Delete* and *Add New* actions:
 
 .. image:: screenshots/wordpress-turnstile-price-category-list.png
 
 
 Creating or editing a price category
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
 Click *Add New* (or *Edit* on an existing row) to reach the
 price-category form.  The form has two sections:
 
 - **Name** — human-readable label for the category (e.g.
   *Standard article*, *Long-form feature*).  Shown to editors
   when they pick a category on a post-edit screen and used as
   the merchant template's summary text.
 - **Description** — free text shown to editors and used as the
   template description on the merchant backend if non-empty.
 
 Below the meta fields, the form has one *Prices* postbox per known token
 family, plus a special block labelled *No reduction* that holds the price for
 non-subscribers.  Each block contains one numeric input per supported
 currency:
 
 .. image:: screenshots/wordpress-turnstile-price-category-edit.png
 
 Pricing semantics:
 
 - A value in the *No reduction* block sets the **per-article
   price for visitors without a subscription** in that currency.
   Leave it empty to make the article available **only** to
   subscribers in that currency.
 - A value in a subscription block sets the **discounted price
   for holders of that subscription token** in that currency.  A
   value of exactly ``0`` marks the article as *fully covered* by
   that subscription — subscribers see it for free.  An empty
   field means "this subscription does not unlock articles of
   this category in this currency", so a holder of such a
   subscription has to pay the full per-article price.
 
 At least one price (across all blocks and currencies) must be set; otherwise
 the category yields no valid payment choices and the matching template cannot
 be published.
 
 Saving the form publishes the category as a ``paivana``-style template to the
 merchant backend (the v1 ``choices`` array is built from the price grid; see
 :ts:type:`TemplateContractPaivana` in the :ref:`Merchant Backend HTTP API
 <merchant-api>`).  If the local save succeeds but the backend push fails
 (network error, 401, ...), the admin notice on the next page surfaces the
 error.
 
 .. note::
 
   In this case, the local price in Wordpress and the merchant
   template may have drifted out of sync. Visitors would still
   pay the price in the merchant backend, so this error should
   always be investigated.
 
 Editing a category or changing prices automatically refreshes the matching
 merchant template via ``PATCH``.  Deleting a category removes its template via
 ``DELETE``; if the delete on the backend fails, you are warned to clean it up
 manually.
 
 
 Gating individual posts
 -----------------------
 
 Once a post type is enabled in the basic settings (see above)
 and at least one price category exists, every post of that
 post type gains a new *Taler Turnstile Price Category* sidebar
 meta box on its editor screen (shown in the bottom right corner):
 
 .. image:: screenshots/wordpress-turnstile-post-meta-box.png
 
 To paywall a post:
 
 1. Edit or create a post of an enabled post type.
 2. Pick a category in the *Price Category* drop-down on the
    sidebar meta box.
 3. *Update* / *Publish* the post.
 
 Leaving the drop-down on *-- None --* leaves the post freely accessible — the
 paywall logic only fires for posts that reference a category.
 
 If you want to remove the paywall from a post, edit it and change the meta box
 back to *-- None --*.  If you want to lift the paywall from an entire post
 type, untick it in the *Enabled Post Types* list on the settings page; the
 meta box and the post meta are then removed from every post of that post type.
 Re-enabling the post type later starts from a clean slate, forcing you to set
 the price categories again for all posts of that type.
 
 
 The visitor experience
 ----------------------
 
 Anonymous visitor without a cookie
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
 For a post that references a price category, an anonymous
 visitor without a valid ``taler_turnstile_paivana`` cookie sees:
 
 - The post rendered as its *excerpt* (the explicit ``excerpt``
   field, or the first 55 words of the body if none is set).
 - A *Payment Required* block immediately below the excerpt with
   a QR code (encoding the ``taler://pay-template/…`` URI for the
   matching merchant template), a *Scan with your GNU Taler
   wallet* hint, and — when the browser advertises support for
   the ``taler`` URI scheme — an *Open GNU Taler payment page*
   button.
 - A pricing summary showing the per-article price (or "Not sold
   individually" if only subscriptions unlock the category) and
   the list of subscriptions that accept this category.
 - A *Waiting for payment…* status line that updates once the
   wallet picks up the order.
 
 .. image:: screenshots/wordpress-turnstile-paywall-page.png
 
 The page is identical for every visitor without the cookie, so Wordpress' page
 cache (and any reverse-proxy cache in front of it) can serve it without
 per-request work.  The response sets ``Vary: Cookie`` so a returning paying
 visitor's path-scoped access cookie still busts the cached paywall, and the
 ``taler://pay-template/…`` URI is also advertised as a ``Paivana:`` HTTP
 header for non-JavaScript Taler clients.
 
 Behind the scenes, the JavaScript on the page does **not** create an order in
 the merchant backend.  It generates a fresh nonce, derives a session ID from
 it (the ``paivana_id``), renders the QR code, and long-polls the public
 ``sessions/{paivana_id}`` endpoint on the merchant backend waiting for the
 wallet to pick the template up and pay.  No order, no PHP session and no
 database write happens until the visitor's wallet actually engages with the
 template.
 
 
 Paying
 ^^^^^^
 
 The visitor scans the QR code with a `GNU Taler wallet
 <https://docs.taler.net/wallet/>`__ (or clicks the *Open GNU Taler payment
 page* button when running a browser with a wallet extension).  The wallet
 shows the available payment choices — for a typical category these are:
 
 - *Pay in {currency}* — the per-article price for non-subscribers.
 - *Pay in {currency} with subscription* — only offered to
   visitors whose wallet holds a matching, unspent subscription
   token (in which case it usually costs ``{currency}:0``).
 - *Buy subscription in {currency}* — pays the per-article price
   plus the subscription's purchase price (from
   :ref:`wordpress-paivana-subscription-prices` above) and yields
   a fresh subscription token in the visitor's wallet.
 
 The visitor picks an option, the wallet pays, and Wordpress'
 JavaScript proceeds to the confirmation step.
 
 
 Confirmation and unlock
 ^^^^^^^^^^^^^^^^^^^^^^^
 
 Once the merchant backend reports the order as paid, the JavaScript POSTs
 ``{order_id, nonce, cur_time, website}`` to the plugin's REST endpoint at
 ``/wp-json/taler-turnstile/v1/paivana``.  The Wordpress-side controller
 re-derives the canonical ``paivana_id``, resolves the fulfillment URL back to
 a local post via ``url_to_postid()``, fetches the order from the merchant
 backend and **verifies that the paid contract's ``fulfillment_url`` matches
 the requesting page and that the paid amount is one of the amounts the price
 category accepts**.  Only then does it mint the ``taler_turnstile_paivana``
 cookie and instruct the browser to reload the article.
 
 The cookie is keyed on Wordpress' built-in ``wp_salt('auth')``, bound to the
 visitor's ``REMOTE_ADDR`` and ``Path``-scoped to the specific fulfillment URL,
 marked ``HttpOnly``, ``SameSite=Lax``, and ``Secure`` when the page was served
 over HTTPS.  It is valid for 24 hours (the ``ORDER_VALIDITY_SECONDS`` constant
 in ``Taler_Merchant_API``; this will follow the merchant-supplied
 ``pay_deadline``/``max_pickup_time`` in the future).  The cookie covers
 exactly one fulfillment URL — clearing cookies forgets paid access, and access
 to a different paywalled article requires a fresh payment (or a valid
 subscription).
 
 The REST confirmation endpoint is unauthenticated by design (the payer has no
 Wordpress account) and is therefore rate-limited per-IP to at most 30 requests
 per minute, comfortably above legitimate use but capping the abuse of an
 endpoint that triggers a merchant-backend round-trip per call.
 
 .. note::
 
   ``ORDER_VALIDITY_SECONDS`` should probably be made
   configurable in the future, as should the restriction of the
   client to a particular IP address, as that may or may not be
   desired. See #11444.
 
 
 Subscriptions in action
 ^^^^^^^^^^^^^^^^^^^^^^^
 
 When a paid contract bought a subscription token, Turnstile also stores the
 token family slug and the token's expiration time in the visitor's PHP session
 (the session is started only *after* the successful payment, so the cacheable
 pre-payment path is unaffected).  Subsequent requests to other posts whose
 price category is fully covered by the same subscription short-circuit the
 paywall entirely: the visitor never sees the *Payment Required* block again
 until the token expires.
 
 Visitors without a PHP-session cookie still see the paywall page (so
 anonymous, cache-friendly traffic stays cacheable); the subscriber check is
 gated on the session cookie already being present so that loading a paywalled
 post never creates a session on its own.
 
 
 Operational notes
 -----------------
 
 Caching
 ^^^^^^^
 
 The plugin emits cache-control headers tuned for the two paths it produces:
 
 - The static paywall response carries ``Vary: Cookie``, so a
   shared cache (page cache plugin, reverse proxy, CDN) can store
   one copy for all anonymous visitors while still busting it for
   returning paying visitors whose path-scoped
   ``taler_turnstile_paivana`` cookie now accompanies their
   request.
 - The post-payment response (the article, served only to the
   visitor who paid) is marked ``Cache-Control: private,
   no-store`` and triggers the ``DONOTCACHEPAGE`` define plus
   ``nocache_headers()`` so it never lands in a shared cache.
 - The REST confirmation endpoint under ``/wp-json/`` is not
   page-cached by Wordpress, and its response is explicitly
   marked ``no-store``.
 
 A reverse-proxy cache in front of Wordpress must therefore honour the ``Vary:
 Cookie`` header to avoid handing one paying visitor's full-content response to
 another visitor.
 
 
 Logging
 ^^^^^^^
 
 The plugin writes to PHP's ``error_log`` (i.e. the destination your
 ``php.ini`` or web server configures for ``error_log``).  Notable events that
 are logged include unreachable backends, malformed responses from the merchant
 backend, paid orders whose contract does not match the fulfillment URL or
 whose paid amount falls outside the price category, and template
 create/update/delete failures.  When debugging an integration problem, tailing
 the PHP error log while reproducing the issue is usually the fastest way to
 identify the culprit.
 
 
 Permissions
 ^^^^^^^^^^^
 
 All admin pages — the basic settings, the subscription prices and the
 price-category CRUD — are gated on Wordpress' ``manage_options`` capability,
 which corresponds to the *Administrator* role.  Editors who only need to
 assign a price category to a post do not need *manage_options*: the sidebar
 meta box is rendered for any user who can edit the post in question
 (``edit_post`` capability check on the meta field).
 
 
 Hooks and filters
 ^^^^^^^^^^^^^^^^^
 
 The plugin exposes a small number of WordPress filters so a theme or
 site-specific plugin can adapt Turnstile to local conventions without forking
 it:
 
 - ``taler_turnstile_enabled_post_types`` — alter the list of
   post types subject to the paywall transformation.
 - ``taler_turnstile_payment_choices`` — modify the payment
   ``choices`` array before it is sent to the merchant backend.
 - ``taler_turnstile_currencies`` — add to or modify the
   list of currencies discovered from the backend's ``/config``.
 
 These hooks are intentionally narrow; deeper customisation (for example,
 overriding the paywall HTML) requires patching
 ``Taler_Content_Filter::render_paywall()`` directly.