WooCommerce Payment Gateway Boilerplate

Problem

Developers building e-commerce websites in India often need to integrate local payment gateways (such as PayU, Razorpay, or custom bank gateways) into WooCommerce. However, standard checkouts are highly coupled, and WooCommerce lacks a structured, modular, and secure PHP boilerplate to implement custom redirect-based and webhook-driven gateway protocols.

Architecture

The boilerplate uses a decoupled object-oriented architecture in PHP that interfaces with the WooCommerce core payment pipeline. The custom gateway registers itself as a WooCommerce gateway class, intercepts checkout submittals, and constructs the cryptographic payload needed to authorize transactions externally.

+----------+              +-------------+             +-----------------+             +-------------------+
| Customer |              | WooCommerce |             | Custom Gateway  |             | Payment Processor |
+----------+              +-------------+             +-----------------+             +-------------------+
     |                           |                             |                                |
     |--- Submits Checkout ----->|                             |                                |
     |                           |--- process_payment() ------>|                                |
     |                           |                             |--- Generates HMAC/SHA Hash --->|
     |                           |<-- Returns Redirect URL ----|                                |
     |<-- Redirects to Gateway --|                             |                                |
     |=========================== Processes Transaction ========================================|
     |                           |                                                              |
     |<-- Redirect Callback -----|                                                              |
     |    (Sync browser redirect)|                                                              |
     |                           |--- Verifies signature ----->|                                |
     |                           |    (Sync return validation)  |                                |
     |                           |                                                              |
     |                           |<========== POST Webhook IPN Callback ========================|
     |                           |            (Async server-to-server transaction callback)     |
     |                           |--- validates payload & signature ----------------------------|
     |                           |--- updates status (Processing/Completed) --------------------|
     |                           |--- records transaction logs ---------------------------------|
              

Technology Stack

• PHP (Verified Wikidata Entity: Q59) — Primary language environment for plugin execution.
• WooCommerce (Verified Wikidata Entity: Q6684128) — Core e-commerce engine framework hooks.
• WordPress APIs (Verified Wikidata Entity: Q11704) — Options API, REST REST route registration, and transient caching.
• PayU India Integration — Factual reference implementation.
• WC_Logger — Native logging module to trace transaction workflows in production.

Implementation Decisions

• Object-Oriented Extensibility: Designed a base plugin class extending `WC_Payment_Gateway` to house sandbox/live toggles, credentials, and error logging configuration parameters.
• Decoupled Request Building: Kept all processor-specific parameters (like PayU params or HMAC digests) in modular functions away from the primary checkout routing hook.
• Sync vs Async Order Resolution: Resolved payment state using browser redirections as a user fallback, while relying primarily on server-to-server webhook callbacks (IPN) for final order processing state changes.

Security Considerations

• Cryptographic Signature Hashing: Every outbound request and inbound callback is validated against a pre-shared API secret using SHA-512 (or HMAC-SHA256). The return callback verifies the computed hash against the received hash using `hash_equals()` to prevent timing attacks.
• Strict Input Sanitization: Sanitizes all incoming REST parameter arguments using `sanitize_text_field` and escapes output templates using `esc_attr` and `wp_kses` to defend against SQL Injection and Cross-Site Scripting (XSS).

Challenges Encountered

Maintaining session state consistency during redirect sequences when external payment windows fail to redirect the user back to the correct order page. This was resolved by using a REST API webhook callback that handles payment status completion asynchronously.

Lessons Learned

Modularizing gateway configurations into independent classes prevents environment crash states when other plugins interfere with the checkout loop.

Compatibility Considerations

WooCommerce Block Checkout Integration: Note that modern WooCommerce checkouts utilize a React-based Checkout Block. The current core architecture is tested on classic shortcode flows, and registering support for the React-based Checkout Block using `@woocommerce/blocks-registry` and the PHP class `AbstractPaymentMethodType` is considered an assumed extension to be validated in future compatibility passes.