Lesson 123: Displaying External Provider Information in the Transaction Details Screen


Overview

In the previous lesson, we introduced persistent storage for external provider transactions. Every completed payment now creates a provider record containing the provider name, escrow reference, timestamps, status, and notes.

However, this information is only available by directly inspecting the database.

In this lesson, we’ll integrate the External Provider Manager with the WordPress administration interface so administrators can view provider information directly from the Transaction Details page.

This represents an important shift from building backend infrastructure to exposing meaningful operational information through the plugin’s user interface.


Why this lesson?

At the moment, an administrator managing a website sale has no immediate visibility into the external provider handling the transaction.

To answer questions such as:

  • Which provider is managing this payment?
  • What is the escrow reference?
  • Has the provider transaction been created?
  • What status is the provider reporting?
  • Were any notes recorded?

the administrator must manually inspect the database.

The goal of this lesson is to eliminate that requirement.


Objectives

By the end of this lesson we will:

  • Retrieve provider information using Flipnzee_External_Provider_Manager
  • Associate provider records with auction transactions
  • Display provider details inside the Transaction Details page
  • Gracefully handle transactions without a provider record
  • Lay the foundation for future provider actions and status synchronization

Planned Interface

The Transaction Details page will gain a new section similar to:

──────────────────────────────────────────
External Provider
──────────────────────────────────────────

Provider
Escrow.com

Reference
ESCROW-20260724010512-34

Status
Created

Started
24 Jul 2026 06:35

Completed
—

Notes
Simulated escrow transaction created.

If no provider record exists, the interface will instead display:

External Provider

No provider information is available for this transaction.

This ensures the interface remains informative without producing errors for historical transactions.


Architectural Improvements

Rather than querying the database directly from the admin screen, the page will use:

Flipnzee_External_Provider_Manager::get_provider_by_transaction()

This maintains a clear separation of responsibilities:

  • External Provider Manager retrieves provider data.
  • Admin Transaction Details focuses solely on presentation.
  • Escrow Provider remains responsible for provider creation.
  • Transaction Lifecycle Manager continues orchestrating the workflow.

This follows the object-oriented architecture established throughout the project.


Benefits

After completing this lesson:

  • Administrators can inspect provider information without leaving WordPress.
  • Transaction debugging becomes significantly easier.
  • Escrow references become immediately accessible.
  • Provider status is visible during transaction processing.
  • The UI becomes ready for future actions such as “Open Escrow Transaction”, “Refresh Provider Status”, or “Retry Provider Synchronization”.

What We’ll Build

The implementation will involve three primary steps:

  1. Retrieve provider information for the current transaction.
  2. Add a dedicated External Provider panel to the Transaction Details page.
  3. Display provider fields using WordPress admin styling and proper escaping.

No database changes are required, as the persistence layer introduced in Lesson 122 already provides everything needed.


Looking Ahead

Displaying provider information is only the first step toward a fully integrated provider management system.

Future lessons will build on this interface by allowing administrators to:

  • Synchronize provider status with external services.
  • View provider history.
  • Launch provider-specific actions.
  • Integrate with the real Escrow.com API.
  • Support multiple external payment and escrow providers through the same abstraction layer.

With provider information now visible inside the administration interface, the Flipnzee Auctions plugin moves one step closer to providing a complete transaction management experience for buying and selling websites.

Lesson 122: Persisting External Provider Transactions for Future Escrow Integration

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:

FieldExample
Transaction ID34
ProviderEscrow.com
Provider ReferenceESCROW-20260724010512-34
Statuscreated
Started At2026-07-24 06:35
Completed AtNULL
NotesSimulated escrow transaction created.

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.

Lesson 122: Persisting Escrow Provider Information for Future API Integration

In the previous lesson, Flipnzee Auctions introduced its first Escrow Provider Engine. Payment completion automatically created a simulated escrow transaction and generated a unique escrow reference.

While that proved the event-driven architecture worked, the generated reference only existed during execution. Once the request finished, there was no permanent record of the escrow transaction.

In this lesson, the plugin takes the next step by designing a persistent storage strategy for external providers.


Why Store Escrow Information?

Real-world escrow services return much more than a reference number.

An external provider may return:

  • Provider transaction ID
  • Escrow reference
  • Current escrow status
  • Creation timestamp
  • Last update timestamp
  • API response details
  • Provider-specific metadata

Without storing this information, the plugin would have no way to:

  • check escrow progress
  • synchronize status
  • reopen existing escrow transactions
  • display escrow details inside the admin panel

Persistence is therefore essential.


Objectives

By the end of this lesson the plugin architecture will support:

  • persistent escrow references
  • provider-specific transaction identifiers
  • provider status tracking
  • future API synchronization
  • support for multiple external providers

Thinking Beyond Escrow.com

Although Flipnzee Auctions is initially designed around Escrow.com, the architecture should never assume only one provider exists.

Instead of storing fields like:

escrow_reference
escrow_status

the plugin adopts more generic terminology.

For example:

provider
provider_reference
provider_transaction_id
provider_status

This makes the database independent of any specific vendor.

Future providers could include:

  • Escrow.com
  • custom enterprise escrow
  • regional payment escrow services
  • internal manual escrow workflows

Extending the Transaction Model

The transaction lifecycle now grows beyond internal auction information.

Auction
        │
        ▼
Transaction
        │
        ▼
External Provider
        │
        ▼
Escrow Workflow

Instead of treating external services as an afterthought, they become a first-class component of the transaction architecture.


Recommended Provider Fields

A professional transaction record may eventually include:

FieldPurpose
providerName of the provider
provider_referenceHuman-readable reference
provider_transaction_idExternal system ID
provider_statusCurrent provider status
provider_created_atProvider creation time
provider_updated_atLast synchronization
provider_responseRaw API response (optional)

Not every provider will use every field, but the structure remains flexible.


Keeping Responsibilities Separate

The Transaction Manager remains responsible for:

  • internal auction transactions
  • payment information
  • ownership workflow

The Escrow Provider becomes responsible for:

  • creating provider records
  • communicating with external APIs
  • interpreting provider responses
  • tracking provider-specific statuses

This clear separation keeps the plugin easier to maintain.


Future Synchronization

Creating an escrow transaction is only the beginning.

Eventually the plugin should support periodic synchronization.

Escrow Created
        │
        ▼
Store Provider Details
        │
        ▼
Scheduled Status Check
        │
        ▼
Retrieve Latest Status
        │
        ▼
Update Local Database

This enables administrators to see real-time escrow progress without manually checking the provider website.


Benefits of Persistent Storage

Persisting provider information allows administrators to:

  • search escrow transactions
  • troubleshoot failed payments
  • view escrow references
  • synchronize provider status
  • audit completed transactions
  • generate financial reports

These capabilities become increasingly valuable as transaction volume grows.


Preparing for API Integration

Most modern payment and escrow APIs follow a similar lifecycle:

  1. Create transaction
  2. Receive external reference
  3. Store the response
  4. Poll or receive status updates
  5. Finalize the transaction

Because Flipnzee Auctions now separates provider logic from transaction logic, integrating a live API becomes a matter of implementing provider-specific communication rather than rewriting the auction system.


Architectural Benefits

This lesson strengthens several important software engineering principles:

  • Separation of concerns
  • Single responsibility
  • Provider abstraction
  • Extensibility
  • Maintainability

By treating external providers as independent services, the plugin becomes easier to evolve as new payment technologies emerge.


What We Accomplished

In this lesson we:

  • designed a persistent model for external provider information
  • separated provider data from transaction data
  • prepared the database for long-term escrow tracking
  • laid the groundwork for status synchronization
  • ensured future provider integrations remain modular
  • continued evolving Flipnzee Auctions into a production-ready architecture

Looking Ahead

With provider persistence planned, the next stage is to build the synchronization layer that keeps local transaction records aligned with external escrow providers.

This will allow Flipnzee Auctions to automatically monitor escrow progress, refresh statuses, and provide administrators with an accurate, real-time view of every transaction without relying on manual updates.

Lesson 121: Building an Escrow Provider Engine for Flipnzee Auctions

As the Flipnzee Auctions plugin matures, the payment workflow is becoming more structured and event-driven. In previous lessons, payment completion triggered the transaction lifecycle, and ownership transfer records were automatically created.

In this lesson, the next major component is introduced: an Escrow Provider Engine.

Although this lesson uses a simulated provider instead of connecting to a real escrow service, it establishes the architecture required for integrating providers such as Escrow.com in the future.


Why an Escrow Provider?

High-value website and domain transactions require trust between buyers and sellers.

Rather than immediately transferring funds or ownership, an escrow service acts as a trusted intermediary by:

  • Holding buyer funds securely
  • Waiting until transfer conditions are satisfied
  • Releasing funds to the seller after successful delivery

Instead of hardcoding a specific provider throughout the plugin, Flipnzee Auctions now introduces an abstraction layer dedicated to escrow providers.


Objectives

By the end of this lesson the plugin will:

  • create an escrow transaction automatically after payment completion
  • generate a unique escrow reference
  • isolate escrow logic into its own provider class
  • keep transaction lifecycle independent from any specific provider
  • prepare the plugin for future Escrow.com API integration

Creating the Escrow Provider

A new provider class was introduced:

includes/
└── class-escrow-provider.php

The provider is intentionally lightweight.

Its responsibility is simply to manage escrow-related operations without affecting the transaction manager or ownership transfer logic.

Initialization is handled through:

Flipnzee_Escrow_Provider::init();

This keeps provider-specific functionality separated from the rest of the plugin.


Simulating Escrow Creation

Rather than connecting to a live API, the provider currently generates an internal escrow reference.

Example:

ESCROW-20260723144534-33

This combines:

  • current UTC timestamp
  • transaction ID

The resulting reference behaves similarly to what an external escrow provider would return after successfully opening an escrow transaction.


Connecting Escrow to the Transaction Lifecycle

Previously, payment completion created an ownership transfer record.

The workflow has now been extended.

Payment Completed
        │
        ▼
Transaction Lifecycle
        │
        ├────────► Create Ownership Transfer
        │
        ▼
Create Escrow Transaction
        │
        ▼
Generate Escrow Reference

This means escrow creation becomes an automatic consequence of payment completion.

No administrator intervention is required.


Event-Driven Architecture

One of the biggest improvements in this lesson is reinforcing an event-driven design.

Instead of directly calling escrow code from the payment page, the plugin continues using WordPress actions.

Payment Updated
        │
        ▼
flipnzee_payment_completed
        │
        ▼
Transaction Lifecycle Manager
        │
        ├────────► Transfer Manager
        │
        └────────► Escrow Provider

This approach offers several advantages:

  • lower coupling
  • easier testing
  • simpler future extensions
  • better maintainability

Why This Design Matters

Imagine replacing the simulated provider with:

  • Escrow.com
  • Stripe Escrow (if available)
  • custom enterprise escrow
  • another regional escrow service

The transaction lifecycle would remain unchanged.

Only the provider implementation would need to change.

That separation makes the architecture considerably more flexible.


Debugging the Workflow

During implementation, extensive logging was added to verify each stage of the lifecycle.

The logs confirmed:

Payment status updated

↓

Payment completed action fired

↓

Transaction lifecycle started

↓

Ownership transfer created

↓

Escrow provider invoked

↓

Escrow reference generated

This confirmed that the entire workflow executes exactly as intended.

After validation, temporary debugging hooks were removed while retaining useful lifecycle logging for development.


Current Escrow Flow

The payment pipeline now behaves as follows:

Buyer submits payment
        │
        ▼
Administrator verifies payment
        │
        ▼
Payment Completed
        │
        ▼
Transaction Lifecycle Manager
        │
        ├────────► Ownership Transfer
        │
        └────────► Escrow Provider
                        │
                        ▼
              Escrow Reference Created

This creates a clean foundation for integrating real external services.


What We Accomplished

In this lesson we successfully:

  • created the Escrow Provider class
  • initialized the provider during plugin bootstrap
  • integrated escrow creation into the transaction lifecycle
  • generated simulated escrow references
  • maintained loose coupling through WordPress actions
  • validated the complete workflow using event-driven architecture
  • prepared the plugin for real escrow provider integration

Looking Ahead

The current provider generates simulated escrow transactions.

In the next lessons, the plugin will evolve further by storing provider information in the database, tracking escrow status, and eventually communicating with real escrow APIs.

By introducing the provider abstraction now, future integrations can be added without restructuring the payment lifecycle.

This is one of the key architectural milestones in transforming Flipnzee Auctions from a simple auction plugin into a professional platform for buying and selling websites, domains, and digital assets.

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

Lesson 121: Designing the Escrow Provider Engine

Series: Building Flipnzee Auctions – From Prototype to Production
Lesson: 121


Introduction

One of the primary objectives of Flipnzee Auctions has always been to facilitate the sale of valuable digital assets such as websites, domains, SaaS applications, WordPress plugins, and online businesses.

Unlike physical products, transferring ownership of a digital business involves several coordinated steps:

  • Buyer submits payment
  • Seller receives confirmation
  • Website files are transferred
  • Database is migrated
  • Domain ownership changes
  • Buyer verifies successful delivery

For transactions involving significant amounts of money, both parties require confidence that the process is secure and fair.

This is precisely the problem that professional escrow services solve.

In this lesson, Flipnzee Auctions begins integrating with external escrow providers by introducing a dedicated Escrow Provider Engine.

Rather than hardcoding support for a single provider, the plugin will establish a generic architecture capable of supporting multiple external transaction providers in the future.


Why Not Hardcode Escrow?

A common mistake during plugin development is embedding provider-specific code directly into payment or transaction managers.

For example:

if provider == Escrow.com
    ...
else if provider == Stripe
    ...
else if provider == PayPal
    ...

As additional providers are added, the code becomes increasingly difficult to maintain.

Instead, Flipnzee Auctions will treat every provider as an interchangeable component.


The Provider Architecture

The plugin already includes an External Provider Manager introduced in previous lessons.

Lesson 121 builds upon that foundation.

The architecture becomes:

Auction

↓

Transaction

↓

Transaction State

↓

External Provider Manager

↓

Escrow Provider

↓

Escrow.com

Instead of communicating directly with Escrow.com, the transaction lifecycle communicates with the External Provider Manager.

The manager then delegates responsibility to the appropriate provider.


Responsibilities of the Escrow Provider

The Escrow Provider will eventually manage tasks such as:

  • Creating an escrow transaction
  • Recording provider references
  • Tracking escrow status
  • Updating transaction states
  • Storing escrow URLs
  • Synchronizing payment progress
  • Logging provider activity

The provider should never contain business rules unrelated to Escrow.

Its responsibility is simply translating Flipnzee Auctions’ workflow into the language understood by the external provider.


Separation of Responsibilities

Each component now has a clear responsibility.

Transaction Lifecycle Manager

Determines when an external provider should be invoked.


Transaction State Manager

Tracks the current lifecycle stage.


External Provider Manager

Determines which provider should handle the transaction.


Escrow Provider

Knows how to communicate with Escrow.com.


This separation dramatically improves maintainability.


Future Providers

Although Lesson 121 focuses on Escrow, the architecture is intentionally generic.

Future providers may include:

  • Escrow.com
  • Stripe
  • PayPal
  • Wise
  • Payoneer
  • Coinbase Commerce
  • Binance Pay
  • Manual Bank Transfer

Every provider should expose a consistent interface while implementing its own communication logic.


Benefits of a Provider Engine

By introducing a provider engine instead of provider-specific code, Flipnzee Auctions gains several advantages:

  • Cleaner architecture
  • Easier testing
  • Reduced coupling
  • Better extensibility
  • Simpler maintenance
  • Multiple payment workflows
  • Enterprise-ready integrations

Perhaps most importantly, administrators will eventually be able to switch providers without modifying the underlying transaction workflow.


Preparing for Real Escrow Integration

Initially, the provider engine will simulate interactions with Escrow.com.

This allows the plugin architecture to mature before introducing:

  • Authentication
  • API credentials
  • Webhooks
  • Callback verification
  • Live transaction synchronization
  • Production error handling

Once these foundations are complete, replacing simulated responses with real API calls becomes significantly easier.


Looking Ahead

In the implementation lesson, we will begin constructing the Escrow Provider Engine by:

  • creating a dedicated Escrow Provider class
  • registering it with the External Provider Manager
  • simulating escrow transaction creation
  • storing provider references
  • connecting provider creation to transaction lifecycle events
  • preparing the plugin for future API communication

This marks the beginning of one of the most significant functional additions to Flipnzee Auctions: secure third-party transaction management through professional escrow services.

Lesson 120 Implementation: Building the Transaction State Machine

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

Lesson 120: Designing a Transaction State Machine for Flipnzee Auctions

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


Introduction

Over the previous lessons, the Flipnzee Auctions plugin has gained several important capabilities. It can create auctions, record winning bids, manage transactions, process payments, and guide administrators through ownership transfers.

Although these features work together, they currently rely on individual events rather than a centralized workflow. A payment completion triggers one action, an ownership transfer triggers another, and each component makes decisions independently.

As the plugin grows to support Escrow.com, additional payment providers, automated notifications, and buyer dashboards, this approach becomes increasingly difficult to maintain.

In this lesson, the plugin takes another significant architectural step by introducing a Transaction State Machine.

Instead of asking:

What event just happened?

the system will begin asking:

What is the current state of this transaction?

This subtle change lays the foundation for a much more scalable and maintainable architecture.


Why a State Machine?

Consider the complete journey of a website sale.

Auction Won

↓

Payment Pending

↓

Payment Completed

↓

Website Files Transfer

↓

Database Transfer

↓

Domain Transfer

↓

Buyer Verification

↓

Completed

Previously, these stages existed only as business knowledge in the administrator’s mind.

The plugin itself had no single place describing where a transaction currently stood.

A transaction state machine changes that.

Every transaction now progresses through a defined sequence of states that represent its lifecycle.


Problems Without States

Without a state machine, different parts of the plugin ask different questions.

The payment manager asks:

Has payment completed?

The transfer manager asks:

Which transfer steps are finished?

The notification system asks:

Which email should I send?

The Escrow integration will eventually ask:

Should Escrow.com be created now?

Each component ends up making its own assumptions.

Eventually those assumptions become inconsistent.


A Better Architecture

Instead of every component deciding independently, every component will consult the same source of truth.

Transaction

↓

Current State

↓

Business Logic

↓

Actions

Examples:

payment_pending

↓

Display payment instructions


payment_completed

↓

Create ownership transfer


database_transfer

↓

Show migration progress


completed

↓

Archive transaction


State vs Event

This distinction is extremely important.

An event describes something that happened.

Payment Completed

A state describes where the transaction is now.

Payment Verified

Events are temporary.

States persist.

Events trigger transitions between states.


Initial Transaction States

The first version of the state machine introduces the following lifecycle.

payment_pending

↓

payment_submitted

↓

payment_completed

↓

files_transfer

↓

database_transfer

↓

domain_transfer

↓

buyer_verification

↓

completed

Additional states such as:

  • cancelled
  • refunded
  • disputed
  • escrow_pending

can be added later without redesigning the plugin.


Centralizing State Definitions

Rather than scattering strings throughout dozens of PHP files, Lesson 120 introduces a dedicated class responsible for transaction states.

For example:

Flipnzee_Transaction_State_Manager::PAYMENT_PENDING

Flipnzee_Transaction_State_Manager::PAYMENT_COMPLETED

Flipnzee_Transaction_State_Manager::COMPLETED

This provides:

  • one authoritative location
  • fewer typing mistakes
  • easier refactoring
  • future localization support

Preparing for Escrow

One of the main goals of this refactoring project is preparing Flipnzee Auctions for external providers such as Escrow.com.

Escrow workflows are inherently state-based.

For example:

Auction Won

↓

Escrow Created

↓

Buyer Funded Escrow

↓

Seller Delivered Website

↓

Buyer Accepted

↓

Escrow Released

Rather than hardcoding Escrow logic into payment pages, the provider will simply observe state transitions.

That is only possible because the plugin now has a formal transaction state machine.


Benefits

By the end of this lesson, Flipnzee Auctions will gain:

  • centralized transaction states
  • reusable state labels
  • helper methods
  • lifecycle awareness
  • cleaner business logic
  • stronger preparation for Escrow integration

Most importantly, the plugin will move away from isolated procedural actions toward a genuine workflow engine.


Coming Next

In the implementation lesson, the plugin will:

  • create a Transaction State Manager
  • define state constants
  • centralize state labels
  • provide helper methods
  • introduce version 1.4.0 database migration
  • prepare persistent transaction states
  • connect the Lifecycle Manager to the new architecture

The result will be a much more maintainable transaction workflow that future lessons can build upon.


Lesson 119 Implementation – Introducing Transaction Lifecycle Events in Flipnzee Auctions

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

Lesson 119: Orchestrating the Auction Transaction Lifecycle


Objective

Build a central Transaction Lifecycle Manager that coordinates the various managers responsible for an auction after it closes.


Why This Lesson?

Currently, several managers know about parts of the workflow:

Auction Manager
Payment Manager
Transaction Manager
Transfer Manager
External Provider Manager
Activity Log
Notification Manager

Each performs its own task.

However, there is no single class responsible for the overall business process.

This means workflow logic is currently scattered across multiple classes.


Current Flow

Auction Ends
      │
      ▼
Winner Determined
      │
      ▼
Transaction Created
      │
      ▼
Payment Submitted
      │
      ▼
Payment Verified
      │
      ▼
Ownership Transfer
      │
      ▼
Transaction Completed

Every step currently triggers another manually.


Proposed Architecture

Introduce a new class:

Flipnzee_Transaction_Lifecycle_Manager

Its responsibility is orchestration—not storage.

Think of it as the project manager of the plugin.


Responsibilities

The Lifecycle Manager will coordinate:

Auction Closed
        │
        ▼
Create Transaction
        │
        ▼
Notify Winner
        │
        ▼
Wait For Payment
        │
        ▼
Verify Payment
        │
        ▼
Create Transfer Record
        │
        ▼
Notify Seller
        │
        ▼
Ownership Transfer
        │
        ▼
Complete Transaction
        │
        ▼
Notify Buyer

Notice that it doesn’t replace the other managers.

It simply tells them when to perform their work.


New Responsibilities

The Lifecycle Manager may call methods such as:

Transaction_Manager::create()

Payment_Manager::create()

Transfer_Manager::create_transfer()

Notification_Manager::send()

Activity_Log::log()

External_Provider_Manager::create_provider()

Each manager remains focused on its own domain.


Benefits

Instead of this:

Auction Manager
     │
     ├── calls Payment
     ├── calls Transfer
     ├── calls Activity Log
     ├── calls Notifications

we move to:

Auction Manager
        │
        ▼
Lifecycle Manager
        │
        ├── Transaction
        ├── Payment
        ├── Transfer
        ├── Activity Log
        ├── Notifications
        └── External Provider

This greatly reduces coupling.


Design Principle

This lesson introduces an important software engineering principle:

Managers should perform work. Coordinators should orchestrate work.

The Lifecycle Manager is a coordinator.

The other managers remain specialists.


Future Expansion

Once this class exists, adding features becomes much easier.

For example:

Escrow.com

↓

Lifecycle Manager

↓

Transfer Manager

or

Stripe Webhook

↓

Lifecycle Manager

↓

Payment Verified

↓

Transfer Manager

No existing managers need major changes.


What We’ll Build

During Lesson 119 we’ll implement:

  • Flipnzee_Transaction_Lifecycle_Manager
  • Lifecycle orchestration methods
  • Central workflow entry points
  • Manager-to-manager coordination
  • Cleaner separation of responsibilities
  • Improved maintainability for future integrations

Learning Objectives

By the end of Lesson 119, readers will understand:

  • The difference between coordination and business logic
  • Why orchestration classes are useful in large plugins
  • How to reduce coupling between components
  • How to design a scalable workflow architecture for complex WordPress plugins

Lesson 118: Implementing an Ownership Transfer Workflow in the Flipnzee Auctions Plugin

In the previous lesson, payment verification marked the financial completion of an auction transaction. However, for website and domain sales, receiving payment is only part of the process. The actual ownership of the digital asset still needs to be transferred from the seller to the buyer.

In this lesson, we implement a dedicated ownership transfer workflow that tracks every stage of the handover process. Rather than relying on manual notes or external spreadsheets, the plugin now provides a structured transfer management system directly inside WordPress.


Why an Ownership Transfer Workflow?

Selling a website is very different from shipping a physical product. A successful transfer often involves multiple independent tasks:

  • Confirming payment
  • Delivering website files
  • Delivering the database
  • Transferring the domain
  • Receiving buyer confirmation

These steps rarely happen simultaneously, and each may require communication between both parties. A dedicated workflow makes the entire process transparent and auditable.


Designing the Transfer Lifecycle

The plugin now models ownership transfer as a sequence of stages.

Auction Ends
        │
        ▼
Payment Verified
        │
        ▼
Website Files Delivered
        │
        ▼
Database Delivered
        │
        ▼
Domain Transfer Completed
        │
        ▼
Buyer Verification
        │
        ▼
Transaction Completed

Each stage can be tracked independently, allowing administrators to immediately identify where a transfer currently stands.


Creating a Dedicated Transfer Manager

Instead of embedding transfer logic throughout the plugin, a dedicated Flipnzee_Transfer_Manager class is responsible for:

  • Creating transfer records
  • Retrieving transfer information
  • Updating transfer progress
  • Calculating completion percentage
  • Determining the overall transfer status
  • Automatically completing transactions

This keeps transfer-related responsibilities isolated from payment, auction, and transaction management.


Recording Individual Transfer Stages

Each transaction stores the status of every transfer stage independently.

Current fields include:

payment_status
files_status
database_status
domain_status
buyer_status
notes

Each stage can be:

  • Pending
  • Completed

This design also makes future status values such as In Progress, Rejected, or Awaiting Buyer straightforward to introduce.


Calculating Progress Automatically

The Transfer Manager now counts completed stages and calculates transfer progress.

For example:

Completed Stages: 3
Total Stages: 5

Progress:
60%

This calculation drives both the numerical progress indicator and the visual progress bar displayed within the administration interface.


Overall Transfer Status

Rather than requiring administrators to manually determine whether a transfer is complete, the plugin now derives an overall status automatically.

Possible values include:

Pending

In Progress

Completed

This status updates automatically as individual stages are completed.


Transaction Details Integration

The Transaction Details page has become the primary workspace for managing ownership transfers.

Administrators can now:

  • Review payment information
  • View payment proof
  • Update payment status
  • Track ownership transfer
  • Update every transfer stage
  • Record transfer notes

This centralises all post-auction management into a single interface.


Transfer Progress Dashboard

A visual progress section has been added to the Transaction Details screen displaying:

  • Progress counter
  • Progress percentage
  • Progress bar
  • Overall transfer status

This provides immediate insight into the current state of every website sale.


Saving Transfer Information

Administrators can update all ownership transfer fields using a dedicated form.

The plugin stores:

  • Website file delivery
  • Database delivery
  • Domain transfer
  • Buyer confirmation
  • Administrative notes

All information is saved into the transfer table for future reference.


Automatic Transaction Completion

One of the most useful improvements introduced in this lesson is automatic transaction completion.

Once all transfer stages have been marked as completed:

Payment
✓

Website Files
✓

Database
✓

Domain
✓

Buyer Confirmation
✓

the plugin automatically updates the associated transaction status to:

Completed

This removes repetitive administrative work while ensuring transactions accurately reflect the real-world ownership transfer process.


Transfer Management Dashboard

A dedicated Transfer Management page now provides an overview of all ownership transfers.

Administrators can quickly see:

  • Transaction ID
  • Overall status
  • Progress
  • Individual stage status
  • Administrative notes
  • Direct link to transaction details

This creates a central dashboard for monitoring every website handover.


Improving Plugin Architecture

This lesson also involved refactoring several areas of the codebase.

Responsibilities are now better separated:

  • Auction Manager manages auctions.
  • Payment Manager manages payments.
  • Transaction Manager manages transactions.
  • Transfer Manager manages ownership transfer.

This clearer separation improves maintainability while making future enhancements easier to implement.


Preparing for External Providers

Although ownership transfers are currently managed manually, the new workflow establishes the foundation for integrating external providers such as Escrow.com.

Future versions can automatically update transfer progress based on provider events while continuing to use the same internal workflow.


What We Achieved

By the end of this lesson, the Flipnzee Auctions plugin now supports:

  • Dedicated ownership transfer records
  • Multi-stage transfer workflow
  • Progress calculation
  • Overall transfer status
  • Progress indicators
  • Transfer notes
  • Transaction Details integration
  • Transfer Management dashboard
  • Automatic transaction completion
  • Cleaner separation of responsibilities

Conclusion

Ownership transfer is a critical part of selling websites, domains, and other digital assets. By introducing a structured transfer workflow, the Flipnzee Auctions plugin now manages not only the auction itself but also the operational process that follows payment.

The result is a more complete marketplace solution that provides better visibility, improved administration, and a stronger foundation for future automation through external escrow and payment providers.

In the next lesson, we will begin connecting this workflow with external providers, allowing payment, escrow, and ownership transfer to operate as a unified transaction lifecycle.

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