Wicket Guest Checkout

A secure WooCommerce plugin that enables guest payment functionality through time-limited, encrypted payment links.

Overview

Wicket Guest Checkout allows WordPress administrators to generate secure payment links for WooCommerce orders. These links can be shared with guests who can then complete payment on behalf of registered users without needing to log in or create an account.

Features

Core Functionality

• Secure Token System: AES-256-CBC encrypted tokens with HMAC validation
• Guest Payment Flow: Streamlined checkout process for guest payers
• Session Management: Temporary authentication with automatic cleanup
• Cart Preservation: Original order items and custom pricing maintained
• Access Restrictions: Guest sessions limited to checkout pages only

Admin Features

• Order Meta Box: Manage guest payment links directly from order admin
• Email Integration: Automatically send payment links via email
• Manual Link Generation: Create and copy links without sending email
• Link Invalidation: Revoke payment links at any time
• Order Notes: Automatic tracking of guest payment activities

Security

• Token encryption using WordPress authentication keys
• HMAC-SHA256 hash verification
• IP-based rate limiting (5 attempts per 15 minutes)
• Time-limited tokens (7-day default expiry)
• Automatic session cleanup after payment
• Duplicate order prevention
• Brute force protection

Receipt System

• Post-payment receipt access
• 30-day receipt link validity
• Printable token-gated receipt page (Print Receipt button)
• Optional receipt email capture on the thank-you page
• Print button and email capture are per-site toggles under Wicket Settings > Integrations > Guest Checkout (both enabled by default)

Documentation

For complete documentation, see docs/index.md.

Requirements

• WordPress: 6.0+
• WooCommerce: 10.0+
• PHP: 8.3+
• SSL Certificate: Recommended for production

Installation

From GitHub

cd wp-content/plugins
git clone https://github.com/wicket/wicket-guest-checkout.git
cd wicket-guest-checkout

Then activate the plugin through WordPress admin.

Manual Upload

1. Download the latest release ZIP
2. Upload through WordPress Admin → Plugins → Add New → Upload
3. Activate the plugin

Configuration

Basic Setup

The plugin works out of the box with WooCommerce. No additional configuration required.

Email & PDF Integration (Optional)

For automatic guest payment links in emails and PDFs, see:

• 📧 Email Integration Guide - Configure automatic email links
• 📄 PDF Integration Guide - Configure automatic PDF links

Quick Enable:

// Enable email integration
add_filter('wicket/wooguestpay/email_integration_enabled', '__return_true');

// Enable PDF integration
add_filter('wicket/wooguestpay/pdf_integration_enabled', '__return_true');

Advanced Configuration

For comprehensive configuration options, filters, and examples, see the Configuration Quick Reference.

Key Configuration Examples:

// Custom encryption keys (enhanced security)
define('WICKET_GUEST_PAYMENT_ENCRYPTION_KEY', 'your-unique-32-char-key-here');

// Custom token expiry (7 days default)
add_filter('wicket/wooguestpay/token_expiry_days', function($days) {
    return 14; // 14 days
});

// Conditional email integration (orders over $100 only)
add_filter('wicket/wooguestpay/email_integration_enabled', function($enabled, $order) {
    return $order && $order->get_total() > 100;
}, 10, 2);

Encryption key and legacy token migration

Since the WWID-2665 bootstrap fix, production sites no longer get a derived fallback key. The plugin derives WICKET_GUEST_PAYMENT_ENCRYPTION_KEY from SECURE_AUTH_KEY . AUTH_KEY in wp-config.php, or uses a direct WICKET_GUEST_PAYMENT_ENCRYPTION_KEY definition. Local and development sites without salts keep a site-derived key. Production and staging sites with no usable key fail closed: new payment links cannot be issued, and existing links validate only if keys are supplied through the filter described below. Salts left at the WordPress sample value (put your unique phrase here) or the Wicket baseline default (generateme) count as missing.

Sites that ran an earlier release signed payment links with whichever key the old code derived at the time: the fallback sha256( site_url + admin_email + 'wicket-wgc-enc' ) on sites without salts, or the concatenated placeholder literals on sites that kept the sample or baseline salt values. Those links stop validating after the upgrade. To keep honoring them during a transition, supply the legacy key through the wicket_guest_payment_encryption_keys filter in a mu-plugin or the site integration plugin:

add_filter('wicket_guest_payment_encryption_keys', function ($keys) {
    $keys = (array) $keys;
    $keys[] = hash('sha256', get_site_url() . get_option('admin_email') . 'wicket-wgc-enc');

    return $keys;
});

Filter keys enable token validation and decryption for existing links. Issuing new payment links still requires the constant (or usable salts) in wp-config.php; the filter cannot replace it for issuance. The filter replaces the whole key list, so a callback should append the legacy key to the incoming $keys. Remove the legacy filter entry once old links have expired or been reissued.

Default Configuration

• Order Statuses Allowed: pending, failed, on-hold
• Token Expiry: 7 days (configurable)
• Rate Limiting: 5 attempts per 15 minutes per IP
• Email Integration: Disabled by default
• PDF Integration: Enabled by default

Usage

For Administrators

1. Navigate to a WooCommerce order in admin
2. Locate the "Guest Payment" meta box in the sidebar
3. Choose one of two options:

Option 1: Generate and Send Email

• Enter guest email address
• Click "Generate & Send Email"
• Guest receives payment link via email

Option 2: Manual Link Generation

• Click "Generate Link"
• Copy the generated URL
• Share via any channel (email, SMS, etc.)

For Guests

1. Click the payment link received
2. Automatically logged in with restricted access
3. Review cart (pre-filled with order items)
4. Complete payment through checkout
5. View receipt and automatically logged out

Architecture

Class Structure

wicket-guest-checkout.php                        # Main plugin file
├── src/
│   ├── WicketGuestPayment.php                   # Main coordinator (Singleton)
│   ├── WicketGuestPaymentCore.php               # Token & cart management
│   ├── WicketGuestPaymentAdmin.php              # Admin interface
│   ├── WicketGuestPaymentAdminPay.php           # Admin Pay for Customer flow
│   ├── WicketGuestPaymentAuth.php               # Authentication & restrictions
│   ├── WicketGuestPaymentConfig.php             # Configuration management
│   ├── WicketGuestPaymentEmail.php              # Email notifications
│   ├── WicketGuestPaymentInvoice.php            # Invoice integration
│   ├── WicketGuestPaymentReceipt.php            # Receipt management
│   ├── AbstractWicketGuestPaymentComponent.php  # Abstract base class
│   ├── TraitWicketGuestPaymentLogger.php        # Logging trait
│   └── legacy-class-aliases.php                # Backward-compat class aliases

Data Flow

1. Admin generates token → Encrypted & stored in order meta
2. Guest clicks link → Token validated → User authenticated
3. Cart populated → Checkout restricted session created
4. Payment completed → Token invalidated → Session cleaned up
5. Receipt generated → 30-day access link created

Database Storage

Order Meta Keys:

• _wgp_guest_payment_token_encrypted: Encrypted payment token
• _wgp_guest_payment_token_hash: HMAC hash for validation
• _wgp_guest_payment_token_created: Token creation timestamp
• _wgp_guest_payment_user_id: Associated user ID
• _wgp_guest_payment_email: Guest email address
• _wgp_guest_payment_generation_method: email or manual
• _wgp_receipt_access_token: Receipt access token
• _wgp_receipt_token_created: Receipt token creation timestamp

User Meta (Temporary):

• _wgp_guest_session_token_validation: Session validation hash
• _wgp_original_order_id: Order ID for duplicate prevention
• _wgp_cart_data: Cart data for restoration

Transients (Temporary):

• wgp_map_{key}: Secure cart key to user ID mapping
• wgp_cart_{key}: Serialized cart data
• guest_pay_limit_{ip}: Rate limiting counter
• wgp_admin_pay_{token}: Admin Pay session data (15-min TTL)
• wgp_admin_pay_session_{customer_id}: Admin Pay cookie/session binding

Hooks & Filters

Actions

// Before guest payment link generation
do_action('wicket_guest_payment_before_generate', $order_id, $guest_email);

// After successful guest payment
do_action('wicket_guest_payment_completed', $order_id, $user_id);

// Before token invalidation
do_action('wicket_guest_payment_before_invalidate', $order_id);

Filters

// Modify allowed order statuses
apply_filters('wicket_guest_payment_allowed_order_statuses', $statuses);

// Modify allowed subscription statuses
apply_filters('wicket_guest_payment_allowed_subscription_statuses', $statuses);

// Customize email subject (6 args)
apply_filters('wicket_guest_payment_email_subject', $subject, $order, $token, $placeholders, $recipient_email, $user_data);

// Customize email content (6 args)
apply_filters('wicket_guest_payment_email_content', $html, $order, $token, $placeholders, $recipient_email, $user_data);

// Customize email headers (6 args)
apply_filters('wicket_guest_payment_email_headers', $headers, $order, $token, $placeholders, $recipient_email, $user_data);

// Replace the key list used for token validation/decryption (array or string;
// $keys holds the wp-config key, append to it rather than dropping it)
apply_filters('wicket_guest_payment_encryption_keys', $keys);

Development

Setup Development Environment

# Clone repository
git clone https://github.com/wicket/wicket-guest-checkout.git
cd wicket-guest-checkout

# Install dependencies
composer install

# Install in WordPress
ln -s $(pwd) /path/to/wordpress/wp-content/plugins/wicket-guest-checkout

⚠️ IMPORTANT: Before Tagging a New Version

Always run composer production before tagging a new version. This command:

• Removes development dependencies
• Optimizes autoloader for production
• Generates a clean build without dev packages

composer production

Without this step, the plugin will include unnecessary dev dependencies in the release.

Coding Standards

• PHP: PSR-12 with WordPress modifications
• PHP Version: 8.3+
• Strict types enabled (declare(strict_types=1))
• WooCommerce CRUD methods for HPOS compatibility
• All user input sanitized and validated
• All output escaped

Logging

The plugin uses WooCommerce logger:

// View logs
WooCommerce → Status → Logs → Select "wicket-guest-payment"

Testing

The plugin uses PEST and PHPUnit for testing.

Running Tests

# Run all tests
composer test

# Run unit tests only
composer test:unit

# Run tests with coverage report
composer test:coverage

# Run browser tests
composer test:browser

# Run specific test file
./vendor/bin/pest tests/unit/WicketGuestPaymentCoreUnitTest.php

Browser Testing (Pest Browser + Playwright)

Prerequisites: Browser tests require a local WordPress instance running with the Wicket Docker setup. Ensure you have a site (e.g., PACE or any other) running locally before executing browser tests.

# Install browser testing dependencies
composer require pestphp/pest-plugin-browser --dev

# Option 1: Install Playwright locally
npm install playwright@latest
npx playwright install

# Option 2: Install Playwright globally (if desired)
npm install -g playwright@latest && npx playwright install

On macOS, npx playwright install is usually enough. If WebKit/Safari fails, run:

xcode-select --install
npx playwright install

Writing New Tests

1. Create test file in tests/unit/ with pattern *Test.php
2. Extend AbstractTestCase for WordPress function mocking

<?php

declare(strict_types=1);

namespace Wicket\GuestPayment\Tests;

use PHPUnit\Framework\Attributes\CoversClass;
use WicketGuestPaymentCore;

#[CoversClass(WicketGuestPaymentCore::class)]
class MyNewTest extends AbstractTestCase
{
    private ?WicketGuestPaymentCore $core = null;

    protected function setUp(): void
    {
        parent::setUp();
        $this->core = new WicketGuestPaymentCore();
    }

    protected function tearDown(): void
    {
        $this->core = null;
        parent::tearDown();
    }

    public function test_something(): void
    {
        $this->assertTrue(true);
    }
}

3. Use Brain Monkey to mock WordPress functions:

\Brain\Monkey\Functions\stubs([
    'get_option' => 'value',
    'update_option' => true,
    'wc_get_logger' => $mock_logger,
]);

4. Run tests - PHPUnit auto-discovers test files matching *Test.php

Test Structure

tests/
├── bootstrap.php              # PHPUnit bootstrap with WordPress mocks
└── unit/
    ├── AbstractTestCase.php   # Base test class with Brain Monkey setup
    ├── WicketGuestPaymentCoreUnitTest.php
    ├── WicketGuestPaymentAuthTest.php
    └── ...

Manual Testing Checklist

- [ ] Generate payment link from order admin
- [ ] Send payment link via email
- [ ] Complete guest payment flow
- [ ] Verify order status update
- [ ] Confirm token invalidation
- [ ] Test rate limiting
- [ ] Verify session cleanup
- [ ] Check receipt access

Available Composer Scripts

composer production       # Build for production (remove dev deps, optimize autoload)
composer test            # Run all tests
composer test:unit       # Run unit tests only
composer test:coverage   # Run tests with HTML coverage report
composer test:browser    # Run browser tests
composer lint            # Check code style
composer format          # Fix code style
composer check           # Run lint + test

Security Considerations

1. Always use HTTPS in production
2. Define custom encryption keys in wp-config.php
3. Regularly update WordPress and WooCommerce
4. Monitor failed token validation attempts
5. Review logs for suspicious activity

Troubleshooting

Payment link doesn't work

• Check token hasn't expired (7 days default)
• Verify WooCommerce is active
• Ensure order status is pending, failed, or on-hold
• Check WooCommerce logs for errors

Cart is empty after clicking link

• Verify WooCommerce session is working
• Check product availability and stock status
• Review cart restoration logs

Guest can access admin pages

• Check guest session cookie is set
• Verify prevent_guest_admin_access hook is running
• Review server cookie configuration

Support

• Issues: GitHub Issues
• Documentation: Wiki
• Discussions: GitHub Discussions

License

GPL v2 or later

Credits

Developed by Wicket

Changelog

See CHANGELOG.md for version history.