Skip to content

WooCommerce Integration

Accept online payments in WooCommerce (WordPress) using the official SecPaid for WooCommerce plugin. This guide is for shop owners and integrators who are new to WooCommerce or SecPaid.

Overview

System Role
WooCommerce Your online store — products, cart, checkout, orders
SecPaid Payment provider — customer pays on a SecPaid-hosted page
SecPaid for WooCommerce plugin Connects both systems — redirect, webhooks, order status

The plugin is maintained by SPACEPITCH and supports WooCommerce 6.0+ (plugin v3.0.0+), including the new Cart & Checkout Blocks.

Download

Get the plugin from GitHub Releases (secpaid-woocommerce-3.0.0.zip).

How payment works

sequenceDiagram
    participant Customer
    participant Woo as WooCommerce
    participant SecPaid

    Customer->>Woo: Checkout — select SecPaid
    Woo->>Woo: Create order (pending)
    Woo->>SecPaid: createLink API
    Woo->>Customer: Redirect to SecPaid (pay_link)
    Customer->>SecPaid: Pay
    SecPaid->>Woo: Webhook POST (?wc-api=secpaid-webhook)
    Woo->>Woo: Mark order paid (payment_complete)
    SecPaid->>Customer: Redirect (?wc-api=secpaid-callback)
    Customer->>Woo: Order received page

Callback vs webhook

This follows the same pattern described in Webhooks & Callbacks:

URL Type Purpose
https://YOUR-SHOP/?wc-api=secpaid-callback Browser redirect Send customer to the order received page
https://YOUR-SHOP/?wc-api=secpaid-webhook Server POST Authoritative payment confirmation

Never skip the webhook

The callback only improves customer experience. Order fulfillment relies on the webhook — the plugin marks orders paid (via payment_complete()) when the webhook is received, even if the customer closes their browser.

Requirements

  • WordPress 6.0+ and WooCommerce 6.0+
  • PHP 7.4+
  • Valid HTTPS on your shop domain
  • Shop reachable from the internet (SecPaid must POST webhooks)
  • SecPaid account (sandbox and/or production)

Step 1 — Install the plugin

  1. Download secpaid-woocommerce-3.0.0.zip from GitHub Releases.
  2. In WordPress admin: Plugins → Add New → Upload Plugin.
  3. Choose the ZIP, click Install Now, then Activate.

Step 2 — Configure WooCommerce

  1. Go to WooCommerce → Settings → Payments.
  2. Open SecPaid and enable it.
  3. Configure:
Setting Description
Title Name shown to customers at checkout
Description Message shown under the title
API Key Your SecPaid API token (Authentication)
Environment Sandbox → app.dev.secpaid.com · Production → app.secpaid.com
Debug log Optional logging to WooCommerce → Status → Logs (source: secpaid)
  1. Save changes.

Copy integration URLs

The settings screen displays the two URLs your SecPaid account needs:

Label Example
Callback URL https://shop.example.com/?wc-api=secpaid-callback
Webhook URL https://shop.example.com/?wc-api=secpaid-webhook

Step 3 — Configure SecPaid

Log in to the SecPaid dashboard:

Integration URLs

SecPaid setting Value
Callback URL https://YOUR-SHOP-DOMAIN/?wc-api=secpaid-callback
Payment endpoint (webhook) https://YOUR-SHOP-DOMAIN/?wc-api=secpaid-webhook

Domain must match

The shop domain must match your WordPress Site Address (URL). Use HTTPS only.

API key

Create or copy an API token in SecPaid and paste it into WooCommerce Payments → SecPaid → API Key. Use a sandbox token when Environment is set to Sandbox.

Step 4 — Test in sandbox

  1. Set WooCommerce Environment to Sandbox.
  2. Place a test order and select SecPaid at checkout.
  3. Complete payment on app.dev.secpaid.com.
  4. Verify:
Check Expected
Customer redirect WooCommerce Order received page
WooCommerce → Orders Status Processing or Completed
SecPaid dashboard Payment successful

Quick endpoint test

curl -X POST "https://YOUR-SHOP/?wc-api=secpaid-webhook" \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "ResponseCode=1&data[pay_id]=test&data[status]=Success"

Expected response: {"received":true} (no order updated for the fake pay_id — that is normal).

Go-live checklist

  • Switch WooCommerce Environment to Production
  • Use the production SecPaid API key
  • Update Callback and Webhook URLs to the production shop domain
  • Confirm a valid SSL certificate
  • Run one real test order

Troubleshooting

Customer returns to cart / payment not started

Cause Fix
Invalid or missing API key Re-enter your token in Payments → SecPaid
Wrong environment token Match Sandbox/Production key with the Environment setting
Outbound HTTPS blocked Allow your server to reach app.secpaid.com

Order stays "pending" after payment

Cause Fix
Webhook URL missing in SecPaid Set …/?wc-api=secpaid-webhook
Shop blocks POST requests Allow the webhook URL through your firewall / CDN / ingress
Permalinks issue Re-save Settings → Permalinks to flush rewrite rules

Payment method not shown at checkout

  • Plugin not enabled in Payments
  • API key empty
  • For block checkout: ensure the plugin is v3.0.0+ (earlier versions registered the wrong block id)

Technical reference

Topic Detail
Plugin repository SPACEPITCH/SP-Woocommerce-Plugin
Detailed setup guide docs in plugin repo
Gateway id secpaid_payment
Order confirmation WC_Order::payment_complete() (idempotent)
HPOS / Blocks Compatible (declared)

Support