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:
- Creates the API client.
- Requests a transaction.
- Receives the response.
- Stores provider details.
- 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