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.
