Lesson 127: Implementing Escrow Connection Testing & API Client Integration

As the Flipnzee Auctions plugin evolves, the Escrow integration is beginning to take shape beyond simple configuration screens. In the previous lesson, an Escrow Settings page was introduced to allow administrators to configure the environment and credentials. While those settings could be saved successfully, there was still no practical way to verify that the configuration was actually usable.

In this lesson, the plugin gains its first end-to-end Escrow connection testing workflow. Although the implementation still operates in simulation mode, the architecture now closely resembles what will eventually be used for communicating with the live Escrow.com API.


Lesson Objectives

By the end of this lesson, the plugin can:

  • Save Escrow configuration securely.
  • Load Escrow settings from WordPress options.
  • Initialize the Escrow API Client using saved configuration.
  • Test the configured connection directly from the admin interface.
  • Display administrator-friendly success messages.
  • Prepare the plugin architecture for future live API requests.

Reviewing the Existing Architecture

Before adding new functionality, the existing components were reviewed.

The project already contained:

  • Escrow Settings administration page
  • Escrow API Client
  • External Provider Manager
  • Escrow Provider abstraction

Rather than creating another isolated implementation, the new functionality was integrated into these existing components.

This keeps responsibilities well separated.

Admin Page
        │
        ▼
Escrow API Client
        │
        ▼
Simulation / Sandbox / Production

Extending the Escrow API Client

The Escrow API Client was refactored to load configuration directly from the plugin settings.

During construction it now retrieves:

$this->settings = get_option(
    'flipnzee_escrow_settings',
    array()
);

Instead of relying on hardcoded values, the client now determines its behaviour from administrator-configured settings.


Environment Detection

A dedicated helper method was introduced:

public function get_environment()

This method returns one of:

simulation
sandbox
production

Centralising this logic makes the remainder of the API client significantly cleaner.

Instead of repeatedly checking options throughout the codebase, every component can simply ask:

$environment = $this->get_environment();

Refactoring Connection Testing

The previous implementation contained duplicate connection testing methods.

These were consolidated into a single implementation capable of handling every supported environment.

The method now returns responses similar to:

return array(
    'success' => true,
    'message' => 'Simulation mode active.',
);

Future lessons will replace these simulated responses with real HTTP requests while preserving the same interface.


Connecting the Admin Page

The Escrow Settings page was updated with a dedicated button:

Test Escrow Connection

Instead of simply saving settings, administrators can now immediately verify the configured environment.

Internally the workflow is:

Administrator

↓

Escrow Settings Page

↓

test_connection()

↓

Flipnzee_Escrow_API_Client

↓

Connection Result

↓

WordPress Admin Notice

This provides immediate feedback without requiring administrators to inspect debug logs.


WordPress Admin Notices

Rather than printing raw output, the implementation uses the native WordPress Settings API.

Successful tests generate notices using:

add_settings_error()

which are displayed through:

settings_errors()

This approach provides a familiar user experience consistent with WordPress core.


Security Improvements

The lesson also improves request handling.

Both actions now verify WordPress nonces before processing:

  • Save Settings
  • Test Connection

This prevents unauthorised requests while maintaining a clean administration workflow.


Eliminating Duplicate Logic

During development several issues surfaced, including:

  • duplicate connection testing methods
  • misplaced class methods
  • syntax errors
  • missing settings
  • undefined array warnings

Rather than working around these problems, the implementation was simplified by removing duplicate logic and ensuring every responsibility existed in only one location.

This makes the code easier to understand and maintain.


Testing the Workflow

After implementation, the complete workflow was verified.

Saving configuration now stores:

  • Environment
  • Sandbox Email
  • Sandbox API Key
  • Debug Logging preference

Selecting Simulation and pressing Test Escrow Connection now produces a successful administrator notice:

Simulation mode active.

This confirms that the complete execution path is functioning correctly.


Current Architecture

Escrow Settings

        │

        ▼

Save Configuration

        │

        ▼

WordPress Options

        │

        ▼

Escrow API Client

        │

        ▼

Simulation Environment

        │

        ▼

WordPress Success Notice

Although the implementation currently simulates API responses, every major architectural component required for live communication is now in place.


Lessons Learned

Several valuable engineering principles emerged during this lesson.

  • Build reusable components before integrating external services.
  • Keep configuration separate from business logic.
  • Prefer one well-designed implementation over multiple similar methods.
  • Leverage WordPress APIs instead of building custom administration workflows.
  • Test complete workflows, not just individual functions.

Looking Ahead

With a functioning Escrow configuration system and connection testing workflow now complete, the project is ready to move beyond simulation.

The next lesson will begin replacing simulated responses with actual requests to the Escrow.com REST API using WordPress HTTP functions, allowing the plugin to communicate with external services while preserving the architecture established in this lesson.


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

Lesson 127 — Testing the Escrow API Connection

Introduction

In the previous lesson, we implemented a dedicated Escrow Settings administration page, allowing administrators to securely configure the plugin without modifying source code. Those settings now provide the foundation for interacting with the Escrow.com API.

However, before the plugin can create transactions or manage escrow payments, it is important to verify that the supplied credentials are valid and that communication with the selected environment is functioning correctly.

In this lesson, we will implement a Test Escrow Connection feature that allows administrators to verify connectivity directly from the WordPress dashboard.


Why Test the Connection?

Many integration problems occur long before the first API request is made.

Examples include:

  • Incorrect API credentials
  • Wrong environment selected
  • Network connectivity issues
  • Invalid API endpoints
  • Authentication failures

Rather than discovering these problems during a live auction, administrators should be able to verify their configuration beforehand.


Lesson Objectives

By the end of this lesson, the plugin will:

  • Add a Test Escrow Connection button.
  • Read configuration from the Escrow Settings page.
  • Initialize the Escrow API Client.
  • Determine the selected environment.
  • Attempt a connection.
  • Display the connection result to the administrator.
  • Record diagnostic information when debug logging is enabled.

Current Architecture

The plugin currently looks like this:

Administrator
        │
        ▼
Escrow Settings Page
        │
        ▼
WordPress Options API
        │
        ▼
Escrow API Client

This lesson extends the final stage by allowing the administrator to verify that communication with Escrow.com is working.


Reading Stored Configuration

The API client should no longer rely on hard-coded values.

Instead, it should retrieve configuration from the settings saved in Lesson 126.

Typical values include:

  • Environment
  • Sandbox Email
  • Sandbox API Key
  • Production Email
  • Production API Key
  • Debug Logging

This keeps the plugin flexible and makes switching environments as simple as changing a dropdown selection.


Initializing the API Client

The Test Connection action will instantiate the existing Flipnzee_Escrow_API_Client and configure it using the stored settings.

The client should automatically determine which endpoint to use based on the selected environment.

For example:

  • Simulation
  • Sandbox
  • Production

Keeping this logic inside the API client avoids duplicating environment selection throughout the plugin.


Simulation Mode

During development, many developers may not yet have Sandbox credentials.

To support plugin development, the existing Simulation mode remains useful.

Instead of making an external HTTP request, the plugin simply returns a simulated successful response.

Example:

✓ Simulation Mode Active

No external API request was performed.

This allows developers to continue building other parts of the plugin without depending on a live service.


Sandbox Connection

When Sandbox mode is selected, the plugin should:

  1. Validate the stored credentials.
  2. Build the appropriate request.
  3. Contact the Escrow Sandbox endpoint.
  4. Capture the response.
  5. Report the outcome.

A successful response confirms that the configuration is ready for development and testing.


Production Connection

Production mode follows the same workflow but communicates with the live Escrow.com environment.

Because Production interacts with live services, administrators should verify that:

  • Correct credentials are being used.
  • The intended environment is selected.
  • Debug logging is configured appropriately.

No financial transaction should be created during the connection test.

The purpose is only to confirm connectivity and authentication.


Displaying Results

After testing the connection, the administration page should present a clear status message.

Examples include:

Successful:

✓ Connected successfully.

Environment:
Sandbox

API Version:
Available

Authentication:
Successful

Simulation:

✓ Simulation Mode Active

No remote connection required.

Failure:

Connection Failed

Reason:
Authentication failed.

Please verify your API credentials.

Providing meaningful feedback helps administrators diagnose configuration issues without consulting server logs.


Debug Logging

If Debug Logging is enabled, the plugin should record useful diagnostic information.

Examples include:

  • Environment selected
  • Endpoint used
  • Request start time
  • Response received
  • HTTP status code
  • Error messages

Sensitive information such as API keys or passwords should never be written to logs.


Error Handling

External services are not always available.

The implementation should gracefully handle situations such as:

  • Invalid credentials
  • HTTP errors
  • Timeout exceptions
  • SSL problems
  • Unexpected API responses

Administrators should receive clear messages while detailed diagnostics remain available through debug logging.


Security Considerations

The Test Connection action should follow the same security practices established in previous lessons.

This includes:

  • WordPress nonce verification
  • Administrator capability checks
  • Sanitized user input
  • Escaped output
  • No exposure of API secrets

Maintaining consistent security practices is essential when interacting with third-party services.


Expected Workflow

Administrator
      │
      ▼
Clicks Test Connection
      │
      ▼
Load Saved Settings
      │
      ▼
Initialize API Client
      │
      ▼
Select Environment
      │
      ▼
Attempt Connection
      │
      ▼
Receive Response
      │
      ▼
Display Status Message
      │
      ▼
Optional Debug Log

Files Likely to be Updated

admin/class-admin-escrow-settings.php

includes/class-escrow-api-client.php

includes/class-logger.php (if required)

The exact implementation may vary, but the objective is to keep responsibilities clearly separated while reusing the API client introduced in earlier lessons.


What You’ll Learn

This lesson introduces several practical concepts commonly found in production WordPress plugins:

  • Testing third-party API connectivity.
  • Reading configuration from the WordPress Options API.
  • Environment-aware application design.
  • Graceful error handling.
  • Diagnostic logging.
  • Secure administrator actions.
  • Integrating existing classes rather than duplicating functionality.

These patterns are applicable to many WordPress integrations beyond Escrow.com.


Conclusion

With a dedicated settings page now in place, the next logical step is to verify that the plugin can successfully communicate with the configured Escrow environment. Implementing a Test Connection feature provides administrators with immediate feedback, reduces configuration errors, and lays the groundwork for future features such as transaction creation, status synchronization, and payment management.

In the next implementation lesson, we will build the Test Escrow Connection feature and connect it to the Flipnzee_Escrow_API_Client, completing the first end-to-end interaction between the plugin and the configured Escrow environment.

Lesson 126 Implementation — Building the Escrow Settings Administration Page

In the previous lesson, we created the foundation for communicating with Escrow.com by introducing a dedicated API client. Before that client can establish a connection, however, the plugin needs a secure and flexible way to store configuration details.

In this lesson, we implement a dedicated Escrow Settings administration page. This page allows administrators to configure the plugin without editing source code and prepares the foundation for Sandbox and Production integrations in future lessons.


Why This Lesson Is Important

One of the hallmarks of a well-designed WordPress plugin is that it separates configuration from application logic. Rather than embedding credentials directly in PHP files, configuration should be managed through the WordPress administration interface.

This approach offers several benefits:

  • Better security
  • Easier maintenance
  • Environment flexibility
  • Cleaner codebase
  • Improved user experience

It also makes the plugin suitable for deployment across multiple websites without requiring code modifications.


Objectives

By the end of this lesson, the plugin will:

  • Add an Escrow Settings page to the WordPress admin area.
  • Store configuration using the WordPress Options API.
  • Support multiple operating environments.
  • Allow Sandbox credentials to be managed from the dashboard.
  • Enable or disable debug logging.
  • Protect settings using WordPress nonce verification.

Creating the Administration Class

A new class was introduced to encapsulate all Escrow configuration functionality.

admin/
└── class-admin-escrow-settings.php

Instead of placing settings inside the main administration class, a dedicated class was created to keep responsibilities focused and improve maintainability.

The class is responsible for:

  • Rendering the settings page
  • Loading stored configuration
  • Saving administrator changes
  • Displaying the configuration interface

Loading the Class

The new class was registered during plugin initialization.

The plugin bootstrap now loads the class before it is referenced by the administration menu.

This small but essential step ensures that WordPress can instantiate the settings page without encountering class loading errors.


Registering the Menu

A new submenu was added beneath the existing Flipnzee Auctions menu.

Flipnzee Auctions
    ├── Dashboard
    ├── Auctions
    ├── Payments
    └── Escrow Settings

Keeping the page within the existing administration structure provides a familiar experience for administrators.


Building the User Interface

The page follows standard WordPress administration conventions using a familiar settings table layout.

The current interface includes:

  • Environment selector
  • Sandbox Email
  • Sandbox API Key
  • Debug Logging option
  • Save Settings button

Following WordPress UI conventions ensures the page feels consistent with the rest of the dashboard.


Supporting Multiple Environments

Different deployment stages require different Escrow environments.

The plugin now supports:

EnvironmentPurpose
SimulationInternal testing without contacting Escrow.com
SandboxEscrow.com’s testing environment
ProductionLive transactions

During development, Simulation mode allows the rest of the plugin to be implemented without relying on external API availability.


Saving Configuration

Instead of creating a custom database table, this lesson uses the WordPress Options API.

Configuration is stored under a single option, allowing WordPress to handle serialization and retrieval automatically.

The implementation uses:

  • get_option()
  • update_option()
  • wp_parse_args()

This keeps the code concise while remaining fully compatible with WordPress standards.


Security

Administrative settings should never trust submitted data.

The implementation therefore includes several important security measures.

Nonce Verification

Every settings submission includes a WordPress nonce to protect against Cross-Site Request Forgery (CSRF).

Sanitization

Submitted values are sanitized before storage.

Examples include:

  • sanitize_email()
  • sanitize_text_field()

Escaping Output

Values displayed back to administrators are escaped before rendering to prevent unintended HTML output.

These practices are fundamental to secure WordPress plugin development.


Object-Oriented Structure

The settings page follows the same object-oriented design used throughout the Flipnzee Auctions plugin.

Flipnzee_Admin_Escrow_Settings
│
├── render_page()
├── save_settings()
└── get_settings()

Each method performs a single responsibility, making the class easier to understand, test, and extend.


Debugging During Development

While implementing the feature, a few issues were encountered and resolved.

These included:

  • Missing class loading during plugin initialization.
  • Callback registration errors.
  • Admin page rendering failures.
  • Validation of plugin bootstrap order.
  • Incremental rebuilding of the settings page after isolating the source of a critical error.

Although these issues were temporary, resolving them improved the plugin’s architecture and highlighted the importance of testing each component as it is introduced.


Testing

The completed implementation was tested to verify that:

  • The Escrow Settings page loads successfully.
  • The submenu appears correctly.
  • Settings can be saved.
  • Stored values persist after page refresh.
  • The selected environment is retained.
  • Sandbox credentials are stored correctly.
  • Debug logging preferences are preserved.
  • WordPress nonce protection functions as expected.

Integration with Previous Lessons

The plugin architecture now looks like this:

Flipnzee_Admin_Escrow_Settings
            │
            ▼
 WordPress Options API
            │
            ▼
 Escrow Configuration
            │
            ▼
Flipnzee_Escrow_API_Client

Future API requests will retrieve configuration directly from these stored settings instead of relying on hard-coded values.


Files Added and Updated

admin/
└── class-admin-escrow-settings.php

admin/
└── class-admin.php

flipnzee-auctions.php

These changes establish the administrative infrastructure required for future Escrow integration.


What We Learned

This lesson demonstrated several important WordPress development concepts:

  • Creating dedicated administration classes.
  • Registering custom admin menus.
  • Using the WordPress Options API.
  • Designing secure administration forms.
  • Implementing nonce verification.
  • Sanitizing and escaping user input.
  • Structuring plugin code using object-oriented principles.

These techniques are applicable to many types of WordPress plugins beyond auction systems.


Conclusion

The Flipnzee Auctions plugin now includes a dedicated administration page for configuring its Escrow integration. By separating configuration from application logic and leveraging the WordPress Options API, the plugin becomes easier to deploy, maintain, and extend.

This implementation provides a solid foundation for the next phase of development, where the stored configuration will be used to establish communication with the Escrow.com API.

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


Next Lesson

In Lesson 127, we will integrate the Escrow API Client with the stored settings and implement a Test Escrow Connection feature. This will allow administrators to verify connectivity to the selected Simulation, Sandbox, or Production environment before initiating real escrow transactions.

Lesson 126 Implementation — Building the Escrow Settings Administration Page

In the previous lesson, we introduced the Flipnzee_Escrow_API_Client to separate Escrow.com communication from the rest of the plugin. Before making live API requests, however, the plugin needs a secure and configurable way to store connection settings.

In this lesson, we implement a dedicated Escrow Settings administration page. This page becomes the central location for configuring the Escrow integration and provides the foundation for future Sandbox and Production connectivity.


Why This Lesson Matters

Rather than hard-coding credentials inside PHP files, professional WordPress plugins allow administrators to manage configuration through the WordPress dashboard.

This approach offers several advantages:

  • Secure credential storage
  • Easy environment switching
  • No source code modifications
  • Future extensibility
  • Better user experience

This lesson transforms our Escrow integration from a developer-only feature into one that can be configured by site administrators.


Objectives

By the end of this lesson the plugin can:

  • Display a dedicated Escrow Settings page
  • Store settings using the WordPress Options API
  • Support multiple environments
  • Store Sandbox credentials
  • Enable or disable debug logging
  • Protect submissions using WordPress nonces

Creating a Dedicated Admin Page

A new administration class was introduced:

admin/
└── class-admin-escrow-settings.php

Keeping Escrow settings isolated from the rest of the administration area improves maintainability and keeps responsibilities clearly separated.


Registering the Menu

A new submenu was added beneath the Flipnzee Auctions menu.

The page now appears as:

Flipnzee Auctions
    Escrow Settings

This provides administrators with a single location for all Escrow configuration.


Building the User Interface

The settings page currently includes:

  • Environment selector
  • Sandbox Email
  • Sandbox API Key
  • Debug Logging option
  • Save Settings button

The interface follows the standard WordPress administration style using native form controls and the familiar form-table layout.


Supported Environments

The plugin now supports multiple operating modes.

EnvironmentPurpose
SimulationInternal testing without API requests
SandboxEscrow.com’s testing environment
ProductionLive Escrow transactions

Development will continue using Simulation Mode until live API communication is introduced in later lessons.


Saving Configuration

Instead of storing credentials in PHP constants or configuration files, settings are saved using the WordPress Options API.

This provides several benefits:

  • Persistent storage
  • Automatic serialization
  • Easy retrieval
  • WordPress compatibility

The page automatically loads the stored configuration whenever it is opened.


Security

Administrative forms should never trust submitted data.

This lesson includes several security measures:

  • WordPress nonce verification
  • Capability checks through the admin menu
  • Data sanitization
  • Escaping output before rendering

These practices help protect against common attack vectors while following WordPress coding standards.


Object-Oriented Design

The implementation continues the plugin’s object-oriented architecture.

Responsibilities remain clearly separated.

Flipnzee_Admin_Escrow_Settings
        │
        ├── render_page()
        ├── save_settings()
        └── get_settings()

Each method performs a single responsibility, making future maintenance significantly easier.


Integration with Previous Lessons

This lesson connects naturally with the previous architecture.

Lesson 125
Escrow API Client
        │
        ▼
Lesson 126
Escrow Settings
        │
        ▼
Future Lessons
Sandbox API Requests
Production API Requests
Transaction Synchronization

The API Client introduced previously will soon begin reading these settings instead of relying on hard-coded values.


Testing

The following functionality was successfully verified:

  • Escrow Settings page loads correctly
  • Environment selection works
  • Sandbox credentials display properly
  • Debug Logging option is available
  • Settings persist using the WordPress Options API
  • WordPress nonce protection is functioning
  • Object-oriented structure loads correctly

Challenges Encountered

While implementing the page, several issues were identified and resolved:

  • Missing class loading in the plugin bootstrap
  • Callback registration issues
  • Runtime debugging for admin page rendering
  • Validation of class loading order
  • Refactoring the settings page into a dedicated administration class

Resolving these issues strengthened the plugin’s initialization process and improved its overall architecture.


What’s Next?

With configuration now handled through the WordPress dashboard, the next step is to make practical use of these settings.

In Lesson 127, we will connect the Escrow API Client to the stored configuration and implement the first Test Escrow Connection feature, allowing administrators to verify communication with the selected Simulation, Sandbox, or Production environment before creating live transactions.


Files Introduced / Updated

admin/class-admin-escrow-settings.php
admin/class-admin.php
flipnzee-auctions.php

These changes establish the administrative foundation required for the upcoming Escrow integration while keeping the plugin modular, secure, and aligned with WordPress development best practices.

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

Lesson 126: Preparing Escrow.com API Credentials and Environment Configuration

Overview

In Lesson 125, Flipnzee Auctions introduced a dedicated Escrow API Client that separates API communication from the rest of the auction workflow. The client currently operates entirely in simulation mode, allowing the plugin to behave like a production system without contacting Escrow.com’s servers.

The next step is to prepare the plugin for real-world integration by introducing configurable API credentials and environment settings.

Rather than hardcoding URLs, usernames, or API keys into the source code, professional software stores these values in a secure configuration interface. This lesson lays that foundation.


Why This Lesson Matters

A production plugin should never contain credentials inside PHP files.

Instead, administrators should be able to configure:

  • Escrow Environment
  • Sandbox credentials
  • Live credentials
  • API username
  • API key
  • Enable/Disable simulation mode

This makes the plugin:

  • safer
  • easier to deploy
  • easier to migrate
  • suitable for multiple environments

Objectives

During this lesson we will:

  • create an Escrow Settings page
  • register plugin options
  • securely store credentials in WordPress options
  • allow Sandbox vs Live selection
  • update the API Client to read configuration instead of hardcoded values
  • continue operating in simulation mode by default

No live API requests will be made yet.


What Will Be Added

A new administration page:

Flipnzee Auctions
    └── Escrow Settings

It will contain fields such as:

  • Environment
Simulation
Sandbox
Production
  • Sandbox API Username
  • Sandbox API Key
  • Live API Username
  • Live API Key
  • Enable Debug Logging

Simulation Remains the Default

Even after credentials are introduced, the plugin will continue using simulation mode.

This is intentional.

The goal is to verify:

  • settings storage
  • configuration loading
  • environment switching

before sending any real HTTP requests.


Updating the API Client

Currently the API client contains values similar to:

const SANDBOX_URL = 'https://api.escrow-sandbox.com/2017-09-01';
const LIVE_URL    = 'https://api.escrow.com/2017-09-01';

After this lesson it will also retrieve:

  • username
  • API key
  • environment
  • simulation flag

from the plugin settings instead of hardcoded values.

This means future lessons can switch between Simulation, Sandbox, and Production without changing any PHP code.


Benefits

After Lesson 126 the Escrow subsystem becomes much more flexible.

Instead of editing source files, administrators will simply configure credentials through WordPress.

The API Client becomes environment-aware while remaining completely isolated from the rest of the payment workflow.

This mirrors how mature commercial plugins manage third-party integrations.


Looking Ahead

Lesson 126 prepares the configuration layer.

The next lessons will build on it:

  • Lesson 127 – Sending the First Real HTTP Request Using the WordPress HTTP API (initially to a safe endpoint or authentication check).
  • Lesson 128 – Creating Live Escrow Sandbox Transactions.
  • Lesson 129 – Synchronizing Transaction Status from Escrow.com.
  • Lesson 130 – Automatic Status Updates and Administrative Monitoring.

Conclusion

Lesson 126 moves Flipnzee Auctions another step toward production readiness by introducing configurable Escrow.com settings. Although the plugin continues to operate in simulation mode, the underlying architecture is now prepared to support Sandbox and Production environments without modifying the source code. This configuration-first approach improves security, simplifies deployment, nd provides a stable foundation for live API communication in the lessons that follow.

Lesson 125: Building an Escrow API Client Architecture for Future Live Integration

One of the biggest goals of Flipnzee Auctions has always been to support a professional transaction workflow for buying and selling websites. While previous lessons introduced the External Provider Manager and simulated Escrow transactions, the plugin was still tightly coupled to a single provider implementation.

In this lesson, the architecture takes an important step forward by introducing a dedicated Escrow API Client. Although it currently operates in simulation mode, it establishes the same separation of responsibilities used by production software and prepares the plugin for future communication with the live Escrow.com REST API.


Why Introduce an API Client?

Earlier lessons allowed the Escrow Provider to simulate transaction creation directly. While functional, that approach meant the provider class was responsible for both business logic and external communication.

As the project grows, this becomes increasingly difficult to maintain.

By introducing an API client, responsibilities become much clearer:

  • Escrow Provider
    • Handles auction payment workflow.
    • Decides when an escrow transaction should be created.
    • Stores provider information in the database.
  • Escrow API Client
    • Handles all communication with Escrow.com.
    • Manages API endpoints.
    • Prepares authentication.
    • Builds request payloads.
    • Parses API responses.

This separation makes each component easier to understand, test and replace.


Studying the Escrow.com API

Before writing any code, the official Escrow.com developer documentation was reviewed to understand how their software works.

The research focused on:

  • Sandbox environment
  • Live API endpoint
  • REST request structure
  • Authentication model
  • Transaction lifecycle
  • Status values
  • Buyer and seller roles

Rather than attempting to integrate every feature immediately, the goal of Lesson 125 is to establish the architecture that future lessons will expand.


Creating the Escrow API Client

A new class was introduced:

includes/class-escrow-api-client.php

This class becomes the single location responsible for interacting with Escrow.com.

Instead of allowing multiple classes to communicate directly with the API, every request will eventually pass through this client.

The class currently contains:

  • Sandbox endpoint
  • Live endpoint
  • API version
  • Simulation mode
  • Transaction creation method

Although responses are simulated today, replacing them with real HTTP requests later will require minimal changes elsewhere in the plugin.


Simulation Mode

During development it is undesirable to create real escrow transactions.

Instead, the client currently returns realistic responses such as:

  • success
  • provider reference
  • status
  • timestamps

This allows every surrounding component to behave exactly as it would during a live transaction without contacting the Escrow.com servers.


Refactoring the Escrow Provider

The existing provider no longer creates references itself.

Instead it now delegates that responsibility:

Escrow Provider
        ↓
Escrow API Client
        ↓
Response
        ↓
External Provider Manager

The provider now simply:

  1. Creates the API client.
  2. Requests a transaction.
  3. Receives the response.
  4. Stores provider details.
  5. Returns the reference.

This greatly reduces complexity inside the provider.


Provider Persistence

After receiving the simulated response, the provider stores:

  • Transaction ID
  • Provider name
  • Escrow reference
  • Provider status
  • Notes
  • Created date
  • Updated date

using the existing External Provider Manager introduced in previous lessons.

This ensures the transaction history remains identical whether responses originate from simulation mode or the live API in future versions.


Logging Improvements

Additional logging was added throughout the workflow.

Typical log output now resembles:

FLIPNZEE ESCROW: Starting escrow transaction...
FLIPNZEE API CLIENT: Simulation mode enabled.
FLIPNZEE API CLIENT: Returning simulated response.
FLIPNZEE EXTERNAL PROVIDER INSERT SUCCEEDED
FLIPNZEE ESCROW: Provider record created.
FLIPNZEE ESCROW: Escrow reference created.

These logs provide a complete picture of the transaction lifecycle and make debugging considerably easier.


Benefits of This Architecture

Introducing the API client provides several advantages:

  • Cleaner separation of responsibilities.
  • Easier testing.
  • Simpler debugging.
  • Reduced coupling.
  • Future API integration requires minimal changes.
  • Other payment providers can adopt the same pattern.

Most importantly, the remainder of the plugin no longer needs to know whether responses come from simulation mode or from the real Escrow.com servers.


Looking Ahead

With the architecture now in place, the plugin is ready to move beyond simulation.

Future lessons will focus on:

  • API authentication
  • Secure credential storage
  • Real HTTP requests using the WordPress HTTP API
  • Creating live Escrow.com transactions
  • Synchronizing provider status
  • Automatic transaction updates
  • Webhook support where available
  • Improved administrative monitoring

By establishing the API client first, these enhancements can be introduced incrementally without rewriting the payment workflow.


Conclusion

Lesson 125 represents an important architectural milestone for Flipnzee Auctions. Rather than jumping directly into live API integration, the plugin now adopts a layered design that separates business logic from external communication. This makes the codebase easier to maintain, easier to test, and well positioned for future integration with the Escrow.com REST API while preserving the existing transaction workflow.

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

Lesson 125: Designing the Escrow.com Integration Architecture


Overview

With the transaction management workflow now established, the next objective is to replace the simulated Escrow provider with a production-ready integration.

Rather than treating Escrow.com as simply another payment gateway, Flipnzee Auctions will use it as the central transaction platform responsible for securely managing website sales between buyers and sellers.

This lesson focuses on designing that integration before implementing live API communication.


Why Escrow.com?

Unlike Stripe or PayPal, Escrow.com is designed for high-value transactions where assets are transferred after payment conditions have been satisfied.

Website and domain sales fit this model almost perfectly.

The buyer wants assurance that ownership will be transferred.

The seller wants assurance that payment has been secured.

Escrow.com acts as the trusted intermediary throughout that process. (escrow.com)


Current Plugin Workflow

Today the plugin works like this:

Auction Ends

↓

Transaction Created

↓

Payment Completed

↓

Ownership Transfer

↓

Transaction Closed

This is ideal for simulation, but it doesn’t yet involve Escrow.com.


Future Workflow

With API integration the workflow becomes:

Auction Ends

↓

Flipnzee Creates Transaction

↓

Escrow.com Transaction Created

↓

Buyer Agrees

↓

Buyer Funds Escrow

↓

Escrow Confirms Funds

↓

Seller Transfers Website

↓

Buyer Accepts Website

↓

Escrow Releases Funds

↓

Transaction Completed

The Flipnzee plugin becomes the orchestration layer, while Escrow.com manages the escrow lifecycle. (escrow.com)


Components We Will Build

The architecture will evolve as follows:

Flipnzee Auctions

│

├── Auction Manager

├── Transaction Manager

├── Payment Manager

├── External Provider Manager

│

└── Escrow Provider

        │

        ▼

Escrow API Client

        │

        ▼

Escrow.com REST API

The existing Flipnzee_Escrow_Provider becomes responsible for communicating with the live API instead of generating simulated references.


API Responsibilities

The Escrow API Client will eventually support operations such as:

  • Create Escrow transaction
  • Retrieve transaction details
  • Synchronize provider status
  • Generate agreement links
  • Monitor funding status
  • Track inspection periods
  • Detect completion
  • Detect cancellation
  • Record disputes

This logic will remain isolated from the rest of the plugin.


Mapping Plugin Data

Most of the information required by Escrow.com already exists inside Flipnzee Auctions.

FlipnzeeEscrow.com
AuctionTransaction
ListingItem
BuyerBuyer
SellerSeller
Winning BidAmount
Transaction IDReference
Ownership TransferInspection & Acceptance

Very little additional data will be required.


Website Sales as Milestone Transactions

One particularly interesting discovery is that Escrow.com recommends Milestone Transactions for services and website/domain sales involving staged delivery. This maps well to your plugin because ownership transfer already has multiple steps that can be represented as milestones rather than a single “completed” event. (escrow.com)

A future transaction could look like:

Payment Funded

↓

Website Files Delivered

↓

Database Delivered

↓

Domain Transferred

↓

Buyer Verification

↓

Escrow Releases Funds

Your existing Ownership Transfer feature already provides the beginnings of this model.


Keeping Responsibilities Separate

One design principle remains unchanged:

  • Transaction Manager manages marketplace transactions.
  • External Provider Manager stores provider records.
  • Escrow Provider communicates with Escrow.com.
  • Escrow API Client performs HTTP requests.

Each class retains a single responsibility, making the integration easier to maintain and test.


Immediate Goal

The next implementation lessons will focus on introducing a dedicated API client and configuration rather than making live requests immediately.

A sensible progression would be:

  • Lesson 126 — Build an Escrow_API_Client class (authentication, HTTP abstraction, sandbox support).
  • Lesson 127 — Add Escrow API settings (API key, email, sandbox/live mode).
  • Lesson 128 — Create live transactions from Flipnzee Auctions.
  • Lesson 129 — Synchronize transaction status from Escrow.com.
  • Lesson 130 — Handle agreement links, funding, and milestone updates.

This staged approach lets us test each layer independently before enabling real financial transactions.


One recommendation

I also noticed from your screenshot that you’re already using Escrow.com “Buy It Now” and “Make an Offer” buttons on your listings. That’s a smart transitional solution because it gives buyers a trusted path today while the plugin evolves.

When the API integration is complete, those external buttons can be replaced by plugin-driven actions:

  • Buy with Escrow
  • Make Offer
  • Proceed to Escrow

These buttons would create and manage Escrow.com transactions automatically while keeping the user inside the Flipnzee workflow until it’s time to complete the secure escrow process. That will make Flipnzee feel like a complete marketplace rather than a site that links out to Escrow.com.

Lesson 124: Improving the Transaction Details Interface with a Transaction Summary

As the Flipnzee Auctions plugin continues to mature, the administrative interface has become just as important as the underlying business logic. Administrators need to review payment information, monitor external providers, and coordinate ownership transfers efficiently. Presenting this information in a clear and organized manner is therefore essential.

In this lesson, the focus shifted away from backend functionality and towards improving the usability of the Transaction Details page. Rather than introducing new transaction processing logic, the goal was to make existing information easier to understand and manage.


Why This Change Was Needed

By previous lessons, the Transaction Details page had already become the operational center for completed auctions. It included:

  • Payment Management
  • External Provider information
  • Ownership Transfer progress

Although all the required information was available, administrators had to scroll through multiple sections before gaining an overall understanding of a transaction.

This lesson introduces a dedicated Transaction Summary section that presents the most important information immediately upon opening the page.


Objectives

The objectives for Lesson 124 were to:

  • Improve the administrator experience.
  • Introduce a high-level transaction overview.
  • Reduce unnecessary scrolling.
  • Organize information more logically.
  • Prepare the interface for future enhancements.

Adding a Transaction Summary

The most visible enhancement in this lesson is the addition of a Transaction Summary card positioned at the top of the page.

The summary consolidates commonly referenced information into a single table, including:

  • Transaction ID
  • Auction ID
  • Listing ID
  • Seller
  • Buyer
  • Winning Bid
  • Payment Status
  • Payment Gateway
  • Creation Date
  • Last Updated

Instead of navigating between multiple sections, administrators can now understand the overall transaction at a glance.


Improving Page Hierarchy

The page now follows a more logical workflow:

Transaction Summary

↓

Payment Management

↓

External Provider

↓

Ownership Transfer

This ordering reflects the natural lifecycle of an auction transaction, making the interface easier to navigate.


Preserving Existing Business Logic

An important design decision during this lesson was to improve the presentation layer without modifying the underlying transaction workflow.

No changes were made to:

  • Payment processing
  • External Provider Manager
  • Escrow Provider integration
  • Ownership Transfer logic
  • Database schema
  • Transaction processing

Only the user interface was enhanced.

This separation between presentation and business logic reduces implementation risk while making the codebase easier to maintain.


Better Administrative Experience

With the addition of the summary section, administrators no longer need to search through multiple forms to locate basic transaction details.

Typical workflow:

Open Transaction

↓

Review Summary

↓

Update Payment Status

↓

Review Provider Information

↓

Continue Ownership Transfer

The page now better supports the day-to-day management of completed auctions.


Preparing for Future Features

The new Transaction Summary also provides a natural location for additional information that will be introduced in later lessons, including:

  • Provider synchronization status
  • Transaction activity timeline
  • Escrow synchronization timestamp
  • Buyer and seller notifications
  • Digital asset transfer progress
  • Transaction reports

By introducing the summary first, these future enhancements can be integrated without redesigning the page structure again.


Lessons Learned

This lesson demonstrates that improving software is not always about adding new functionality.

A well-organized interface can significantly improve administrator productivity without requiring changes to the underlying business logic.

Separating presentation from application logic also makes future development safer and easier, allowing interface improvements to be implemented independently of transaction processing.


Conclusion

Lesson 124 focused on enhancing the usability of the Transaction Details page by introducing a Transaction Summary and improving the overall page organization. While the plugin’s core transaction workflow remained unchanged, administrators now have a clearer, more structured overview of each completed auction.

With a stronger administrative foundation now in place, the Flipnzee Auctions plugin is well positioned for the next phase of development, where attention will return to functional enhancements such as transaction activity tracking, provider synchronization, and deeper Escrow integration.

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

Lesson 124: Improving Transaction Navigation and User Experience


Overview

As the Flipnzee Auctions plugin has evolved, the transaction management interface has become significantly more capable. Administrators can now manage payments, monitor ownership transfers, and inspect external provider information from a single screen.

However, one aspect of the user experience can still be improved.

The Transaction Details page currently exists as a standalone administration page, even though it is only meaningful when viewing a specific transaction. This creates unnecessary clutter in the WordPress administration menu and makes navigation less intuitive.

In this lesson, we will refine the transaction management workflow by improving navigation and aligning the plugin more closely with common WordPress administration patterns.


Why Improve Navigation?

The Transaction Details screen represents a detail view, not a destination in its own right.

Administrators typically follow this workflow:

Transactions

        │

        ▼

Select Transaction

        │

        ▼

Transaction Details

        │

        ▼

Payment Management

        │

        ▼

External Provider

        │

        ▼

Ownership Transfer

The page should therefore be accessed from the Transactions list rather than appearing as a permanent menu item.


Objectives

By the end of this lesson we will:

  • Hide the Transaction Details page from the WordPress sidebar.
  • Continue allowing direct access through secure admin URLs.
  • Improve navigation between the Transactions list and individual transactions.
  • Add contextual navigation for administrators.
  • Prepare the interface for future transaction actions.

Current Navigation

Today the administrator sees:

Flipnzee Auctions

Dashboard

Add Auction

Auctions

Payments

Transactions

Transaction Details

Settings

The final item is only useful when a specific transaction has been selected.


Desired Navigation

After this lesson the administration menu becomes:

Flipnzee Auctions

Dashboard

Add Auction

Auctions

Payments

Transactions

Settings

The Transaction Details page still exists, but it becomes a hidden administrative page accessed only when needed.


Improved Workflow

Instead of manually navigating to Transaction Details, the administrator simply clicks View from the Transactions list.

The flow becomes:

Transactions

        │

        ▼

View Transaction

        │

        ▼

Transaction Details

        │

        ├── Payment

        ├── External Provider

        └── Ownership Transfer

This mirrors the user experience provided by many established WordPress plugins.


Contextual Navigation

To make navigation clearer, the Transaction Details page will also introduce contextual controls such as:

← Back to Transactions

and a simple breadcrumb:

Transactions
        >
Transaction #34

These additions help administrators understand where they are within the transaction management workflow.


Architectural Benefits

This lesson is primarily about user experience rather than backend functionality, but it still reinforces good architectural principles.

The page hierarchy becomes:

Transactions

        │

        ▼

Transaction Details

        │

        ├── Payment Management

        ├── External Provider

        └── Ownership Transfer

Each screen now has a clear responsibility.


Future Expansion

This refined navigation also prepares the interface for future transaction actions, including:

  • Refresh Provider Status
  • View Activity History
  • Retry Provider Synchronization
  • Open Escrow Dashboard
  • Generate Transaction Report
  • Archive Completed Transaction

These features will naturally belong within the Transaction Details page rather than cluttering the main Transactions list.


Benefits

Completing this lesson provides several improvements:

  • Cleaner WordPress administration menu.
  • Better navigation between list and detail views.
  • Improved administrator workflow.
  • More intuitive transaction management.
  • Better alignment with WordPress administration conventions.
  • A stronger foundation for future transaction management features.

Looking Ahead

With the transaction workflow becoming easier to navigate, future lessons can focus on enriching the transaction experience rather than reorganizing it.

Upcoming work may include:

  • Provider status synchronization.
  • Transaction activity timelines.
  • Administrator action buttons.
  • Escrow API integration.
  • Automated provider updates.
  • Transaction reporting.

By refining the navigation before introducing these capabilities, the Flipnzee Auctions plugin continues its progression from a collection of independent management pages toward a cohesive, production-ready marketplace administration system.

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

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

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

In this lesson, that changes.

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


Why Display Provider Information?

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

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

Administrators frequently need answers to questions such as:

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

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


Bringing the Provider Layer into the User Interface

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

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

Conceptually, the flow now looks like this:

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

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


Information Displayed

The new External Provider section includes:

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

A typical provider record appears as follows:

FieldExample
ProviderEscrow.com
ReferenceESCROW-20260724010512-34
StatusCreated
Started2026-07-24 06:35:12
Completed—
NotesSimulated escrow transaction created.

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


Graceful Handling of Missing Provider Records

Not every transaction will necessarily have an associated provider.

For example:

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

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

This improves both usability and robustness.


Maintaining Separation of Responsibilities

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

The Transaction Details page now communicates exclusively with the Flipnzee_External_Provider_Manager.

Responsibilities are clearly divided:

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

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


Improving Administrative Visibility

The addition of provider information significantly improves the administrative workflow.

An administrator reviewing a completed transaction can now immediately determine:

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

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


Preparing for Future Integrations

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

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

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

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


Benefits of This Lesson

The improvements introduced in this lesson provide several practical advantages:

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

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


Looking Ahead

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

Future lessons will continue building upon this foundation by introducing:

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

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

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