WooCommerce plugin

Drop-in payment gateway for WordPress

WooCommerce plugin

The plugin adds spuke as a payment gateway in WooCommerce. It works on classic checkout and Cart/Checkout Blocks, handles both live and test modes, and receives webhooks to reconcile orders even if the buyer closes the tab.

Current version: 1.4.2 — download it from Dashboard → Integrations → WooCommerce.

Requirements

  • WordPress 6.0+, WooCommerce 6.0+
  • PHP 7.4+
  • Non-plain permalinks (needed for the WC REST API)

Install

  1. Dashboard → Integrations → WooCommerce → Download plugin — the ZIP is generated on the fly.
  2. WP Admin → Plugins → Add New → Upload Plugin → pick spuke-woocommerce-1.4.2.zip → Install → Activate.
  3. WooCommerce → Settings → Payments → enable spuke.

Configure

Open the spuke gateway settings and fill in:

Field What to paste
Live API key An sk_live_... key from Dashboard → Developers → API keys.
Test API key An sk_test_... key.
Mode Live in production, Test while integrating.
Webhook signing secret The whsec_... shown when you create the webhook endpoint (next step).

Register the webhook

In Dashboard → Developers → Webhooks → Add endpoint set:

  • URL: https://your-store.com/wc-api/spuke
  • Events: checkout.session.completed, payment.succeeded, payment.failed, charge.refunded

Copy the signing secret into the plugin's Webhook signing secret field. Without it the plugin rejects every incoming call with 401 invalid signature and orders stay pending.

Order flow

  1. Customer places order → WooCommerce calls POST /v1/checkout/sessions with the cart total, currency, and metadata.wc_order_id.
  2. Customer is redirected to checkout_url (spuke hosted checkout).
  3. On success:
    • spuke redirects the buyer to WooCommerce's return URL.
    • spuke sends payment.succeeded to /wc-api/spuke.
    • Plugin verifies the signature (5-minute replay tolerance), matches the order by metadata.wc_order_id, and calls payment_complete().
  4. If the buyer closes the tab, the webhook still completes the order — the redirect is not the source of truth.

Idempotency

The plugin stores the last 50 event.ids per order in post meta (_spuke_events_seen). Duplicate deliveries are skipped without side effects.

Testing

Switch the plugin to Test, place a real order, pay with 4242 4242 4242 4242 (any future expiry, any CVC). The order should move to Processing within a few seconds of the redirect.

Troubleshooting

Symptom Fix
Gateway not visible at checkout Confirm the plugin is activated and toggled on in WC → Settings → Payments.
401 invalid signature in server log Signing secret in plugin ≠ secret shown in dashboard. Regenerate the endpoint and re-paste.
Order stuck at pending after redirect Webhook URL wrong or blocked by firewall. Test with curl -X POST https://your-store.com/wc-api/spuke -d '{}' — must return 401 (signature missing), not 404.
rest_no_route in WP debug log Permalinks are set to Plain. Switch to Post name in WP → Settings → Permalinks.