Troubleshooting

Common issues with PayBridgeNP for WooCommerce and how to fix them.

Most problems on this page boil down to one of three things: the webhook signing secret isn’t set, your WordPress site isn’t publicly reachable, or the PayBridgeNP API key is wrong. Work through the matching section below and you’ll likely fix it in under 2 minutes.

Orders stuck in “On hold”

The single most common issue. Customers complete payment and land on your thank-you page, but the order never moves from On hold to Processing.

Most likely cause: PayBridgeNP can’t reach your webhook endpoint, OR you haven’t configured the webhook signing secret in WooCommerce settings.

Diagnostic checklist

1. Is your store publicly reachable over HTTPS? PayBridgeNP only delivers webhooks to public HTTPS URLs. If you’re running WordPress on localhost, a LAN IP, or behind a VPN, webhooks won’t arrive.

   curl -I https://yourstore.com/?wc-api=paybridge_webhook
   

   You should get a response (a 400 is fine - it means the endpoint is reachable but rejects non-signed requests). If you get a connection timeout, your store isn’t reachable from the internet.

2. Is the webhook URL in the PayBridgeNP dashboard correct? Go to PayBridgeNP dashboard → Webhooks and click the endpoint for your store. The URL should be:

   https://yourstore.com/?wc-api=paybridge_webhook
   

   Pay attention to:

   • https:// not http://
   • Correct domain (no typos, trailing slashes, or www. where it shouldn’t be)
   • ?wc-api=paybridge_webhook query string present
   • The endpoint is enabled (check the toggle in the dashboard)

3. Is the subscription list complete? The webhook must subscribe to at least payment.succeeded. Recommended: all of payment.succeeded, payment.failed, payment.cancelled.

4. Is the Webhook Signing Secret configured in WooCommerce? Go to WooCommerce → Settings → Payments → PayBridgeNP and verify the Webhook Signing Secret field has a value starting with whsec_. If it’s empty, every incoming webhook is rejected with HTTP 400 - this is deliberate, but means orders will never move past On hold.

5. Check PayBridgeNP’s delivery log. In the PayBridgeNP dashboard, click the webhook endpoint → Deliveries tab. You’ll see every event fired, the HTTP response code, and the response body. If you see 400 Invalid signature, your signing secret doesn’t match (copy-paste error? extra whitespace?). If you see 400 Webhook signing secret not configured, set the secret in WooCommerce settings. If you see 200 OK, the webhook was accepted and the plugin will have already moved the order.

6. Check your PHP error log. The plugin logs [PayBridgeNP] Webhook received but no signing secret is configured. via error_log() when a webhook arrives and the secret field is empty. Look for this in /wp-content/debug.log (if WP_DEBUG_LOG is enabled) or your server’s PHP error log.

Quick fix

If you just set up the webhook and it’s the first time through:

1. Make sure your store is publicly reachable (rule out localhost, staging sites behind HTTP auth, firewall-blocked subnets)
2. Copy the signing secret from PayBridgeNP → paste into WooCommerce settings → Save
3. In PayBridgeNP → Webhooks → your endpoint → click Send test event (or retry the failed delivery)
4. The order should flip to Processing within seconds

Customer sees “Payment error: Invalid API key” on checkout

Cause: the Secret Key field in WooCommerce settings has a typo, trailing whitespace, or is using a key from the wrong environment.

Fix:

1. Go to the PayBridgeNP dashboard → Settings → API Keys
2. Copy the key directly from the dashboard (don’t retype it)
3. Paste into WooCommerce → Settings → Payments → PayBridgeNP → Secret Key
4. Make sure you copied the whole string including the sk_live_ or sk_test_ prefix
5. Save and try again

Live vs sandbox mismatch: if you copied a sk_test_… key but your PayBridgeNP project is in live mode (or vice versa), the API rejects the key. Either switch the project mode in the dashboard or copy a matching key.

Customer sees “PayBridgeNP: the PHP SDK is missing”

Cause: You installed the plugin by copying source files (git clone or unzipping without running composer install), and the vendor/ directory is missing.

Fix:

• If you installed from the official ZIP - re-download from paybridgenp.com/integrations/woocommerce. The official ZIP includes vendor/ pre-built. If it’s still missing, your WordPress upload must have stripped subdirectories - check your hosting provider’s upload limits.
• If you installed from source - inside the plugin directory, run:
  composer install --no-dev --optimize-autoloader
  
  This generates the vendor/ directory with the PayBridgeNP PHP SDK.

Webhook endpoint returns 400 “Webhook signing secret not configured”

Cause: Merchant-side - you set up the webhook endpoint in PayBridgeNP dashboard but forgot to paste the signing secret into WooCommerce.

Fix: Go to WooCommerce → Settings → Payments → PayBridgeNP, paste the whsec_… secret from the PayBridgeNP dashboard into the Webhook Signing Secret field, and save.

The plugin refuses unsigned webhooks on purpose - without signature verification, an attacker could forge a payment.succeeded event and get free orders. There’s no way to disable this check from the settings page.

Webhook endpoint returns 400 “Invalid signature”

Cause: The signing secret in WooCommerce settings doesn’t match what PayBridgeNP is signing with.

Most common sub-causes:

• You copied a secret from the wrong webhook endpoint in the PayBridgeNP dashboard (if you have multiple endpoints)
• Extra whitespace at the start or end of the pasted secret
• You rotated the secret in the PayBridgeNP dashboard but didn’t update the WooCommerce setting

Fix:

1. Go to the PayBridgeNP dashboard → Webhooks → your endpoint
2. Look at the Signing Secret - note that PayBridgeNP only shows it once on creation, so if you’ve lost it, click Rotate secret to generate a new one
3. Paste the fresh secret into WooCommerce → Settings → Payments → PayBridgeNP → Webhook Signing Secret
4. Save and retry the failed delivery from the PayBridgeNP dashboard

Customer completes payment but WooCommerce says “Payment was cancelled”

Cause: Either the customer clicked cancel on PayBridgeNP’s hosted checkout, OR the return URL was tampered with and has &cancelled=1 appended.

Fix: Check the order notes in WooCommerce admin for the reason. If the customer really cancelled, the order is correctly set to cancelled. If you see this for orders that should have succeeded, check your PayBridgeNP dashboard’s delivery log to see what event actually fired.

Block checkout not showing PayBridgeNP

Cause: Your theme or a caching plugin is loading a stale JavaScript bundle.

Fix:

1. Flush any object cache (Redis, Memcached, WP Rocket, W3 Total Cache, etc.)
2. Clear your browser cache for the site
3. Verify in WooCommerce → Settings → Payments that the gateway is still Enabled
4. Open your checkout page in an incognito window - if PayBridgeNP shows there, the issue is browser/cache, not the plugin

If it still doesn’t show, check your browser’s DevTools console for JavaScript errors when the Blocks checkout loads. A script loading error (404 on assets/js/paybridge-block.js) usually means the plugin wasn’t fully uploaded - re-upload the ZIP.

”This plugin doesn’t work with your version of WordPress”

Cause: Your WordPress is older than 5.8 or your PHP is older than 7.4.

Fix: Upgrade WordPress + PHP. Both 5.8 and 7.4 are years out of support - you’d be running an insecure stack regardless of this plugin.

HPOS compatibility warning in WooCommerce admin

Symptom: WooCommerce admin shows “This plugin is incompatible with High-Performance Order Storage.”

Cause: You’re running an older version of the plugin (pre-1.0.0).

Fix: Update to the latest version. The current plugin declares HPOS compatibility on boot and is fully tested against custom order tables.

Still stuck?

If none of the above describes your issue, contact PayBridgeNP support with:

• Your store URL
• The WooCommerce order number
• The PayBridgeNP session id (visible in the order notes)
• The approximate time the issue occurred (with timezone)
• A copy of the delivery log entry from the PayBridgeNP dashboard, if relevant

We’ll pull our side of the delivery log and get back to you within one business day.