In the previous lesson, the Flipnzee Auctions plugin introduced persistent storage for external provider transactions. Whenever a payment reached the completed stage, the Escrow provider generated a provider reference and stored important information such as provider status, timestamps, and notes within a dedicated database table.

Although this information was now permanently stored, it was only accessible by inspecting the database directly.

In this lesson, that changes.

The Transaction Details page is enhanced to display external provider information directly within the WordPress administration area, giving administrators immediate visibility into the provider responsible for processing a transaction.

Why Display Provider Information?

Once a website sale enters the payment stage, the auction transaction is no longer the only entity involved.

An external provider—such as Escrow.com in our simulated implementation—maintains its own transaction lifecycle.

Administrators frequently need answers to questions such as:

• Which provider is handling this transaction?
• What is the provider reference number?
• Has the provider transaction been created?
• What is the current provider status?
• Are there any provider notes?

Without displaying this information inside WordPress, administrators must inspect database records manually, making day-to-day transaction management unnecessarily difficult.

Bringing the Provider Layer into the User Interface

The Transaction Details screen now retrieves provider information using the External Provider Manager rather than performing direct database queries.

The page requests the provider record associated with the current transaction and displays the information in a dedicated section beneath Payment Management.

Conceptually, the flow now looks like this:

Transaction Details
        │
        ▼
External Provider Manager
        │
        ▼
Latest Provider Record
        │
        ▼
Display Provider Information

This preserves the plugin’s object-oriented architecture by separating presentation logic from data access.

Information Displayed

The new External Provider section includes:

• Provider name
• Provider reference
• Current provider status
• Started timestamp
• Completed timestamp
• Provider notes

A typical provider record appears as follows:

This allows administrators to monitor provider activity without leaving the WordPress dashboard.

Graceful Handling of Missing Provider Records

Not every transaction will necessarily have an associated provider.

For example:

• Historical transactions created before provider persistence was introduced.
• Transactions that have not yet reached the payment completion stage.
• Future transactions using alternative payment methods.

Instead of generating errors or displaying incomplete information, the page now detects the absence of a provider record and displays a clear message indicating that no provider information is available.

This improves both usability and robustness.

Maintaining Separation of Responsibilities

One of the primary objectives of the refactoring effort has been reducing coupling between components.

The Transaction Details page now communicates exclusively with the Flipnzee_External_Provider_Manager.

Responsibilities are clearly divided:

• Escrow Provider creates provider records.
• External Provider Manager retrieves provider information.
• Transaction Details presents the information.
• Transaction Lifecycle Manager coordinates the overall workflow.

Each component remains responsible for a single concern, making the codebase easier to understand, maintain, and extend.

Improving Administrative Visibility

The addition of provider information significantly improves the administrative workflow.

An administrator reviewing a completed transaction can now immediately determine:

• Which provider created the transaction.
• The external provider reference.
• The provider’s current status.
• When the provider transaction started.
• Whether additional provider information has been recorded.

This reduces reliance on database inspection while providing a clearer operational overview of website sales.

Preparing for Future Integrations

Although the current provider implementation continues to simulate Escrow.com, the user interface has now been designed with future integrations in mind.

When a live Escrow.com API is introduced, the same section can display:

• Live provider status.
• Escrow milestones.
• Buyer and seller verification.
• Payment confirmation.
• Domain transfer progress.
• Provider synchronization timestamps.

Because the display layer is already connected to the provider abstraction rather than the provider implementation, future integrations can be introduced with minimal changes to the administration interface.

Benefits of This Lesson

The improvements introduced in this lesson provide several practical advantages:

• External provider information is available directly within WordPress.
• Administrators no longer need to inspect the database for provider details.
• The transaction management interface becomes more informative.
• Presentation logic remains independent from database operations.
• The architecture remains fully extensible for future payment and escrow providers.

Most importantly, the Transaction Details page now serves as a unified view of the complete website sale process, combining auction information, payment management, ownership transfer, and external provider details in a single location.

Looking Ahead

Displaying provider information is only the first step toward comprehensive provider management.

Future lessons will continue building upon this foundation by introducing:

• Improved transaction navigation.
• Enhanced provider user interface components.
• Provider status synchronization.
• External API communication.
• Webhook processing.
• Live Escrow.com integration.

With external provider information now visible alongside payment and ownership transfer details, the Flipnzee Auctions plugin takes another significant step toward becoming a complete transaction management platform for buying and selling websites.

https://github.com/SplendidDigital/flipnzee-auctions/releases/tag/lesson-123-stable

One of the goals of the Flipnzee Auctions project is to build a transaction system that can eventually integrate with multiple payment and escrow providers without requiring major architectural changes. While previous lessons introduced a simulated Escrow.com provider and an event-driven transaction lifecycle, provider information existed only temporarily during execution.

In this lesson, that changes.

Instead of simply generating a simulated escrow reference and returning it to the caller, the plugin now persists provider information in a dedicated database table. This transforms the provider layer from a simple simulation into a permanent part of the transaction history and prepares the architecture for future integration with real external services.

Why Persist Provider Information?

During a real website sale, the auction transaction is only one part of the process. Once payment is initiated through an external provider such as Escrow.com, additional information must be tracked independently of the auction itself.

Examples include:

• External provider name
• Provider transaction reference
• Provider status
• Processing timestamps
• Notes and audit information

Without persistent storage, all of this information would be lost once the request finishes.

Existing Provider Infrastructure

Earlier lessons already introduced a dedicated database table for external providers.

This lesson focuses on using that infrastructure rather than redesigning it.

Each provider record is linked to a Flipnzee transaction while maintaining its own independent lifecycle.

This separation keeps the auction system independent from the implementation details of any individual payment provider.

Enhancing the Escrow Provider

The simulated Escrow provider has been significantly expanded.

Instead of only generating an escrow reference, it now performs a complete provider workflow:

1. Starts the provider transaction.
2. Generates a unique simulated escrow reference.
3. Creates a persistent provider record.
4. Records timestamps and status.
5. Returns the generated reference to the transaction lifecycle.

Conceptually, the workflow now looks like this:

Payment Completed
        │
        ▼
Transaction Lifecycle Manager
        │
        ▼
Escrow Provider
        │
        ├── Generate Escrow Reference
        ├── Create Provider Record
        ├── Store Status
        ├── Store Notes
        └── Return Reference

Persistent Provider Records

Every completed payment now creates a record similar to:

Unlike previous lessons, this information now survives beyond the lifetime of the PHP request and becomes part of the permanent transaction history.

The Role of the External Provider Manager

The Flipnzee_External_Provider_Manager acts as the persistence layer between business logic and the database.

Its responsibilities include:

• Creating provider records
• Retrieving provider information
• Updating provider status
• Looking up providers by transaction
• Removing provider records if necessary

By centralizing these operations, the Escrow provider no longer communicates directly with the database.

This follows the same architectural principle used throughout the plugin, where managers coordinate data access while providers focus on provider-specific behaviour.

Improved Logging

The provider workflow now produces much more meaningful debug output.

Typical logs now include messages such as:

FLIPNZEE ESCROW: Starting escrow transaction for transaction #34

FLIPNZEE EXTERNAL PROVIDER: create_provider() called.

FLIPNZEE EXTERNAL PROVIDER INSERT SUCCEEDED

FLIPNZEE ESCROW: Provider record #14 created.

FLIPNZEE ESCROW: Escrow reference ESCROW-20260724010512-34 created.

These logs make it considerably easier to diagnose provider-related issues during development.

Benefits of the New Architecture

Persisting provider information provides several advantages:

• Permanent audit trail of provider activity.
• Separation between auction transactions and external services.
• Easier debugging through structured provider records.
• Foundation for future status synchronization.
• Support for multiple providers without changing the auction model.
• Cleaner object-oriented architecture.

Most importantly, the auction plugin no longer treats provider interactions as temporary events—they are now first-class entities within the transaction system.

Looking Ahead

Although the current implementation still simulates Escrow.com, the surrounding architecture is now remarkably close to supporting a real integration.

Future lessons will build upon this foundation by:

• Displaying provider information within the Transaction Details screen.
• Updating provider status as transactions progress.
• Synchronizing with external provider APIs.
• Supporting additional payment providers using the same abstraction layer.
• Introducing webhook-based status updates.

With persistent provider records now in place, the Flipnzee Auctions plugin has taken another important step toward becoming a production-ready digital asset marketplace capable of handling complex website sale transactions in a clean, extensible, and maintainable manner.

Series: Building Flipnzee Auctions – From Prototype to Production
Lesson: 120 (Implementation)

Overview

In the previous lesson, we introduced the concept of a transaction state machine and explained why representing a transaction’s current state is more scalable than relying solely on events.

This implementation focuses on laying the architectural foundation for persistent transaction states.

What We Built

This lesson introduces a new class:

Flipnzee_Transaction_State_Manager

Its responsibility is to define the lifecycle of every transaction within the plugin.

Instead of scattering state strings across multiple files, all transaction states are centralized in one location.

State Constants

The following constants were added:

PAYMENT_PENDING

PAYMENT_SUBMITTED

PAYMENT_COMPLETED

FILES_TRANSFER

DATABASE_TRANSFER

DOMAIN_TRANSFER

BUYER_VERIFICATION

COMPLETED

These constants eliminate duplicated string literals and provide a single source of truth throughout the plugin.

Human-Readable Labels

A helper method was added to convert internal state identifiers into administrator-friendly labels.

Examples include:

payment_pending

↓

Payment Pending

and

database_transfer

↓

Database Transfer

This keeps presentation logic separate from business logic.

Ordered Transaction Lifecycle

The state manager now exposes the complete transaction lifecycle in a predictable order.

This makes future features—such as determining the next valid state—much easier to implement.

Rather than relying on complex conditional logic, the plugin can iterate over a centralized lifecycle definition.

Active and Terminal States

Two helper methods were introduced:

• is_active()
• is_terminal()

These methods allow other components to determine whether a transaction is still progressing or has reached its final destination.

This abstraction will become increasingly valuable as future terminal states (such as cancelled or refunded) are introduced.

Lifecycle Integration

The Transaction Lifecycle Manager was updated to work with the new state architecture.

When payment is completed, the lifecycle manager now:

• recognizes the current transaction state
• logs the state transition
• continues creating the ownership transfer workflow

Although states are not yet fully persisted, the lifecycle manager now thinks in terms of transaction states rather than isolated events.

Database Preparation

The lesson also prepares the database for persistent transaction states through a new migration targeting version 1.4.0.

The migration introduces a dedicated state column within the transactions table.

Once applied, every transaction will permanently record its current position in the workflow.

Refactoring Existing Migrations

While extending the migration system, several improvements were made:

• corrected logging messages
• cleaned migration sequencing
• prepared a dedicated migration for transaction states
• continued following versioned database upgrades

These improvements make future schema changes easier to maintain.

Architectural Impact

Before this lesson, the transaction workflow looked like this:

Payment

↓

Transfer

↓

Completion

After Lesson 120, the architecture evolves into:

Payment

↓

Lifecycle Manager

↓

Transaction State

↓

Transfer Manager

↓

Completion

The transaction state now becomes the central reference point for every future workflow.

Why This Matters

This lesson may not introduce visible frontend changes, but it represents one of the most important architectural improvements in the project.

Upcoming features—including:

• Escrow.com integration
• multiple payment providers
• automated notifications
• buyer dashboards
• transaction timelines
• dispute handling

will all depend on a reliable transaction state machine.

By completing this refactoring now, future lessons can focus on business functionality instead of continually restructuring the underlying architecture.

Looking Ahead

With the state machine in place, the plugin is now ready to persist transaction states and allow external providers to react to state transitions.

The next lessons will leverage this foundation to integrate Escrow workflows, ensuring that every payment and ownership transfer follows a consistent, extensible lifecycle.

https://github.com/SplendidDigital/flipnzee-auctions/releases/tag/lesson-120-stable

In the previous lesson, the plugin gained a complete ownership transfer workflow. Although that feature worked well, the implementation revealed an architectural issue: the payment update screen was becoming responsible for triggering multiple business processes.

This lesson introduces a cleaner, more extensible architecture by adopting WordPress action hooks as lifecycle events.

Why This Change Was Needed

Originally, when an administrator marked a payment as Completed, the payment update method was expected to:

• Update the payment status
• Create an ownership transfer record
• Record activity logs
• Trigger notifications
• Potentially communicate with Escrow.com
• Perform any future post-payment tasks

As the plugin grows, this approach would lead to a large method that becomes increasingly difficult to maintain.

Instead, the payment module should simply announce that a payment has been completed and allow other parts of the system to respond independently.

Existing Flow

Previously, the workflow looked like this:

Admin Updates Payment
        │
        ▼
update_payment_status()
        │
        ├── Update database
        ├── Create transfer
        ├── Send notifications
        ├── Escrow processing
        └── More future code...

Every new feature would require modifying the payment update method.

New Event-Driven Flow

The payment screen now performs only its own responsibility.

Admin Updates Payment
        │
        ▼
update_payment_status()
        │
        ▼
do_action(
    'flipnzee_payment_completed'
)
        │
        ▼
Transaction Lifecycle Manager
        │
        ├── Create ownership transfer
        ├── Future email notifications
        ├── Future Escrow integration
        ├── Future analytics
        └── Future automation

This separates responsibilities while allowing the plugin to grow without constantly modifying the payment module.

Creating the Transaction Lifecycle Manager

A new class was introduced:

includes/
    class-transaction-lifecycle-manager.php

This class becomes responsible for listening to important transaction lifecycle events.

Its initial responsibilities include:

• Registering lifecycle hooks
• Responding to completed payments
• Coordinating transfer creation
• Serving as the central point for future transaction automation

Registering the Lifecycle Event

During plugin initialization, the lifecycle manager registers a listener for completed payments.

flipnzee_payment_completed

Whenever this event is fired, the lifecycle manager automatically begins the ownership transfer workflow.

Publishing the Event

Instead of directly creating transfer records, the payment update process now publishes an event:

do_action(
    'flipnzee_payment_completed',
    $transaction_id
);

The payment module no longer needs to know what happens next.

Its responsibility ends after announcing that the payment has been completed.

Responding to the Event

The lifecycle manager receives the transaction ID and performs the required business logic.

Currently, it automatically:

• Creates an ownership transfer record (if one does not already exist)

Future versions will expand this handler to include:

• Buyer notifications
• Seller notifications
• Escrow.com processing
• CRM integrations
• Analytics events
• Audit logging
• Additional automation

Benefits of Event-Driven Design

This approach offers several important advantages.

Single Responsibility

The payment module focuses exclusively on payment management.

Loose Coupling

The payment module no longer depends directly on the transfer manager.

Extensibility

New features can subscribe to lifecycle events without modifying existing code.

Easier Maintenance

Each component performs one clearly defined responsibility.

Better Testing

Lifecycle handlers can be tested independently of the payment interface.

Real-World Example

After this lesson, marking a payment as Completed automatically performs the following sequence:

Administrator
        │
        ▼
Payment Updated
        │
        ▼
Lifecycle Event Published
        │
        ▼
Transaction Lifecycle Manager
        │
        ▼
Ownership Transfer Created
        │
        ▼
Transfer appears in
Transfer Management

No additional code is required inside the payment update screen.

Result

After implementing this lesson:

• Payment completion automatically creates ownership transfer records.
• The payment module no longer contains transfer-specific logic.
• A reusable lifecycle architecture is now available.
• Future integrations can subscribe to lifecycle events without modifying existing functionality.

Looking Ahead

With lifecycle events in place, the next step is to formalize the overall transaction workflow.

Rather than treating transactions as isolated status updates, the plugin will begin managing them as a sequence of well-defined states—from auction completion through payment, ownership transfer, and final closure.

This state-based approach will provide a stronger foundation for Escrow.com integration and future automation while keeping the plugin organized as it continues to evolve.

https://github.com/SplendidDigital/flipnzee-auctions/releases/tag/lesson-119-stable