When I started building GPCB Pay, I thought displaying the card payment interface in WooCommerce would be the difficult part.
I was wrong. ๐
The bigger challenge was everything happening after a customer clicked Pay.
What happens when PayPal approves an interaction but the capture hasn't been verified? What if a network request times out? What if the same capture request is triggered twice?
These questions led me to build GPCB Pay (General PayPal Card Bridge), an independently developed WooCommerce payment integration.
I recently released its open-source WordPress connector in the official WordPress Plugin Directory. I wanted to share the architecture behind it and some lessons from building a payment SaaS independently.
1. A Payment Button Is Not a Payment System
Integrating a payment provider is more than displaying a checkout button or collecting a successful browser callback.
I designed GPCB Pay around three important rules:
- Browser approval is not proof of payment.
- Creating a PayPal Order does not mean the customer has paid.
- WooCommerce should complete an order only after successful server-verified capture.
That distinction matters.
A customer can approve a payment while the server is still processing the financial operation. Network interruptions and repeated requests can also leave the application uncertain about the outcome.
The system needs to handle those situations without assuming that a payment succeeded or blindly repeating a capture.
2. The Architecture: Three Separate Components
Instead of placing the entire payment system inside a WordPress plugin, I separated GPCB Pay into three components.
WooCommerce Connector
A lightweight WordPress plugin that integrates with WooCommerce Checkout Blocks.
It handles gateway configuration, checkout integration, authenticated communication with the backend, and WooCommerce order operations.
It isn't intended to store raw card numbers, CVV, or merchant PayPal Client Secrets.
Private SaaS Payment Core
A Node.js and TypeScript backend responsible for sensitive payment operations.
Its responsibilities include:
- Creating PayPal Orders.
- Coordinating and verifying Captures.
- Idempotency and duplicate-capture safeguards.
- Durable payment records and recovery.
- Merchant and store authorization.
- Subscription access enforcement.
The server coordinates financial operations rather than trusting the browser to declare an order paid.
Merchant Dashboard
A React-based application where merchants can manage onboarding and payment configuration.
This includes store provisioning, domain verification, Connector credentials, PayPal Sandbox and Live connections, and service-access status.
Separating these responsibilities makes the payment boundaries clearer and allows the WooCommerce Connector to remain relatively small.
3. Why Server-Verified Capture Matters
Imagine a customer approves a payment, but the next network request times out.
Did the payment fail? Did PayPal complete the Capture before the connection disappeared?
The browser alone cannot reliably answer those questions.
In GPCB Pay, the backend is responsible for verifying the provider's Capture outcome before WooCommerce can complete the order.
There are several safeguards around that process.
Idempotency: Repeated requests associated with the same payment attempt should not automatically create repeated financial effects.
Duplicate-Capture protection: The system must prevent an already captured payment from being captured again.
Durable state: Payment evidence must survive a request ending or an application restart.
Recovery and reconciliation: When an operation has an uncertain outcome, the original attempt needs verification before another financial action is considered.
One of the biggest lessons I learned is that handling an uncertain outcome is just as important as handling a successful one.
4. Guest Card vs. Advanced Card
GPCB Pay supports two explicitly configured payment experiences through eligible PayPal services.
Guest Card can provide a debit or credit card payment option through PayPal, depending on the merchant and checkout context.
Advanced Card uses PayPal-hosted card fields within the WooCommerce checkout where the merchant has the required capabilities and approval.
Both experiences depend on PayPal eligibility, supported countries, merchant configuration, and checkout conditions.
Connecting PayPal successfully does not guarantee that every card payment option will be available.
Version 0.1.0 is designed for WooCommerce Checkout Blocks, not Classic Checkout. Automatic switching between Guest and Advanced modes is not implemented.
5. Merchant Onboarding Is Also a Security Problem
Another challenge was connecting the correct WooCommerce website to the correct merchant account.
The setup process includes:
- Merchant registration and email verification.
- Creating a WooCommerce store in the Merchant Dashboard.
- Issuing a Connector Key ID and Signing Secret.
- Verifying domain ownership using a DNS TXT record.
- Proving Connector credential possession through an authenticated request.
- Completing the authorized store activation workflow.
- Configuring PayPal Sandbox and Live credentials.
- Testing connectivity and confirming payment readiness.
These checks serve different purposes.
DNS verification proves domain control. Connector proof demonstrates possession of the configured credentials. Neither one, by itself, authorizes payment processing.
This separation helped me think more carefully about trust boundaries throughout the application.
6. Full WooCommerce Setup Tutorial
I've also published an English tutorial showing the actual GPCB Pay interfaces and onboarding process.
It covers plugin installation, merchant registration, DNS verification, Connector configuration, PayPal Sandbox and Live setup, subscription access, and the eligible card checkout experiences.
The video is based on real product interfaces. Actual payment-method availability can differ depending on each merchant's PayPal eligibility.
7. The Project Is Now Available on WordPress.org
GPCB Pay's WooCommerce Connector is free and open-source under GPLv2 or later.
The operational SaaS Payment Core is a separate external service with an eligible trial or paid subscription. PayPal processing fees are separate.
If you're interested in exploring the project:
GPCB Pay is independently developed and is not affiliated with, sponsored by, or endorsed by PayPal or WooCommerce.
8. What I Learned Building This Independently
Building a payment integration pushed me to think beyond the user interface.
A successful checkout isn't just a nice-looking payment form. It needs verified financial outcomes, carefully managed authorization boundaries, persistent state, and deliberate recovery behavior.
I'm still learning and improving the engineering behind the project, and sharing that process is part of why I built it publicly.
For developers who have worked with WooCommerce or payment APIs: what's the most difficult payment edge case you've encountered?

Top comments (0)