Lesson 118: Connecting Payment Verification to the Ownership Transfer Workflow

In the previous lesson, the Flipnzee Auctions plugin introduced a complete payment verification workflow. Buyers can upload payment proof, administrators can review the submission, and the payment progresses through a structured lifecycle from Pending to Submitted, Verified, and finally Completed.

Although this completes the payment process, a website sale does not end when payment is received. The actual ownership transfer still needs to take place.

This lesson focuses on bridging the gap between payment management and website transfer management.


Why a Transfer Workflow?

Unlike physical products, websites consist of multiple digital assets that must be transferred individually.

A successful website sale may include:

  • Website files
  • Database
  • Domain name
  • Hosting credentials
  • Administrator accounts
  • Email accounts
  • Documentation

Completing payment simply authorizes the beginning of this process.


Current Workflow

After Lesson 117, the payment lifecycle looks like this:

Auction Won
      │
      ▼
Pending
      │
      ▼
Payment Submitted
      │
      ▼
Payment Verified
      │
      ▼
Payment Completed

While technically correct, this skips one of the most important business processes.


Introducing Ownership Transfer

Instead of ending the transaction after payment, we’ll introduce a dedicated transfer phase.

The revised workflow becomes:

Auction Won
      │
      ▼
Payment Submitted
      │
      ▼
Payment Verified
      │
      ▼
Ownership Transfer
      │
      ▼
Transaction Completed

This separates financial completion from operational completion.


The Transfer Dashboard

The Flipnzee Auctions plugin already includes a Transfer Management page.

Rather than creating another administration interface, this page will evolve into the central dashboard for tracking every ownership transfer.

Each transfer will contain multiple independent tasks.


Transfer Components

Instead of a single “Transferred” flag, the workflow will track individual stages.

For example:

Files
───────────────
Pending
In Progress
Completed
Database
────────────────
Pending
In Progress
Completed
Domain
───────────────
Pending
In Progress
Completed
Buyer Confirmation
──────────────────────
Pending
Completed

Tracking each component independently provides administrators with much greater visibility into the progress of a transaction.


Why Separate Payment and Transfer?

Although payment and ownership transfer are related, they represent different business processes.

Payment answers one question:

Has the buyer paid?

Transfer answers another:

Has the buyer actually received ownership of the website?

Separating these workflows reduces ambiguity and more accurately reflects how website acquisitions are managed.


Triggering a Transfer

Once an administrator verifies a payment, the plugin can automatically prepare the transfer process.

The simplified workflow becomes:

Payment Verified
        │
        ▼
Transfer Record Ready
        │
        ▼
Files
Database
Domain
Buyer Confirmation

Administrators no longer need to manually create transfer records.


Administrative Workflow

The administrator’s responsibilities now expand beyond payment approval.

A typical transaction becomes:

Review Payment Proof
        │
        ▼
Verify Payment
        │
        ▼
Transfer Website Files
        │
        ▼
Transfer Database
        │
        ▼
Transfer Domain
        │
        ▼
Buyer Confirms Receipt
        │
        ▼
Complete Transaction

This mirrors the practical workflow followed by agencies and marketplace operators when transferring ownership of digital assets.


Buyer Experience

The buyer also benefits from a more transparent process.

Instead of seeing only:

Payment Completed

they can eventually follow the transfer itself.

Example:

Payment Verified

Website Transfer

✓ Files

✓ Database

✓ Domain

Waiting for Buyer Confirmation

This reduces uncertainty and provides confidence that the transaction is progressing.


Foundation for Future Automation

Designing transfer management as its own workflow opens the door to future enhancements.

Potential additions include:

  • Automatic transfer record creation
  • Progress tracking
  • Email notifications
  • Buyer acknowledgements
  • Transfer checklists
  • Internal notes
  • Document uploads
  • Completion certificates

Because the transfer system is independent of payment processing, these features can be added without changing the payment workflow.


Lessons Learned

Real-world business processes often consist of multiple related workflows rather than a single sequence of events.

By separating payment verification from ownership transfer, the Flipnzee Auctions plugin becomes easier to maintain while better representing the lifecycle of a website sale.

This modular approach also keeps the codebase extensible as additional transfer features are introduced.


Conclusion

Lesson 118 marks the transition from payment management to operational ownership transfer. Instead of treating payment as the end of the transaction, the plugin now recognizes it as the beginning of the website handover process.

With a dedicated Transfer Management workflow already in place, the next lessons will focus on automating transfer creation, tracking progress across multiple transfer stages, and providing administrators and buyers with a clearer view of each transaction from payment verification through final ownership transfer.

Lesson 117: Building the Admin Payment Verification Workflow

In the previous lesson, the buyer payment page was refactored into a clean, state-driven architecture. Buyers can now submit payment proof, and the interface automatically reflects the payment status.

However, one important piece of the workflow is still missing.

Once a buyer uploads proof of payment, an administrator needs a way to verify it before ownership transfer can begin.

In this lesson, we’ll implement the Payment Verification Workflow in the WordPress admin panel.


Where We Left Off

Our payment lifecycle currently looks like this:

Auction Won
        │
        ▼
Pending
        │
        ▼
Manual Payment
        │
        ▼
Upload Payment Proof
        │
        ▼
Submitted

At this point, the buyer has completed everything required.

The next step belongs to the administrator.


Current Problem

Although payment proofs are stored successfully, administrators cannot yet:

  • verify the payment
  • reject incorrect payment proofs
  • begin ownership transfer
  • update the buyer’s payment status

The transaction simply remains in the Submitted state.


Goal of This Lesson

We’ll extend the Admin Payments screen so administrators can manage submitted payments directly.

Each submitted transaction should display actions such as:

Verify Payment

Later lessons will add:

Reject Payment

Mark Transfer Started

Complete Transfer

New Payment Workflow

The buyer and administrator will now share responsibility for the payment lifecycle.

Buyer
──────────────

Win Auction
↓

Choose Payment Method
↓

Upload Payment Proof
↓

Submitted



Administrator
────────────────────────

Review Payment Proof
↓

Verify Payment
↓

Ownership Transfer
↓

Completed

Why Verify Instead of Mark Paid?

Payment verification represents a business decision rather than simply changing a status.

The administrator confirms that:

  • payment amount is correct
  • payment reference matches
  • uploaded proof is valid
  • payment has actually been received

Only after these checks should ownership transfer begin.


State Transition

We’ll introduce our first administrator-driven state transition.

Submitted
      │
      ▼
Verified

Later:

Verified
      │
      ▼
Completed

Because the buyer page is already state-driven, changing a single database value automatically changes the buyer experience.


Updating the Admin Payments Table

For submitted payments, we’ll add a new action button.

Example:

Transaction #27

Status:
Submitted

[ Verify Payment ]

Once clicked, the plugin will:

  • validate the request
  • verify the nonce
  • update payment status
  • refresh the admin screen

Database Changes

The database already stores the payment status.

No schema changes are required.

We’ll simply update:

payment_status

from

submitted

to

verified

This is one advantage of designing the payment system around discrete states.


Buyer Experience

The buyer does not need to perform any additional action.

Once the administrator verifies the payment, the payment page will automatically switch from:

Payment Submitted

to

Payment Verified

Ownership transfer has started.

No additional templates or pages are required.


Security Considerations

Administrative actions should always include:

  • capability checks
  • nonce verification
  • transaction validation
  • status validation

For example, only payments currently marked as Submitted should be eligible for verification.

Attempting to verify an already completed transaction should simply be ignored.


Benefits of This Design

Separating buyer actions from administrator actions keeps responsibilities clear.

Buyers can:

  • choose payment methods
  • upload payment proof
  • monitor progress

Administrators can:

  • verify payment
  • initiate ownership transfer
  • complete transactions

This separation also makes future integrations with automated gateways much easier.


What We’ll Build

By the end of this lesson, administrators will be able to:

  • view submitted payments
  • verify payments with one click
  • update the payment status
  • immediately update the buyer-facing payment page

Next Steps

Once payment verification is complete, the plugin will be ready for the next major milestone:

  • Ownership Transfer Workflow
  • Transaction Completion
  • Email Notifications
  • Additional Payment Gateways
  • Escrow.com Integration
  • Audit Logging

The payment system is gradually evolving from a simple upload form into a complete transaction management workflow that mirrors how real-world website sales are handled.

Lesson 116 – Designing a State-Driven Buyer Payment Workflow


Introduction

In the previous lesson, the Buy Now workflow became fully functional. When a buyer purchases a website, the auction is closed, a winner is declared, a transaction is created, an external provider record is initialized, and a transfer record is prepared. Finally, the buyer is redirected to the payment page.

Although the backend workflow is now complete, the payment page itself still behaves like a prototype. Every payment option is displayed, buttons remain visible regardless of transaction status, and the interface does not yet guide buyers through the payment process.

In this lesson, the focus shifts from backend infrastructure to user experience. Rather than treating the payment page as a static form, it will evolve into a workflow that changes based on the current state of the transaction.


Why this lesson is important

A payment page should answer one simple question:

“What should the buyer do next?”

Instead of always displaying the same controls, the interface should respond to the transaction’s current status.

For example:

  • Before payment, buyers should choose a payment method.
  • After payment submission, buyers should see confirmation instead of payment options.
  • Once payment is verified, they should see transfer progress.
  • After transfer completion, they should receive ownership confirmation.

This creates a guided experience instead of presenting every possible action at once.


Current Workflow

Listing
        │
        ▼
Place Bid / Buy Now
        │
        ▼
Auction Closed
        │
        ▼
Winner Determined
        │
        ▼
Transaction Created
        │
        ▼
External Provider Created
        │
        ▼
Transfer Record Created
        │
        ▼
Buyer Payment Page

The backend now reaches the payment page successfully.


Proposed Workflow

Instead of one static page:

Pending Payment
        │
        ▼
Select Payment Method
        │
        ▼
Manual Payment Instructions
        │
        ▼
Upload Proof
        │
        ▼
Payment Submitted
        │
        ▼
Admin Verification
        │
        ▼
Payment Verified
        │
        ▼
Transfer Started
        │
        ▼
Ownership Delivered

Each state presents only the actions that are relevant at that moment.


Planned UI States

State 1 — Pending Payment

Display:

  • Transaction summary
  • Winning bid
  • Payment methods
  • Continue to Payment

State 2 — Manual Payment

Display:

  • Bank details
  • Payment instructions
  • Upload payment proof

Hide all unnecessary payment options.


State 3 — Payment Submitted

Display:

✔ Payment Submitted

Our team has received your payment proof.

Status:
Awaiting Verification

No payment buttons should remain visible.


State 4 — Payment Verified

Display:

✔ Payment Verified

Preparing ownership transfer...

Show transfer progress instead of payment controls.


State 5 — Transfer Complete

Display:

✔ Congratulations!

The website has been transferred successfully.

Offer download links or ownership instructions if applicable.


Why State-Driven Interfaces Matter

Large marketplaces rarely present every possible action simultaneously.

Instead, the interface adapts according to the transaction.

Benefits include:

  • Less confusion
  • Cleaner interface
  • Better user guidance
  • Reduced accidental actions
  • Easier maintenance
  • Simpler future payment gateway integration

Lesson Objectives

By the end of this lesson, readers will understand:

  • Why payment pages should be workflow-driven
  • How transaction status determines the interface
  • How payment and transfer states relate
  • Why state-driven design scales better as new gateways are added

Looking Ahead

The backend payment architecture is now in place. Future lessons will focus on polishing the buyer experience by hiding irrelevant controls, presenting clear payment instructions, and progressively revealing the next action as the transaction advances through its lifecycle.


Previous Lesson: Lesson 115 – Completing the Buy Now Transaction Pipeline and External Provider Integration

Next Lesson: Lesson 116 Implementation – Building a State-Driven Buyer Payment Interface


Lesson 116: Refactoring the Buyer Payment Page into a State-Driven Workflow

As the Flipnzee Auctions plugin continues to mature, the buyer payment page has evolved beyond a simple form. It now manages multiple stages of a transaction—from selecting a payment method to uploading payment proof and tracking verification status. As additional payment gateways and workflows are planned, maintaining everything inside a single method would quickly become difficult.

In this lesson, the payment page is refactored into a cleaner, state-driven architecture while preserving the existing functionality.


Why Refactor?

The original implementation mixed several responsibilities inside one method:

  • Validating the transaction
  • Handling payment gateway selection
  • Uploading payment proof
  • Displaying transaction details
  • Rendering different payment states
  • Showing payment instructions

Although functional, this structure made future enhancements increasingly difficult.

The objective was to separate these responsibilities into focused methods that each perform one task.


Design Goals

The refactoring focused on four principles:

  • Smaller, easier-to-read methods
  • Separation of business logic and presentation
  • State-driven rendering
  • A scalable foundation for future payment gateways

This approach aligns more closely with object-oriented design and WordPress coding standards.


Simplifying render()

The render() method now serves primarily as the controller for the page.

Its responsibilities are limited to:

  • Validating the request
  • Loading the transaction
  • Processing payment proof uploads
  • Delegating payment actions
  • Rendering the appropriate payment state

Instead of containing hundreds of lines of mixed logic, it now orchestrates the workflow through dedicated helper methods.


Extracting Payment Submission Logic

Payment gateway processing was moved into its own method:

private static function handle_payment_submission()

This method now handles:

  • nonce validation
  • selected gateway validation
  • gateway routing
  • unsupported gateway messaging

The result is a much cleaner entry point that will make future integrations significantly easier.


Introducing a State Machine

Rather than scattering conditional statements throughout the page, the buyer interface now behaves like a simple state machine.

Current payment states include:

  • Pending
  • Submitted
  • Verified
  • Completed

A single controller determines which section should be displayed.

render_payment_state()

Internally it delegates to dedicated rendering methods for each state.


Dedicated Rendering Methods

Instead of one large template, each payment state now has its own renderer.

Examples include:

  • render_pending_state()
  • render_submitted_state()
  • render_verified_state()
  • render_completed_state()

Each method focuses on presenting one stage of the payment lifecycle.

This improves readability while making future UI enhancements much safer.


Payment Proof Upload

The payment proof upload process remains fully functional after the refactor.

The workflow now becomes:

  1. Buyer selects Manual Payment.
  2. Payment instructions are displayed.
  3. Buyer uploads proof of payment.
  4. The proof is stored.
  5. Payment status changes to Submitted.
  6. The buyer now sees a confirmation message instead of the upload form.

This creates a much clearer user experience while preventing duplicate uploads.


Transaction Summary

The transaction summary has also been isolated into its own renderer.

It displays:

  • Transaction ID
  • Winning Bid
  • Transaction Status
  • Payment Status
  • Selected Payment Gateway

Keeping this component separate makes future additions—such as payment timestamps or invoice numbers—straightforward.


Benefits of the Refactor

Compared to the previous implementation, the payment page is now:

  • Easier to read
  • Easier to debug
  • Easier to test
  • Easier to extend
  • Better aligned with object-oriented design

Future payment gateways such as Escrow.com, Stripe, PayPal, Wise, and cryptocurrency integrations can now be added with minimal impact on the rest of the codebase.


Lessons Learned

One important takeaway from this refactor is that working code is not always well-structured code.

As software grows, periodically revisiting earlier implementations helps improve maintainability without changing the user-facing behaviour.

By separating responsibilities into focused methods, the payment page becomes easier to understand today while reducing technical debt for future development.


Current Payment Lifecycle

The buyer payment workflow now follows a clear sequence:

Auction Won
        │
        ▼
Pending Payment
        │
        ▼
Select Payment Gateway
        │
        ▼
View Payment Instructions
        │
        ▼
Upload Payment Proof
        │
        ▼
Submitted
        │
        ▼
Verified (Admin)
        │
        ▼
Ownership Transfer
        │
        ▼
Completed

Conclusion

Although this lesson introduces very few visible changes to the buyer interface, it represents an important architectural milestone for the Flipnzee Auctions plugin. The payment page has been transformed from a monolithic implementation into a modular, state-driven workflow that is easier to maintain and extend.

With this foundation in place, the next lessons can focus on the administrative side of the payment lifecycle, including payment verification, ownership transfer, transaction completion, and integration with additional payment gateways, all without requiring major structural changes to the buyer-facing code.

https://github.com/SplendidDigital/flipnzee-auctions/releases/tag/lesson-116-payment-page-refactor

Lesson 115 – Implementation: Implementing the Buy Now Auction Completion Workflow


Introduction

In the previous lesson, we outlined how the Buy Now feature should behave from a business perspective. In this implementation lesson, we transform that design into working code.

Rather than introducing a separate purchase engine, the implementation builds upon the auction infrastructure already developed throughout the project. The result is a cleaner architecture where a Buy Now purchase is simply a special case of a successful bid that immediately concludes the auction.


Step 1 – Detect Buy Now Bids

A new helper method was introduced:

Flipnzee_Bid_Manager::is_buy_now_bid()

This method retrieves the configured Buy Now price for the auction and compares it against the submitted bid amount.

If the bid is equal to or greater than the Buy Now price, the method returns true.

Keeping this logic separate makes the bid placement code easier to understand and allows future enhancements without modifying the core bidding workflow.


Step 2 – Update the Bid Handler

After a successful bid is recorded, the bid handler now performs an additional check:

$is_buy_now = Flipnzee_Bid_Manager::is_buy_now_bid(
    $auction_id,
    $bid_amount
);

For ordinary bids, execution continues exactly as before.

For Buy Now bids, the workflow branches into an immediate auction completion sequence.


Step 3 – Close the Auction

A new method was added to the Auction Manager:

Flipnzee_Auction_Manager::close_auction(
    $auction_id
);

This method:

  • updates the auction status to closed,
  • records the closing timestamp,
  • returns whether the update succeeded.

Centralising this behaviour inside the Auction Manager keeps auction state management in a single location.


Step 4 – Determine the Winner Immediately

Once the auction is closed, the existing winner determination logic is reused:

Flipnzee_Bid_Manager::determine_winner(
    $auction_id
);

No duplicate winner-selection logic is required.

The plugin simply performs the same process that would normally occur after the scheduled auction expiry.


Step 5 – Reuse Existing Hooks

Because winner determination already fires the existing action hook:

do_action(
    'flipnzee_auction_winner_determined',
    $auction_id,
    $winner
);

the following systems continue working automatically:

  • Buyer notification
  • Seller notification
  • Administrator notification
  • Transaction creation

This demonstrates one of the benefits of designing around WordPress actions rather than tightly coupled method calls.


Step 6 – Automatically Create the Transaction

The existing Transaction Manager now creates the purchase transaction immediately after the winner is determined.

This removes the delay that previously existed between auction completion and payment.

The buyer is now ready to proceed directly to the payment stage.


Step 7 – Integrate the External Provider Workflow

During implementation, the transaction workflow also creates an associated external provider record for future integrations such as Escrow.com.

This lays the foundation for supporting external payment and escrow services without altering the auction workflow itself.


Debugging the Workflow

This lesson involved significantly more debugging than implementation.

Extensive logging was added throughout the Buy Now workflow to verify each stage executed correctly.

Typical log entries included:

  • Buy Now detection
  • Auction closure
  • Winner determination
  • Notification dispatch
  • Transaction creation
  • External provider creation

These logs made it possible to isolate failures quickly and verify that each subsystem executed in the expected order.


Issues Encountered

Several issues surfaced while implementing this workflow:

  • Buy Now bids behaved like normal bids.
  • Auctions remained active after reaching the Buy Now price.
  • Winner determination was not triggered immediately.
  • Transaction creation exposed a missing class loading issue for the External Provider Manager.
  • Front-end auction state required refreshing after administrative changes because the database status remained closed until explicitly reopened.

Resolving these issues reinforced the importance of validating the complete workflow rather than assuming each individual component behaved correctly in isolation.


Final Workflow

After completing Lesson 115, the Buy Now process now follows this sequence:

Buyer submits Buy Now bid
        │
        ▼
Bid accepted
        │
        ▼
Buy Now detected
        │
        ▼
Auction closed
        │
        ▼
Winner determined
        │
        ▼
Notifications sent
        │
        ▼
Transaction created
        │
        ▼
External provider record created
        │
        ▼
Buyer proceeds to payment

Conclusion

With this lesson complete, the Flipnzee Auctions plugin now supports an end-to-end Buy Now workflow. A qualifying bid no longer waits for the auction timer to expire; instead, it immediately concludes the auction, determines the winner, creates the transaction, and launches the payment process.

This represents a major architectural milestone. The plugin has evolved from handling bids and scheduled auction endings to supporting immediate purchases through a unified auction lifecycle, providing a solid foundation for future enhancements such as escrow integrations, automated transfers, and richer post-sale workflows.

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

Lesson 115: Buy Now Auction Completion Workflow (Planning)

Introduction

Until now, the Flipnzee Auctions plugin has treated every bid in the same way. Regardless of the bid amount, the auction remains active until its scheduled end time, where a scheduled process later determines the winner.

However, this behavior is not how a traditional Buy Now feature is expected to work.

When a bidder agrees to pay the Buy Now price, they are effectively accepting the seller’s asking price. At that point there should be no reason to keep the auction running or allow additional bids.

This lesson focuses on transforming Buy Now from a simple display price into an action that immediately completes the auction.


Current Problem

Suppose an auction has:

  • Start Price: $120
  • Current Bid: $1,200
  • Buy Now Price: $5,000

If a buyer places a bid of exactly $5,000, the plugin currently:

  • accepts the bid,
  • updates the current bid,
  • leaves the auction active,
  • allows other users to continue bidding.

This defeats the purpose of having a Buy Now option.


Expected Behaviour

The expected workflow should become:

Buyer submits Buy Now bid
        │
        ▼
Bid is accepted
        │
        ▼
Buy Now condition detected
        │
        ▼
Auction closes immediately
        │
        ▼
Winner determined
        │
        ▼
Winner notifications sent
        │
        ▼
Transaction created
        │
        ▼
Buyer redirected to payment

Instead of waiting until the scheduled auction end, the auction lifecycle should complete immediately.


Why This Matters

This change transforms the auction from a passive bidding system into an actual marketplace transaction.

It establishes a complete workflow where:

  • bidding,
  • winner determination,
  • transaction creation,
  • payment,
  • ownership transfer

all become part of a single automated process.

Without this behaviour, Buy Now is merely another bid amount rather than an instant purchase mechanism.


Design Considerations

Rather than scattering Buy Now logic throughout the plugin, we will introduce a clear sequence of responsibilities.

The bid handler should remain responsible for accepting bids.

Once a valid bid has been recorded, it should ask one simple question:

“Did this bid satisfy the Buy Now price?”

If the answer is yes, the auction manager will immediately close the auction and the existing winner determination workflow can continue unchanged.

This approach reuses the infrastructure already built in previous lessons instead of creating an entirely separate purchase system.


Objectives

By the end of this lesson we will:

  • Detect when a submitted bid reaches the Buy Now price.
  • Close the auction immediately.
  • Determine the winning bidder instantly.
  • Reuse the existing notification system.
  • Automatically create the buyer transaction.
  • Launch the payment workflow without waiting for auction expiry.

What We’ll Build

At the end of this lesson, the auction lifecycle will look like this:

Auction Created
        │
        ▼
Buyer Places Bid
        │
        ▼
Buy Now Price Reached
        │
        ▼
Auction Closed Immediately
        │
        ▼
Winner Determined
        │
        ▼
Notifications Sent
        │
        ▼
Transaction Created
        │
        ▼
Buyer Payment Page

This is one of the most important milestones in the Flipnzee Auctions project, as it connects bidding with the complete post-auction purchase workflow.


Lesson 114 – Refactoring the Buyer Payment Page with a State-Driven Interface

One of the goals of the Flipnzee Auctions project is to continuously improve the codebase while keeping the plugin functional at every stage. Rather than adding new features immediately, this lesson focuses on improving the buyer payment experience by making the interface respond to the current payment status.

Instead of always displaying payment options regardless of the transaction state, the payment page now renders different views depending on where the buyer is in the payment process.


Project Goals

In previous lessons, the payment workflow allowed buyers to:

  • View transaction details
  • Choose a payment gateway
  • View manual payment instructions
  • Upload payment proof

Although functional, the payment page continued to display payment controls even after payment proof had already been submitted. This could confuse buyers and encourage duplicate submissions.

The objective of this lesson was to make the payment page aware of the payment lifecycle.


Problems with the Previous Implementation

Previously, the payment page always rendered:

  • Transaction summary
  • Gateway selector
  • Payment buttons

regardless of whether the buyer had already submitted payment proof.

This produced an interface similar to:

Transaction Summary

↓

Payment Gateway Selection

↓

Manual Payment Instructions

↓

Upload Proof

↓

Payment Gateway Selection (still visible)

The buyer could continue interacting with payment controls that were no longer relevant.


Design Objective

The payment page should automatically display information that matches the transaction’s current state.

Instead of asking the buyer what to do next, the interface should guide them naturally through the workflow.


State-Driven Rendering

A new rendering controller was introduced:

self::render_payment_state(
    $transaction,
    $gateways
);

Instead of directly rendering the gateway selector, the payment page now delegates rendering to a state-aware method.


Payment States

The renderer evaluates the current payment status.

switch ( strtolower( $transaction->payment_status ) ) {

    case 'submitted':
        ...
        break;

    case 'verified':
        ...
        break;

    case 'completed':
        ...
        break;

    default:
        ...
}

Each payment status now has its own dedicated renderer.


Pending State

Pending transactions continue using the existing payment workflow.

private static function render_pending_state(
    $transaction,
    $gateways
) {

    self::render_gateway_selector(
        $gateways
    );

}

From the buyer’s perspective, nothing changes until payment has actually been submitted.


Submitted State

After payment proof is uploaded, the page now replaces the gateway selector with a confirmation message.

Example:

Payment Submitted

Your payment proof has been received.

Our team will verify your payment before ownership transfer begins.

This prevents unnecessary duplicate uploads while reassuring the buyer that their submission has been received.


Verified State

Future lessons will allow administrators to verify payments.

Once verification occurs, buyers will see a confirmation such as:

Payment Verified

Ownership transfer has started.

No additional payment actions are displayed.


Completed State

When ownership transfer has been completed, the payment page will display a completion message instead of payment controls.

Example:

Transaction Completed

Ownership has been transferred successfully.

This provides a natural end to the purchase workflow.


Transaction Summary

The transaction summary remains available throughout every stage.

Information displayed includes:

  • Transaction ID
  • Winning Bid
  • Transaction Status
  • Payment Status
  • Selected Payment Gateway

This allows buyers to monitor the progress of their purchase without losing important transaction details.


User Experience Improvements

Before this lesson:

Payment Summary

↓

Gateway Selection

↓

Manual Payment

↓

Upload Proof

↓

Gateway Selection still visible

After this lesson:

Payment Summary

↓

Pending

↓

Gateway Selection

↓

Upload Proof

↓

Submitted

↓

Waiting for Verification

↓

Verified

↓

Ownership Transfer

↓

Completed

The payment page now behaves more like a modern checkout portal, displaying only the actions that are appropriate for the buyer’s current stage.


Architectural Benefits

Although this lesson introduced only a small visible change, it significantly improved the overall design.

Benefits include:

  • State-driven rendering
  • Reduced UI clutter
  • Clear buyer guidance
  • Easier maintenance
  • Better separation between transaction information and payment workflow
  • Foundation for future payment gateways

Lessons Learned

One important lesson during development was recognizing the difference between refactoring and rewriting.

Several attempts were made to extract large portions of the payment processing logic into separate methods. While architecturally appealing, making too many structural changes at once introduced unnecessary complexity during debugging.

The final implementation adopted a more conservative approach by refactoring only the rendering layer while preserving the existing payment processing logic. This resulted in a cleaner user interface without risking regressions in the working payment workflow.

This incremental strategy is often preferable in production software, where maintaining stability is just as important as improving code quality.


Conclusion

Lesson 114 transformed the Buyer Payment Page from a static form into a state-driven interface that responds intelligently to the payment lifecycle.

While the underlying payment processing remains unchanged, buyers now receive a clearer and more intuitive experience, and the architecture is better prepared for future enhancements such as administrator payment verification and automated ownership transfers.

In the next lesson, we will build the Admin Payment Verification Workflow, allowing administrators to approve submitted payments and advance transactions to the ownership transfer stage.

lesson-114-stable: Lesson 114: Refactor buyer payment page with state-driven rendering

Lesson 114 — State-Driven Payment Workflow

Objective

In Lesson 113, the Flipnzee Auctions plugin gained a complete payment workflow, including gateway selection, manual payments, payment proof uploads, and transaction tracking.

However, the payment page still displays multiple interface components simultaneously, regardless of the transaction’s current state. As additional payment providers and transfer stages are introduced, this approach will become increasingly difficult to maintain.

The objective of Lesson 114 is to refactor the payment page into a state-driven workflow, where the user interface changes automatically based on the transaction’s current payment status.


Why Refactor?

Currently, class-payment-page.php mixes together several responsibilities:

  • Loading transactions
  • Processing uploads
  • Rendering summaries
  • Rendering payment gateways
  • Rendering manual payment instructions
  • Displaying success messages

As more payment providers and statuses are added, the file will become difficult to understand and maintain.

Instead of checking multiple conditions throughout the page, the plugin should have one central decision point responsible for determining which interface to display.


Current Workflow

Load Transaction

↓

Display Summary

↓

Display Gateway Selection

↓

Manual Payment

↓

Upload Proof

↓

Display Messages

Regardless of payment status, much of the interface continues to be shown.


Desired Workflow

Load Transaction

↓

Read payment_status

↓

pending
│
├── Show Gateway Selection
├── Allow Payment
└── Allow Upload

submitted
│
├── Payment Submitted
├── Awaiting Verification
└── Hide Payment Controls

verified
│
├── Payment Verified
├── Ownership Transfer Started
└── Display Progress

completed
│
├── Transfer Completed
└── Transaction Finished

Only the interface relevant to the current stage should be displayed.


Architectural Goal

Rather than writing numerous if statements throughout the payment page, the plugin will introduce a dedicated payment state renderer.

render()

        │
        ▼

Load Transaction

        │
        ▼

render_transaction_summary()

        │
        ▼

render_payment_state()

        │
        ▼

Pending
Submitted
Verified
Completed

Each payment state becomes responsible for rendering its own interface.


New Rendering Methods

The payment page will gradually be divided into focused rendering methods such as:

  • render_pending_state()
  • render_submitted_state()
  • render_verified_state()
  • render_completed_state()

Each method will display only the controls appropriate for that stage.


Benefits

This refactoring provides several advantages.

Cleaner Code

Instead of hundreds of lines inside render(), each payment state becomes a small, focused method.


Easier Maintenance

Adding new payment providers no longer requires editing multiple parts of the payment page.


Better User Experience

Buyers only see the actions relevant to their current payment stage.

For example:

Pending

  • Select Gateway
  • Upload Proof

Submitted

  • Confirmation message
  • Waiting for review

Verified

  • Ownership transfer started

Completed

  • Auction completed

Easier Future Integrations

Future lessons will introduce:

  • Escrow.com API
  • Stripe
  • PayPal
  • Razorpay
  • Cryptocurrency
  • Admin verification
  • Automatic ownership transfer

Each of these features can simply render the appropriate payment state without restructuring the payment page.


Engineering Principle

Lesson 114 introduces an important software engineering concept:

The user interface should reflect the current state of the underlying business process.

Instead of asking:

“Which buttons should I display?”

the plugin asks:

“What is the current payment state?”

The interface then naturally follows from that answer.


Files to Modify

Primary:

includes/class-payment-page.php

Potentially:

includes/class-payment-manager.php

for helper methods if needed.


Expected Outcome

By the end of Lesson 114:

  • Payment rendering will be state-driven.
  • Gateway selection will only appear when payment is pending.
  • Submitted payments will display confirmation instead of payment controls.
  • The payment page will be significantly cleaner and easier to extend.
  • The foundation will be ready for Lesson 115, which will introduce the Admin Payment Verification Workflow.

Git Tag Recommendation

lesson-114-stable

This lesson marks an architectural milestone. Rather than adding new functionality, it refines the payment system into a scalable design that will support all future payment providers and ownership transfer stages.

Lesson 113: Building the Payment Workflow Foundation

In the previous lessons, auctions could successfully determine a winner and create a transaction. However, there was still no mechanism for the buyer to complete payment or for the marketplace to track payment progress.

This lesson introduces the payment workflow foundation for Flipnzee Auctions.

Rather than integrating directly with a payment provider immediately, the plugin now establishes a flexible payment architecture capable of supporting multiple providers in future releases while already allowing manual payment submissions.


Objectives

This lesson aimed to:

  • Create a buyer payment page
  • Support multiple payment providers
  • Introduce an External Provider architecture
  • Allow manual payment submissions
  • Upload payment proof
  • Prepare the plugin for Escrow.com integration
  • Preserve compatibility with future gateways

External Provider Architecture

Instead of embedding payment provider logic directly inside the transaction manager, the plugin now introduces an independent provider layer.

Auction
    │
    ▼
Transaction
    │
    ▼
External Provider
    │
    ▼
Transfer

This separation keeps responsibilities clear.

Transactions continue to represent marketplace events, while external providers maintain information about third-party payment services.


Database Changes

Lesson 113 introduces a dedicated table for provider-specific information.

wp_flipnzee_external_providers

The table stores:

  • Transaction ID
  • Provider name
  • External reference
  • External URL
  • Provider status
  • Notes
  • Timestamps

This allows each transaction to maintain its own provider lifecycle independently of the payment record itself.


Buyer Payment Page

A new frontend payment page was implemented.

The page now:

  • Displays transaction information
  • Shows the winning bid
  • Displays payment status
  • Displays the selected payment gateway

The payment page retrieves transactions securely using the transaction ID passed through the URL.


Supported Payment Providers

The gateway selector was designed from the beginning to support multiple providers.

Current options include:

  • Escrow.com (recommended)
  • Manual Payment
  • Stripe
  • PayPal
  • Razorpay
  • Cryptocurrency (USDT)

Only Manual Payment is currently active.

The remaining gateways are intentionally displayed as “Coming Soon,” allowing the interface to remain stable while future integrations are developed.


Manual Payment Workflow

The first complete payment workflow now exists.

After selecting Manual Payment, buyers receive:

  • Payment instructions
  • Reference number
  • Amount due
  • Payment status
  • Important reminders

The workflow is intentionally simple while providing a complete end-to-end payment process.


Uploading Payment Proof

Buyers can upload payment evidence directly from the payment page.

Supported formats include:

  • JPG
  • JPEG
  • PNG
  • PDF

Uploads are handled using the standard WordPress Media Library APIs rather than creating a custom upload system.

Once uploaded, the attachment ID is stored against the transaction for later verification.


Transaction Improvements

Several improvements were made to transaction handling.

The payment page now:

  • Retrieves transactions using the correct transaction ID
  • Reloads transactions after updates
  • Displays current payment information
  • Handles missing transactions gracefully

During development, a bug caused older transactions to appear because of confusion between multiple transaction records. This was resolved by ensuring that payment pages always retrieve the exact transaction referenced in the URL.


Debugging Improvements

Lesson 113 also included several reliability improvements.

These included fixing:

  • Object versus array access errors
  • Transaction retrieval bugs
  • Payment page rendering issues
  • Upload state refresh
  • Gateway display consistency

Additional logging was temporarily introduced during development to validate the payment workflow before being cleaned up.


Why This Architecture Matters

Although only Manual Payment is currently operational, the underlying architecture was designed for long-term extensibility.

Future payment providers can now plug into the same workflow without redesigning the payment page.

This makes it possible to introduce services such as Escrow.com, Stripe, PayPal, or cryptocurrency while keeping a consistent buyer experience.


Files Added

  • includes/class-external-provider-manager.php

Major Files Updated

  • includes/class-payment-page.php
  • includes/class-payment-manager.php
  • includes/class-transaction-manager.php
  • includes/class-database.php
  • includes/class-database-migration.php
  • flipnzee-auctions.php

What Comes Next

With the payment foundation complete, the next lesson will shift from adding functionality to improving architecture.

Lesson 114 will refactor the payment page into a state-driven workflow, allowing each payment stage—Pending, Submitted, Verified, and Completed—to present only the actions relevant to that stage. This will simplify future integrations with Escrow.com, admin verification, and automated ownership transfers.


Git Tag Recommendation

lesson-113-stable

I recommend tagging this release as lesson-113-stable. It represents the first complete payment workflow in Flipnzee Auctions and establishes the architecture that future payment providers and transfer features will build upon.

Building Flipnzee Auctions – Lesson 113 (Planning) – Implementing Escrow.com Support (Part 1)


Objective

In this lesson we’ll build the foundation for external transaction management.

Instead of trying to duplicate Escrow.com’s workflow, Flipnzee Auctions will simply track that an auction has entered an external transaction process.

This makes the plugin simpler, easier to maintain, and ready for future providers.


Philosophy

The plugin is responsible for:

✅ Auction

✅ Winner

✅ Transaction Record

✅ External Provider

✅ Completion Status

The plugin is not responsible for:

❌ collecting payment

❌ holding funds

❌ inspection

❌ disputes

❌ fee calculation

❌ releasing payment

Those remain the responsibility of the external transaction provider.


New Workflow

Auction Ends
        │
        ▼
Winner Selected
        │
        ▼
Create External Transaction
        │
        ▼
Transaction In Progress
        │
        ▼
Seller Receives Confirmation
        │
        ▼
Mark Transaction Completed
        │
        ▼
Auction Completed

Notice how much cleaner this is.


Database Changes

We’ll extend the existing transaction table.

New columns:

ColumnPurpose
providerEscrow.com
external_transaction_idTransaction reference
external_transaction_urlOptional link
statusIn Progress / Completed
started_atStarted date
completed_atCompletion date
notesInternal notes

No provider-specific columns.


Statuses

Instead of many workflow states we’ll begin with four.

Pending

↓

Initiated

↓

In Progress

↓

Completed

Simple.

Reliable.

Expandable.


Provider Architecture

Instead of

Escrow Manager

we’ll build

External Transaction

↓

Provider

↓

Escrow.com

Later we can support

Escrow.com

Escrow Europe

Sedo

Afternic

Dan.com

Manual Transfer

without changing the architecture.


Administration Screen

Each transaction will eventually contain something similar to:

Auction

Website.com

Winner

[email protected]

Provider

Escrow.com

External Transaction ID

E48329844

Started

21 July 2026

Status

In Progress

Notes

Buyer funded transaction.
Waiting for completion.

[Mark Completed]

Nothing more is needed.


Why We Aren’t Tracking Every Step

A common temptation is to mirror every stage of the escrow process.

For example:

Buyer Paid

↓

Funds Verified

↓

Seller Transfers

↓

Buyer Inspection

↓

Funds Released

Although these stages are useful within Escrow.com, they are not controlled by Flipnzee Auctions.

Attempting to reproduce them inside the plugin would require manual updates, duplicate information already maintained by the escrow provider, and increase the risk of inconsistencies.

Instead, Flipnzee Auctions records only what it can reliably know:

  • when an external transaction begins
  • which provider is being used
  • the provider’s transaction reference
  • whether the transaction is still in progress or has been completed

This keeps responsibilities clearly separated between the marketplace and the external escrow service.


Future API Integration

When we eventually integrate with the Escrow.com API, this design will remain unchanged.

Instead of an administrator manually updating the transaction status, the plugin will retrieve the latest information from the provider automatically.

Because the underlying architecture is provider-independent, future integrations with additional services will require minimal changes.


What We’ll Build in This Lesson

Rather than making isolated edits throughout the plugin, we’ll implement the feature as a cohesive unit.

The implementation will include:

  • Extending the transaction database schema with provider-independent fields.
  • Enhancing the Transaction Manager to create and manage external transaction records.
  • Updating the Payment Manager to recognise external providers.
  • Adding administrator controls for recording provider information, transaction references, and notes.
  • Displaying transaction progress within the existing administration interface.
  • Preparing the codebase for future API integration without introducing provider-specific dependencies.

Expected Result

After completing this lesson, a finished auction will be able to move into an external transaction workflow.

Administrators will be able to record the transaction provider, store the provider’s reference number, monitor whether the transaction is still in progress, and mark it as completed once the provider confirms that the sale has successfully concluded.

Although the financial transaction itself remains under the supervision of the external provider, Flipnzee Auctions will maintain an accurate record of every completed marketplace sale.


Git Commit

Lesson 113

Implement external transaction tracking

• extend transaction schema
• support external transaction providers
• add transaction references
• add transaction tracking
• prepare for Escrow.com integration

Before we write the code

I also want to make one additional architectural improvement, and I believe you’ll appreciate it.

At the moment, your plugin has Payment Manager and Transaction Manager. Once we introduce external transaction tracking, those responsibilities become distinct:

  • Payment Manager → Responsible for available payment methods (Escrow.com, Stripe, Manual, etc.).
  • Transaction Manager → Responsible for recording and managing the lifecycle of a completed auction transaction.

This separation follows the Single Responsibility Principle and will make future enhancements—such as API integrations or support for multiple providers—much easier to implement. Since we’re moving quickly toward a production-ready plugin, I recommend making this distinction now rather than after additional features have been added.