WordPress Plugin

Complete guide to the TransX402 WordPress plugin — set up IDRX paywalls on your WordPress site without writing any code.

Overview

The TransX402 WordPress plugin enables site owners to monetize content with IDRX micropayments — no coding required. Just install the plugin, enter your API key and merchant wallet, set prices in IDR, and toggle paywalls on individual posts or pages.

The plugin lives in a separate repository from the TransX402 monorepo: transx402-wordpress.

This is the first x402 plugin in the WordPress ecosystem — no other x402 WordPress plugin exists yet.

Requirements

WordPress 6.0+
PHP 8.0+
A TransX402 account with an API key (register at dashboard.transx402.com)

Installation

From GitHub Release

Download the plugin ZIP from GitHub releases
Go to Plugins > Add New > Upload Plugin
Select the ZIP file and click Install Now
Activate the plugin

Manual Upload

Clone or copy the plugin into wp-content/plugins/transx402-wordpress/
Activate TransX402 Paywall from the Plugins screen

Configuration

Main Settings

Go to Settings > TransX402 in the WordPress admin:

Setting	Description
API Key	TransX402 API key (`ipk_sandbox_...` or `ipk_live_...`) — stored server-side only
Merchant Wallet	Your payout wallet from the TransX402 dashboard (auto-detected after first payment)
Facilitator URL (optional)	Override for local development (e.g. `http://localhost:3402`)
Default Price (IDR)	Default price for paywalled content (e.g., 5000)
Preview Length	First paragraph / First N words / Post excerpt
Paywall Style	Overlay / Inline / Blur
Custom Message	Custom message on the paywall
Enable for	Posts / Pages / Custom post types

Note: Network and token configuration come from the TransX402 facilitator (GET /config). The plugin uses server settlement — PHP calls POST /facilitate with your API key; the browser never sees the key.

Per-Post/Page Configuration

In the post/page editor sidebar, you'll see the TransX402 metabox:

Setting	Description
Enable Paywall	Toggle to enable paywall for this content
Price (IDR)	Override the default price (optional)
Preview Content	Custom preview text (optional)

How It Works

Settlement Mode: Server (Canonical)

The plugin uses server settlement — the same canonical flow as the Next.js paid-content example:

Browser requests full content via REST (GET /wp-json/transx402/v1/content/:postId)
PHP returns 402 Payment Required with x402 payment instructions
Visitor connects wallet (MetaMask, etc.) and signs Permit2 authorization
Browser retries with PAYMENT-SIGNATURE header
PHP calls POST /facilitate with your server API key
PHP verifies the payment via GET /payments/:txHash
Payment is recorded in the WordPress database and content is returned

The browser loads @transx402/client from CDN with settlement: "server" — it signs and retries, but never calls /facilitate directly.

For Visitors (Frontend)

Visitor opens a paywalled article
Sees the article preview plus the paywall card
Clicks "Pay with IDRX"
Connects wallet and completes Permit2 approval (one-time)
Signs the payment authorization (gasless settlement)
Article unlocks immediately
Return visits are free — access is restored from the WordPress DB using the payer cookie

Content Gating

The plugin hooks into WordPress's the_content filter:

// Full content is NEVER sent to the browser for paywalled posts
// PHP truncates content at the preview boundary and injects the paywall UI
// After payment, JS fetches full content via the REST API

Premium content is secure — it cannot be accessed by disabling JavaScript or viewing the HTML source.

Payment History (WordPress Database)

Verified payments are stored in {prefix}transx402_payments:

Access control — return visits check (post_id, payer_address) in the DB
Admin reporting — view payments under Settings > TransX402 Payments

Each row records: transaction hash, payer wallet, amount (IDR), post ID, network, resource URL, and verification timestamp.

After the first successful payment, the merchant wallet is also cached in plugin settings.

Paywall Styles

Overlay (Default)

Content blurred behind a centered payment card.

Inline

Paywall card appears inline after the preview content.

Blur

Full preview visible but blurred, with a floating payment button.

WordPress REST API Endpoints

Namespace: transx402/v1

`GET /wp-json/transx402/v1/content/:postId`

Returns full post content after payment verification or DB access grant.

Flow:

If payer cookie/header matches a DB grant → 200 with content
If no PAYMENT-SIGNATURE header → 402 with x402 payment requirements
If PAYMENT-SIGNATURE present → PHP facilitates, verifies, records to DB → 200

Headers:

PAYMENT-SIGNATURE — base64 payment payload (settlement retry)
X-TransX402-Payer — payer wallet (return visits)

Verification flow (first payment):

Look up transaction hash via TransX402 API (GET /payments/:txHash)
Assert verified === true and status === "confirmed"
Verify the payment recipient matches the site's wallet
Verify the payment amount matches the post's price
Verify resource matches https://{site}/wp-json/transx402/v1/content/{postId}
Record grant in WordPress DB and return full post content

Response (200):

{
  "content": "<p>Full article HTML...</p>",
  "paid": true,
  "txHash": "0x...",
  "payer": "0x..."
}

`GET /wp-json/transx402/v1/access/:postId`

Lightweight access check for frontend boot:

{
  "granted": true,
  "payer": "0x..."
}

`GET /wp-json/transx402/v1/config`

Full TransX402 facilitator config, proxied server-side. The paywall passes this URL to @transx402/client as facilitatorUrl so the browser loads chain and token params same-origin (no facilitator CORS, no API key in the browser):

{
  "sandbox": {
    "rpcUrl": "https://testnet-rpc.onchainfolio.com/rpc",
    "chainId": 1337,
    "network": "sandbox",
    "tokens": { "IDRX": "0x..." },
    "tokenDecimals": { "IDRX": 2 },
    "permit2Address": "0x000000000022D473030F116dDEE9F6B43aC78BA3",
    "x402": { "sponsorshipMode": "erc20ApprovalRelay", "caip2Network": "eip155:1337" },
    "nativeCurrency": { "name": "Ether", "symbol": "ETH", "decimals": 18 }
  },
  "production": { }
}

Settlement still uses server mode — PHP calls POST /facilitate; only GET /config is read from the browser.

`GET /wp-json/transx402/v1/config/public`

Plugin-level settings for integrations (no API key):

{
  "environment": "camp",
  "configUrl": "https://example.com/wp-json/transx402/v1/config",
  "contentEndpointPattern": "https://example.com/wp-json/transx402/v1/content/{postId}",
  "defaultPriceIdr": 5000,
  "currency": "IDR",
  "paywallStyle": "overlay"
}

Payment Verification and Access

After payment, access is stored in:

WordPress database — {prefix}transx402_payments (source of truth)
Payer cookie — transx402_payer (HttpOnly, 1 year) for instant return visits

On first payment, PHP verifies against TransX402 GET /payments/:txHash and asserts recipient, amount, and resource match. Subsequent visits skip facilitator calls when the DB grant exists.

Compatibility

Component	Support
WordPress	6.0+
PHP	8.0+
Editor	Gutenberg, Classic Editor
Caching plugins	Exclude paywalled URLs from full-page cache; preview HTML is cache-safe
SEO	Preview content is indexable; full content is behind REST

Testing with Sandbox

Enter a sandbox API key (ipk_sandbox_...) in plugin settings
Add your merchant wallet from the TransX402 dashboard
Make test payments using free test IDRX on CAMP Testnet
Switch to a production API key (ipk_live_...) when ready

For local development, set Facilitator URL to http://localhost:3402.

Security

API key stored in wp_options — never exposed to the browser
Full post content never in initial HTML for paywalled posts
PAYMENT-SIGNATURE processed server-side only
Payment verification against TransX402 before DB insert
No private keys or Permit2 signatures stored in WordPress

WordPress Plugin

On this page