woocommerce-payment-sync

name	woocommerce-payment-sync
metadata	{"category":"E-Commerce and Retail Tech"}
description	WooCommerce REST API integration, webhook-driven order payment processing, inventory reconciliation, custom payment gateway integration, and Action Scheduler job queues.
compatibility	WordPress 6.x, WooCommerce 8.x/9.x, PHP 8.2+, WooCommerce REST API v3

WooCommerce Payment & Inventory Synchronization

Overview

This skill provides standards for integrating WordPress / WooCommerce with external payment gateways and ERP systems. It covers custom WooCommerce payment gateway plugin development, REST API v3 client operations, nonces security, inventory reconciliation, and background queue management via Action Scheduler.

---

1. WooCommerce Integration Principles

1. Leverage Action Scheduler for Background Jobs: Never run heavy sync logic directly inside HTTP requests or standard WP-Cron (wp_cron()). Use WooCommerce Action Scheduler (as_schedule_single_action) for reliable background processing.
2. Idempotent Webhook Handlers: Payment webhooks must check existing order metadata (_payment_completed_tx_id) before changing order status to prevent duplicate fulfillments.
3. WooCommerce High-Performance Order Storage (HPOS): Always use \WC_Order CRUD methods ($order->get_meta(), $order->update_meta_data()) instead of generic WordPress postmeta functions (get_post_meta()) to ensure compatibility with HPOS database tables (wp_wc_orders).
4. Transaction Locks on Inventory Mutations: Acquire database row locks (SELECT ... FOR UPDATE) or atomic inventory updates (wc_update_product_stock()) to prevent race conditions during flash sales.
5. Strict API Authentication: Authenticate external REST API requests using Consumer Key / Consumer Secret over HTTPS using HMAC-SHA256 signatures.

---

2. Integration & Payment Architecture

[ Customer Storefront ] ──(Checkout Form)──▶ [ Custom Payment Gateway Plugin ]
                                                    │
                                                    │ 1. Charge Request
                                                    ▼
[ WooCommerce HPOS Core ] ◀──(Webhook 200 OK)── [ Payment Provider API ]
        │
        │ 2. Trigger Action Scheduler Task
        ▼
[ Action Scheduler Queue ] ──(Background Worker)──▶ [ ERP / Inventory Sync Engine ]

Lifecycle Event	WooCommerce Hook	Primary Responsibility
Payment Process	process_payment($order_id)	Validate checkout form & initiate gateway transaction
Webhook Ingestion	woocommerce_api_{gateway_slug}	Receive IPN/Webhook, verify signature, mark order paid
Status Change	woocommerce_order_status_completed	Trigger downstream inventory sync and ERP dispatch
Background Job	as_enqueue_async_action()	Execute long-running inventory reconciliation async

---

3. Anti-Patterns & Common Errors

• Anti-Pattern: Using Legacy get_post_meta() on WooCommerce Orders
  • Risk: Total failure or missing data when WooCommerce High-Performance Order Storage (HPOS) is enabled.
  • Remediation: Always call $order = wc_get_order($order_id); $val = $order->get_meta('_custom_key');.
• Anti-Pattern: Unverified Gateway Callbacks ($_POST Ingestion)
  • Risk: Fraudulent order fulfillment by spoofing IPN requests.
  • Remediation: Validate payment processor digital signatures or re-query payment status directly via gateway API before marking payment_complete().
• Anti-Pattern: Syncing Large Inventories via Single HTTP Request
  • Risk: PHP execution timeout (max_execution_time), partial sync states, memory allocation failures.
  • Remediation: Chunk products into batches of 50 and schedule sequential Action Scheduler jobs.

---

4. Production PHP Payment Gateway & Sync Snippets

A. Custom WooCommerce Payment Gateway (class-wc-gateway-enterprise.php)

<?php
/**
 * Plugin Name: WooCommerce Enterprise Payment Gateway & Sync
 * Description: Production-grade custom payment gateway with Action Scheduler inventory sync.
 * Version: 2.1.0
 * Author: Enterprise Commerce Engineering
 */

if (!defined('ABSPATH')) {
    exit; // Exit if accessed directly
}

add_action('plugins_loaded', 'init_enterprise_payment_gateway');

function init_enterprise_payment_gateway() {
    if (!class_exists('WC_Payment_Gateway')) return;

    class WC_Gateway_Enterprise extends WC_Payment_Gateway {

        public function __construct() {
            $this->id                 = 'enterprise_pay';
            $this->icon               = apply_filters('woocommerce_enterprise_icon', '');
            $this->has_fields         = true;
            $this->method_title       = __('Enterprise Pay', 'wc-enterprise');
            $this->method_description = __('Custom enterprise payment gateway integration.', 'wc-enterprise');

            ->();
            ->();

            ->title       = ->();
            ->description = ->();
            ->api_key     = ->();

            
            ( . ->id, (, ));
            
            
            ( . ->id, (, ));
        }

         {
            ->form_fields = (
                 => (
                       => (, ),
                        => ,
                       => (, ),
                     => 
                ),
                 => (
                           => (, ),
                            => ,
                         => (, ),
                ),
                 => (
                           => (, ),
                            => ,
                )
            );
        }

         {
             = ();

             (!) {
                ((, ), );
                 ( => );
            }

             {
                
                 = ->();

                 ([] === ) {
                    
                    ->([]);
                    ->(((, ), []));

                    
                     (()) {
                        (, ( => ->()));
                    }

                    ()->cart->();

                     (
                           => ,
                         => ->()
                    );
                }  {
                    ((, ) . [], );
                     ( => );
                }
            }  (\ ) {
                (->(), );
                 ( => );
            }
        }

         {
            
             (
                         => ,
                 =>  . (())
            );
        }

         {
             = ();
               = ([]) ? ([]) : ;

             = (, , ->api_key);

             (!(, )) {
                ();
                ();
            }

             = (, );
             = ([]) ? ([]) : ;
             = ();

             ( && !->()) {
                ->([]);
                ();
                 ;
                ;
            }

            ();
             ;
            ;
        }
    }

    (, function() {
        [] = ;
         ;
    });
}


(, , , );
{
     = ();
     (!) ;

    
    ->(, ());
    ->();
}