Documentation

Paddle for WooCommerce — Docs

Everything you need to install, configure, and operate the PimiPay Paddle for WooCommerce plugin.

Requirements

Make sure your environment meets these before installing.

  • PHP8.3+
  • WordPress6.x
  • WooCommerce4.x+
  • MySQL8.x
  • PaddleBilling account (sandbox or production)
  • SSLHTTPS required

HPOS (High-Performance Order Storage) compatible. PSR-4 autoloading via Composer.

Installation

  1. Purchase the plugin and download the ZIP from your PimiPay account.
  2. In WordPress Admin, go to Plugins → Add New → Upload Plugin, choose the ZIP, and click install.
  3. Activate PimiPay Paddle for WooCommerce.
  4. Go to WooCommerce → Settings → Payments → Paddle and configure credentials.

Configuration

Navigate to WooCommerce → Settings → Payments → Paddle and configure:

  • Environment — Staging (sandbox) or production.
  • Staging / Production API Key — separate Paddle API keys for each environment.
  • Staging / Production Seller ID — your Paddle seller ID for each environment.
  • Webhook Settings — register webhooks to receive real-time payment notifications from Paddle.
  • Debug Mode — enable logging to WooCommerce → Status → Logs for troubleshooting.

Product sync

Sync your WooCommerce products to Paddle Billing so prices and products stay consistent across both platforms.

  • Simple products — 1 Paddle product + 1 Paddle price.
  • Variable products — 1 Paddle product + 1 price per variation.
  • Each variation is mapped to its own Paddle price, so customers can buy any variation.
  • Paddle IDs (_paddle_product_id, _paddle_price_id) are stored as product meta.

To sync a product:

  1. Go to Products in WordPress Admin.
  2. Hover over a product row.
  3. Click "Sync with Paddle".

Auto sync

Products tagged with a configurable tag (default: paddle) can be synced automatically on a schedule via WordPress cron.

  1. Go to WooCommerce → Settings → Payments → Paddle.
  2. Set Product Tag for Auto-Sync.
  3. Enable Enable Auto Sync.
  4. Set Auto Sync Interval in minutes (minimum 5, default 60).
  5. Save settings.

Price changes on tagged products are also detected automatically — no manual re-sync needed.

Checkout flow

The plugin uses Paddle's overlay checkout modal for a seamless in-page payment experience.

  1. Customer selects Paddle as the payment method and clicks "Place Order".
  2. Order is created immediately with Pending status.
  3. Customer is redirected to the order-received page, where the Paddle checkout modal auto-opens with pre-filled email, name, and cart items.
  4. After successful payment, the transaction ID is sent via AJAX to the server.
  5. The server validates the transaction with the Paddle API — verifies status, custom data, and amount.
  6. If valid, the order status is updated and the page reloads with the order confirmation.

Webhooks

Webhooks are the authoritative source of order status updates. All webhooks are HMAC SHA256-verified.

Endpoints

  • Production: /?wc-api=paddle_webhook
  • Staging: /?wc-api=paddle_webhook_staging

Each environment has its own endpoint, so you can keep staging and production isolated.

Setup

  1. Open WooCommerce → Settings → Payments → Paddle → Webhook Settings.
  2. Paste the webhook secret from your Paddle notification settings into the matching Staging Webhook Secret or Production Webhook Secret field.
  3. Click Register Webhook to create the webhook in Paddle for the current environment.
  4. Use Check Webhook to verify registration, or Forget Webhook to remove it.

Handled events

  • transaction.completed — order marked complete.
  • transaction.past_due — order marked failed.
  • transaction.canceled — order marked failed.

Security

  • HMAC SHA256 signature verification on every webhook.
  • Timestamp validation (5-second tolerance) to prevent replay attacks.
  • Timing-safe signature comparison via hash_equals().
  • Separate secrets per environment, with support for secret rotation.

Cart recovery

Paddle can send recovery emails to customers with pending payments. The plugin auto-detects recovery links and routes the customer back to their order.

  • URLs with ?_paction=recovery&_ptxn=… are intercepted automatically.
  • Orders are found by stored transaction ID, or by Paddle API lookup using custom_data.order_id as a fallback.
  • Pending orders redirect to the order-pay page; completed orders redirect to order-received.

Debug logging

Enable Debug Mode in the gateway settings to log sync operations, payment processing, API requests, and webhook activity.

View logs in WooCommerce → Status → Logs (source: paddle).

Troubleshooting

Products not syncing

  • Verify API key and seller ID for the active environment.
  • Ensure the product has a valid price.
  • Check logs at WooCommerce → Status → Logs (source: paddle).

Payment not completing

  • Confirm the product has a _paddle_price_id meta — i.e. it has been synced.
  • Check the browser console for JavaScript errors on the order-received page.
  • In sandbox mode, test with Paddle test cards.

Order stuck in pending

  • Verify the webhook is registered and reachable from the public internet.
  • Review WooCommerce logs for webhook signature failures.
  • Check the Paddle dashboard to confirm the transaction actually completed.

Webhooks not working

  • Make sure the webhook secret in the plugin matches the one in your Paddle notification settings.
  • Confirm your site is reachable over HTTPS from outside.
  • Ensure server time is accurate — timestamp validation has a 5-second tolerance.

Still stuck? Email support@pimipay.com with your site URL, plugin version, and a copy of the relevant log lines.