Lesson 75: Building the Payment Proof Upload System for Manual Payments

Introduction

In the previous lesson, we enhanced the payment page by providing buyers with professional manual payment instructions, including a unique payment reference number, payment amount, and important payment guidance.

However, after completing a bank transfer or manual payment, buyers still have no way to notify the marketplace that payment has been made.

In this lesson, we will begin building the Payment Proof Upload System. This feature will allow buyers to upload proof of payment directly from the payment page. Although the uploaded proof will not yet be reviewed automatically, this lesson lays the foundation for an administrative verification workflow that will be completed in later lessons.


Why This Feature Matters

For manual payments, marketplace administrators need evidence that payment has actually been made before transferring website ownership.

Typical proof includes:

  • Bank transfer receipt
  • UPI payment screenshot
  • NEFT/RTGS receipt
  • Wire transfer confirmation
  • Cryptocurrency transaction screenshot

Without an upload facility, buyers would need to send these documents through email, making transaction management much more difficult.


What We Will Build

By the end of this lesson, the payment page will include:

  • Upload Proof of Payment section
  • Secure file upload field
  • Support for common image and PDF formats
  • WordPress nonce protection
  • Submit Payment Proof button
  • Success confirmation message
  • Storage of uploaded proof using the WordPress Media Library
  • Transaction updated with the uploaded proof attachment ID

Learning Objectives

In this lesson you will learn how to:

  • Build secure upload forms in WordPress
  • Handle file uploads safely
  • Use WordPress Media Library programmatically
  • Associate uploaded files with marketplace transactions
  • Protect uploads using nonces
  • Validate uploaded file types
  • Store attachment IDs for later verification

Implementation Roadmap

Step 1

Create the Payment Proof Upload section.


Step 2

Build the upload form.


Step 3

Add WordPress nonce verification.


Step 4

Validate uploaded files.


Step 5

Upload payment proof to the Media Library.


Step 6

Store the attachment ID against the payment transaction.


Step 7

Display upload success confirmation.


Step 8

Prepare the workflow for administrator verification in the next lesson.


Expected Result

The payment page will evolve from this:

Payment Instructions

Reference Number

Amount

Status

Select Payment Method

into:

Payment Instructions

Reference Number

Amount

Status

Upload Payment Proof

Choose File

[ Upload Receipt ]

✓ Payment proof uploaded successfully.

Benefits

After completing this lesson, Flipnzee will gain:

  • A complete buyer payment submission workflow
  • Secure proof-of-payment uploads
  • Organized storage in the WordPress Media Library
  • Better transaction tracking
  • A foundation for admin payment verification
  • Reduced reliance on email communication

What Comes Next?

In Lesson 76, we will build the Administrator Payment Verification Dashboard, allowing administrators to review uploaded payment proofs, approve or reject payments, update transaction statuses, and continue the website ownership transfer workflow. This will complete the first end-to-end manual payment verification cycle within Flipnzee.

Lesson 74 Implementation: Displaying Professional Manual Payment Instructions on the Payment Page

After completing the payment gateway selection workflow in the previous lessons, the next improvement was making the payment page more informative for buyers who choose Manual Payment.

Previously, selecting Manual Payment only displayed a simple confirmation message. In this lesson, the payment page was enhanced to show a professional payment instruction section containing a unique payment reference, payment amount, current status, and important guidance for the buyer.


What We Built

The payment page now displays a dedicated Payment Instructions section whenever the buyer selects Manual Payment.

The section includes:

  • Unique payment reference number
  • Winning bid amount
  • Current payment status
  • Important payment instructions
  • Existing transaction details remain visible below

This provides buyers with the information they need before sending payment.


Step 1 – Detect Manual Payment Selection

After validating the form submission and selected gateway, the payment page checks which payment method the buyer selected.

switch ( $selected_gateway ) {

    case 'manual':

        // Display manual payment instructions.

        break;

    default:

        // Unsupported gateway.

        break;
}

This structure prepares the plugin for adding more gateways like Escrow.com, Stripe, PayPal and USDT in future lessons.


Step 2 – Create the Manual Payment Instruction Section

Inside the Manual Payment case, a dedicated container was added.

<div class="flipnzee-manual-payment">

    <h3>Payment Instructions</h3>

    <p>
        Thank you for choosing Manual Payment.
    </p>

    <p>
        Please use the transaction reference below when sending your payment.
    </p>

</div>

This creates a clear visual separation between payment instructions and transaction information.


Step 3 – Generate a Unique Payment Reference

Instead of using only the transaction ID, a formatted payment reference was generated.

<?php

echo esc_html(

    'FLIP-' . str_pad(

        $transaction->id,

        6,

        '0',

        STR_PAD_LEFT

    )

);

?>

Example:

FLIP-000001

Using a formatted reference looks much more professional and is easier for buyers to include in payment notes.


Step 4 – Display Important Payment Information

A table was created to display the essential payment information.

<table class="widefat striped">

<tr>

    <th>Reference Number</th>

    <td>

        <?php

        echo esc_html(
            'FLIP-' . str_pad(
                $transaction->id,
                6,
                '0',
                STR_PAD_LEFT
            )
        );

        ?>

    </td>

</tr>

<tr>

    <th>Amount</th>

    <td>

        <?php

        echo esc_html(
            number_format_i18n(
                $transaction->winning_bid,
                2
            )
        );

        ?>

    </td>

</tr>

<tr>

    <th>Status</th>

    <td>

        Awaiting Payment

    </td>

</tr>

</table>

This gives buyers an organized summary before making payment.


Step 5 – Add Important Buyer Instructions

An instruction list was added below the payment summary.

<h4>Important</h4>

<ul>

    <li>
        Include the reference number with your payment.
    </li>

    <li>
        Keep proof of payment for verification.
    </li>

    <li>
        Your transaction will be reviewed before ownership transfer.
    </li>

</ul>

These reminders help reduce payment mistakes and prepare buyers for the verification process.


Final Result

After selecting Manual Payment, buyers now see:

  • Professional payment instruction heading
  • Payment reference number
  • Winning amount
  • Awaiting payment status
  • Important payment reminders
  • Original transaction details below

The payment page now feels much closer to a production-ready marketplace instead of a placeholder page.


What I Learned

This lesson demonstrated that payment pages should do much more than simply display transaction details. Buyers need clear instructions, a recognizable payment reference, and confirmation of the amount and status before making payment.

Generating a formatted reference number and presenting information in a structured table significantly improves usability and prepares the payment workflow for future enhancements.

Download Source Code

Download the starting version of the plugin before the lesson:

⬇ Download Plugin (After Lesson 73) (0 downloads )

Download the completed version after this lesson:

⬇ Download Plugin (After Lesson 74) (0 downloads )


What’s Next?

In Lesson 75, we will build the Payment Proof Upload feature, allowing buyers to submit proof of payment after completing a manual transfer. This will move the Flipnzee payment workflow one step closer to a complete marketplace transaction process.

Lesson 74: Manual Payment Instructions and Buyer Confirmation Workflow

Introduction

With the payment gateway routing architecture completed in the previous lessons, buyers can now securely select their preferred payment method. However, selecting Manual Payment currently only displays a placeholder message.

In this lesson, we’ll implement the first real payment workflow in Flipnzee Auctions by displaying manual payment instructions after the buyer selects the Manual Payment gateway.

Rather than integrating a live payment processor immediately, we’ll build a professional workflow that guides buyers through the payment process while preparing the plugin for future automation.


What We’ll Build

After selecting Manual Payment and clicking Continue to Payment, the buyer will see:

  • A payment confirmation notice
  • Transaction reference number
  • Amount to be paid
  • Payment instructions
  • Placeholder bank/account details
  • Buyer checklist
  • “I’ve Completed Payment” button
  • Architecture ready for payment verification in future lessons

Why This Matters

Many marketplace platforms begin with manual payments before integrating payment gateways.

This approach allows:

  • Faster marketplace launch
  • Manual verification by administrators
  • Easy transition to automated gateways later
  • Reusable payment workflow

The same workflow will later support:

  • Escrow.com
  • Stripe
  • PayPal
  • Razorpay
  • USDT Cryptocurrency

Learning Objectives

By the end of this lesson you will:

  • Display professional payment instructions
  • Generate a transaction reference for buyers
  • Show payment amount clearly
  • Build a buyer payment confirmation interface
  • Prepare the plugin for payment verification
  • Create a reusable payment workflow

Planned User Experience

Instead of seeing only:

Manual Payment selected.

The buyer will see something similar to:

Manual Payment

Transaction Reference:
FLIP-000001

Amount:
₹55,555,609.00

Payment Instructions

✓ Transfer the exact amount.

✓ Use the reference number.

✓ Keep your payment receipt.

✓ Click "I've Completed Payment" after payment.

[ I've Completed Payment ]

What We’ll Implement

Step 1

Replace the temporary success message with a real payment instruction section.


Step 2

Generate a payment reference number using the transaction ID.

Example:

FLIP-000001

Step 3

Display the winning bid amount prominently.


Step 4

Display manual payment instructions.


Step 5

Add a buyer checklist before payment.


Step 6

Add an I’ve Completed Payment button.

Initially this button will not update the database.

It simply prepares the workflow for the next lesson.


Files We’ll Modify

Primary file:

includes/class-payment-page.php

Possible future updates:

includes/class-payment-manager.php

Skills You’ll Learn

  • Building multi-step payment workflows
  • Creating reusable payment interfaces
  • Improving user experience
  • Structuring payment pages
  • Preparing for payment verification
  • Designing scalable payment architecture

Expected Result

By the end of Lesson 74, buyers will experience a much more realistic payment process instead of a placeholder message. They’ll receive clear payment instructions, a unique transaction reference, the payment amount, and a confirmation button that prepares the marketplace for the payment verification workflow introduced in the next lesson.


Coming Next

Lesson 75: Recording Buyer Payment Confirmation and Updating Transaction Status

In the next lesson, clicking I’ve Completed Payment will begin updating the transaction status (for example, to Awaiting Verification) and lay the groundwork for seller/admin payment verification.

Lesson 73: Capturing and Validating the Buyer’s Selected Payment Method

Objective

In the previous lesson, we introduced a dynamic payment gateway selection interface. Buyers can now see the available payment methods, but their selection is not yet processed.

In this lesson, we’ll begin building the actual checkout workflow by wrapping the gateway list inside a form, capturing the selected payment method, validating it on submission, and preparing the plugin for gateway-specific payment processing.

Although real payment gateways are still not connected, this lesson establishes the core workflow that every future payment provider will use.


Why This Lesson Matters

A payment page is only useful if it can process the buyer’s choice.

Instead of immediately integrating Stripe, PayPal, or Escrow.com APIs, we first need a common checkout workflow that:

  • accepts the selected gateway
  • validates user input
  • prevents invalid gateway selections
  • prepares the transaction for payment
  • redirects to the appropriate payment handler

Once this workflow exists, every new payment provider can plug into it.


What We’ll Build

The payment page will evolve from:

○ Escrow.com
● Manual Payment
○ Stripe
○ PayPal

[Continue (Disabled)]

into:

○ Escrow.com
● Manual Payment
○ Stripe
○ PayPal

[Continue to Payment]

When the buyer clicks the button:

  1. The selected gateway is submitted.
  2. The selection is validated.
  3. Disabled gateways cannot be submitted.
  4. Manual Payment continues to the next step.
  5. Future gateways display an informative placeholder message.

Files We’ll Modify

Existing

includes/class-payment-page.php

Existing

includes/class-payment-manager.php

Features to Implement

1. Wrap Gateway Selection Inside a Form

Convert the payment gateway section into a proper HTML form.

The form will submit the selected gateway using the POST method.


2. Enable the Continue Button

Replace the disabled placeholder button with an active submit button.

Example:

Continue to Payment

3. Capture Buyer Selection

Read the submitted gateway using:

$_POST['payment_gateway']

Sanitize the value before processing.


4. Validate the Selected Gateway

Verify that:

  • the gateway exists
  • the gateway is currently enabled

If validation fails, display a user-friendly error message.


5. Prepare Gateway Routing

Rather than processing payments directly, create routing logic similar to:

if Manual Payment
    continue to manual payment workflow

if Escrow
    placeholder

if Stripe
    placeholder

if PayPal
    placeholder

This architecture allows future lessons to implement each gateway independently.


User Experience

Current:

Choose Gateway

Manual Payment

Continue (disabled)

After Lesson 73:

Choose Gateway

Manual Payment

Continue to Payment

Upon submission:

Selected Gateway:
Manual Payment

or

Escrow.com integration is coming soon.

depending on the selected gateway.


Architecture Improvement

Before Lesson 73:

Payment Page

↓

Display Gateways

After Lesson 73:

Payment Page

↓

Capture Form

↓

Validate Gateway

↓

Route to Selected Payment Method

↓

Future Gateway Handler

This creates a reusable payment flow that every payment provider will follow.


Benefits

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

  • Functional payment selection form
  • Gateway validation
  • Secure handling of buyer input
  • Centralized routing logic
  • Foundation for integrating Escrow.com, Stripe, PayPal, Razorpay, and cryptocurrency payments

What We Won’t Build Yet

To keep the implementation stable, we are not implementing:

  • Escrow.com API
  • Stripe Checkout
  • PayPal Checkout
  • Razorpay API
  • Cryptocurrency payments
  • Payment confirmation
  • Webhooks
  • Automatic transaction updates

Those will be introduced in future lessons after the payment workflow has been completed.


Expected Outcome

By the end of Lesson 73, the Payment page will evolve from a static gateway selection interface into the first stage of a real checkout process. Buyers will be able to submit their chosen payment method, the plugin will validate the selection securely, and the architecture will be ready to hand control to the appropriate payment gateway implementation in future lessons.

Lesson 72: Building the Payment Gateway Selection Interface

Objective

With the payment architecture now prepared, the next logical step is to give buyers the ability to choose how they would like to pay.

In this lesson, we will introduce a Payment Method Selection section on the Payment page. Although only a placeholder gateway exists today, the interface will be built so future gateways (Stripe, PayPal, Razorpay, Bank Transfer, Crypto, etc.) can be added with almost no changes to the frontend.

This lesson focuses entirely on UI architecture, not actual payment processing.


What We’ll Build

Instead of only showing:

Payment Gateway
Manual Payment (Coming Soon)

the payment page will display something like:

Select Payment Method

(•) Manual Payment (Coming Soon)
( ) Stripe
( ) PayPal
( ) Razorpay
( ) Cryptocurrency (USDT)

[Continue]

Only Manual Payment will be enabled.

The remaining gateways will appear disabled with a “Coming Soon” label.


Why This Lesson Matters

This is an important architectural step because:

  • separates payment UI from payment logic
  • allows new gateways without redesigning pages
  • provides a familiar checkout experience
  • keeps the plugin scalable
  • prepares for future gateway plugins

Files We’ll Modify

Existing

includes/class-payment-page.php

Existing

includes/class-payment-manager.php

(add helper function for available gateways)


New Features

1. Payment Gateway List

Create a helper such as:

Flipnzee_Payment_Manager::get_available_gateways()

which returns an array like

array(
    'manual' => array(
        'label' => 'Manual Payment',
        'enabled' => true,
    ),
    'stripe' => array(
        'label' => 'Stripe',
        'enabled' => false,
    ),
    'paypal' => array(
        'label' => 'PayPal',
        'enabled' => false,
    ),
    'razorpay' => array(
        'label' => 'Razorpay',
        'enabled' => false,
    ),
    'crypto' => array(
        'label' => 'USDT Cryptocurrency',
        'enabled' => false,
    ),
);

2. Display Gateway Choices

Show all gateways as radio buttons.

Only enabled gateways are selectable.

Disabled gateways display:

Coming Soon

3. Continue Button

Display

Continue to Payment

No payment processing yet.


4. Clean HTML Structure

Wrap the section in

<div class="flipnzee-payment-gateways">

for future styling.


User Experience

Current page:

Transaction Details

Gateway:
Manual Payment

New page:

Transaction Details

Select Payment Method

○ Stripe
○ PayPal
● Manual Payment
○ Razorpay
○ Crypto

Continue

Benefits

After this lesson the plugin will have:

  • scalable payment architecture
  • configurable gateway list
  • reusable gateway rendering
  • future-ready checkout interface
  • no dependency on a specific payment provider

What We Won’t Build Yet

To keep the project stable, we are not implementing:

  • Stripe API
  • PayPal API
  • Razorpay API
  • Crypto payments
  • Order confirmation
  • Payment verification

Those will come in later lessons.


Expected Outcome

By the end of Lesson 72, buyers will see a professional payment method selection interface with a working placeholder for Manual Payment and clearly marked future payment options, laying the foundation for integrating real payment gateways in the upcoming lessons.

Lesson 71 Implementation: Introducing the Payment Manager for Transaction Validation

After successfully creating the buyer payment page in the previous lesson, the next logical improvement was to separate payment-related business logic from the presentation layer. Instead of allowing the payment page to directly decide whether a transaction could be paid, a dedicated Payment Manager class was introduced.

This lesson focuses on improving the plugin architecture while preparing the foundation for future payment gateway integrations such as Stripe, PayPal, Razorpay, or manual bank transfer.


Objective

The goals of this lesson were to:

  • Create a dedicated Flipnzee_Payment_Manager class.
  • Centralize payment validation logic.
  • Validate transactions before displaying the payment page.
  • Prepare a placeholder method for future payment gateway integrations.
  • Keep the payment page clean and easier to maintain.

Why This Refactoring Was Needed

In Lesson 70, the payment page displayed transaction details directly after fetching the transaction.

As more features are added, such as:

  • payment expiry
  • completed payments
  • cancelled transactions
  • multiple payment gateways

placing all validation logic inside the page would quickly become difficult to maintain.

Instead, all payment-related decisions should live inside a dedicated manager.

This follows the Single Responsibility Principle, where each class has one clear responsibility.


Step 1 — Creating the Payment Manager

A new file was created:

includes/class-payment-manager.php

The initial class structure:

<?php

if ( ! defined( 'ABSPATH' ) ) {
    exit;
}

class Flipnzee_Payment_Manager {

}

This class will eventually become the central place for everything related to buyer payments.


Step 2 — Registering the New Class

The loader was updated so WordPress loads the new class automatically.

Example:

require_once FLIPNZEE_AUCTIONS_PLUGIN_DIR . 'includes/class-payment-manager.php';

Step 3 — Moving Validation into the Manager

Instead of checking the transaction status directly inside the payment page, a reusable validation method was created.

public static function can_pay( $transaction ) {

    if ( ! $transaction ) {
        return false;
    }

    if ( strtolower( trim( $transaction->status ) ) !== 'pending' ) {
        return false;
    }

    return true;
}

Why strtolower()?

During testing, it was discovered that database values may use different capitalization.

Examples:

Pending
pending
PENDING

Using:

strtolower( trim( $transaction->status ) )

ensures all of these are treated consistently.


Step 4 — Validating the Transaction

The payment page now retrieves the transaction:

$transaction = Flipnzee_Payment_Manager::get_transaction(
    $transaction_id
);

If nothing is found:

if ( ! $transaction ) {
    return '<p>Transaction not found.</p>';
}

Then the Payment Manager determines whether payment is still allowed.

if ( ! Flipnzee_Payment_Manager::can_pay( $transaction ) ) {
    return '<p>This transaction is no longer available for payment.</p>';
}

This keeps the page itself very clean.


Step 5 — Preparing Gateway Support

Since payment gateways will be implemented in future lessons, a placeholder method was added.

public static function get_gateway_name( $transaction ) {

    return 'Manual Payment (Coming Soon)';
}

The payment page simply calls:

echo esc_html(
    Flipnzee_Payment_Manager::get_gateway_name( $transaction )
);

Later, this method will automatically return:

  • Manual Bank Transfer
  • Stripe
  • Razorpay
  • PayPal

without changing the payment page.


Debugging Along the Way

During implementation, a few useful issues were discovered.

1. Transaction Status Case Sensitivity

Initially the validation checked:

$transaction->status !== 'Pending'

However, the database stored:

pending

As a result, every payment was incorrectly rejected.

The validation was updated to:

strtolower( trim( $transaction->status ) ) !== 'pending'

making it much more reliable.


2. Missing Payment Gateway Column

An attempt was made to display:

$transaction->payment_gateway

This produced an undefined property warning because the database table does not yet contain a payment_gateway column.

Instead of adding a temporary workaround, the gateway display was moved into:

Flipnzee_Payment_Manager::get_gateway_name()

which currently returns a placeholder while the database schema is prepared in a future lesson.


Testing

Several scenarios were tested.

✅ Existing transaction loads correctly.

✅ Pending transaction is accepted.

✅ Invalid transaction ID displays:

Transaction not found.

✅ Placeholder payment gateway displays:

Manual Payment (Coming Soon)

No PHP warnings remain.


Final Result

The payment page now displays:

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

with validation handled entirely by the Payment Manager.

The interface remains clean while the underlying architecture becomes much more maintainable.

Download Source Code

Download the starting version of the plugin before the lesson:

⬇ Download Plugin (After Lesson 70) (1 download )

Download the completed version after this lesson:

⬇ Download Plugin (After Lesson 71) (0 downloads )


What Was Learned

This lesson demonstrated the value of separating business logic from presentation.

Instead of embedding validation throughout the payment page, all payment-related decisions are now centralized in a dedicated manager. This approach makes the code easier to read, easier to test, and far simpler to extend as new payment gateways and payment workflows are introduced.

It also highlighted the importance of real-world debugging—such as handling inconsistent database values (e.g., Pending vs. pending) and recognizing when a database schema needs to evolve rather than patching around missing fields.

With the Flipnzee_Payment_Manager now in place, the plugin has a solid foundation for implementing gateway-specific payment processing in upcoming lessons while keeping the payment page itself clean and focused.

Lesson 70: Building the Payment Page Foundation for Completed Auctions


Introduction

After successfully completing the auction lifecycle in the previous lessons, the next logical step is to allow auction winners to complete their purchase.

By the end of Lesson 69, Flipnzee Auctions was already capable of:

  • Creating and managing auctions
  • Automatically closing expired auctions
  • Determining the winning bidder
  • Recording transactions
  • Displaying transactions in the WordPress admin
  • Showing buyers their purchases
  • Displaying purchase details
  • Providing a Pay Now button for unpaid purchases

Although the Pay Now button existed, clicking it resulted in a 404 Page Not Found error because the payment page itself had not yet been implemented.

Lesson 70 focuses on solving this problem by creating the foundation of the payment workflow.


Why This Lesson Is Important

Every online marketplace requires a secure payment flow after an auction ends.

Instead of jumping directly into integrating a payment gateway like Stripe or PayPal, it is better to build the underlying architecture first.

This lesson concentrates on creating the page that receives the transaction, validates it, and displays the purchase before any actual payment processing takes place.

Building the foundation first makes later gateway integration much cleaner and easier.


Objectives

In this lesson we will:

  • Create the Payment Page shortcode
  • Build a dedicated Payment Page class
  • Register the shortcode with the plugin loader
  • Display transaction information
  • Validate transaction IDs
  • Handle missing or invalid transactions gracefully
  • Prepare the page for future payment gateway integration

Planned Workflow

To keep development safe and manageable, this lesson will be completed in several small checkpoints.

Checkpoint 1

Create the Payment Page class.


Checkpoint 2

Register the payment shortcode.


Checkpoint 3

Display transaction information.


Checkpoint 4

Handle invalid transactions.


Checkpoint 5

Test the page using existing auction transactions.


Checkpoint 6

Commit the completed lesson to Git.


Expected User Flow

Auction Ends
        │
        ▼
Winner Determined
        │
        ▼
Transaction Created
        │
        ▼
Buyer Visits "My Purchases"
        │
        ▼
Clicks "Pay Now"
        │
        ▼
Payment Page Opens
        │
        ▼
Transaction Validated
        │
        ▼
Ready for Payment Gateway

Development Strategy

One important improvement in our workflow is the use of small Git checkpoints.

At the beginning of this lesson, the entire project was restored to the stable Lesson 69 state and committed to GitHub. This provides a reliable rollback point before introducing the payment workflow.

Rather than implementing the complete payment system in one attempt, each stage will be developed, tested, and committed separately. This incremental approach reduces risk, simplifies debugging, and ensures that any issues can be isolated without affecting previously completed features.


What We’ll Build Next

By the end of Lesson 70, clicking the Pay Now button should no longer produce a 404 error. Instead, buyers will be taken to a dedicated payment page displaying the transaction details, confirming the amount due, and preparing the auction purchase for payment processing in the upcoming lessons.


Next Lesson: Implementing the Payment Page and Connecting the “Pay Now” Workflow.