WordPress — Docs

The official SpicePay plugin turns any WordPress site into a store. You manage products, orders, and refunds from the WordPress admin, and checkout is handled by an embedded hosted-checkout iframe (or a full-page redirect). Card data is entered on the hosted checkout and never reaches your WordPress server or database.

It's a self-contained plugin — it brings its own product catalog and works with any theme, so you don't need any other e-commerce plugin.

Already selling with WooCommerce? Install SpicePay for WooCommerce instead. It's a payment gateway, not a store: WooCommerce keeps the cart, checkout, taxes, shipping and orders, and SpicePay contributes the payment methods. See SpicePay for WooCommerce below.

Download

Neither plugin is on the WordPress.org plugin directory — download the one you need here and install it manually.

Package	Version	Download
SpicePay plugin (standalone store)	1.3.0	spicepay.zip
SpicePay Shop theme (optional)	0.2.1	spicepay-shop.zip
SpicePay for WooCommerce (gateway)	1.2.0	spicepay-woocommerce.zip

Pick one of the two plugins: spicepay.zip if SpicePay should run the store, spicepay-woocommerce.zip if WooCommerce already does. The standalone plugin works with any theme; the optional SpicePay Shop theme is a ready-made, fully customizable storefront design that pairs with it.

Install

The rest of this page covers the standalone plugin; for the WooCommerce gateway skip to SpicePay for WooCommerce.

In your WordPress admin, go to Plugins → Add New → Upload Plugin, choose spicepay.zip, and click Install Now, then Activate. A SpicePay menu appears in the admin sidebar.
(Optional) To use the storefront theme, go to Appearance → Themes → Add New → Upload Theme, choose spicepay-shop.zip, install, and activate it.

Requirements: WordPress 6.0+ and PHP 7.4+. A SpicePay merchant account is required — the plugin is the open-source integration; the payment service it connects to is SpicePay's hosted platform.

Connect your account

Go to SpicePay → Settings and click Connect to SpicePay.
A secure popup opens the Control Center and, after you approve, provisions the plugin's API key and webhook secret automatically — you don't copy or paste any keys.
Pick your environment and default currency.

Add products and checkout

Add your products under SpicePay → Products (and optional categories), then place the store on your pages with the plugin's shortcodes — [spicepay_products], [spicepay_product], [spicepay_categories], [spicepay_cart], [spicepay_checkout], and [spicepay_complete]. Under SpicePay → Settings you choose how the cart checks out:

Embedded — the hosted checkout is framed inside your store page.
External — the customer is redirected to the hosted checkout and back.
Both — offer the customer either.

Test before you sell

Tick Test mode under SpicePay → Settings and every order the store creates is sent as a test payment: it runs against your processor's sandbox and stays out of your live transactions and analytics. A warning banner runs on every admin screen while it is on, because a store left in test mode takes orders that never get paid.

Each order records the environment it ran in, so turning test mode off does not relabel the test orders you already have — SpicePay → Orders shows a Test badge on the list and an Environment row on the order detail. Orders placed before plugin 1.3.0 show Unknown, since the plugin has no way to find that out after the fact.

One caveat worth reading before you rely on it: a processor with no sandbox credentials stored in SpicePay is used with its live ones, which means a real charge recorded as a test. See Environments.

How it works

On checkout, the plugin creates the order server-side and calls POST /payments, pricing line items against your SpicePay product catalog in WordPress (never trusting client-side prices).
The customer pays inside the SpicePay-hosted checkout at https://checkout.spicepay.net/pay/{merchant_id}/{payment_id}.
SpicePay sends a signed webhook to https://your-site.example/wp-json/spicepay/v1/webhook. The plugin verifies the X-Webhook-Signature-512 HMAC before updating the order — the webhook, not the browser redirect, is the source of truth for order status.

Refunds (full and partial) are issued from SpicePay → Orders and pushed to the connector, reconciled by a background job.

Wallets in the embedded checkout

The plugin embeds the checkout in an iframe. Stripe only offers Apple Pay, Google Pay and Link when the top-level page's domain is registered as a payment method domain — inside an iframe that page is your WordPress site, so Stripe hides them.

Turn those methods into native panes on your Stripe connector and the checkout shows a tile for each; clicking it opens the hosted checkout in a new tab, at the top level, with only that method.

The iframe the plugin renders already permits this — it carries allow="payment *" and no sandbox attribute. If your theme or a page builder wraps the shortcode in its own sandboxed frame, it needs allow-popups and allow-popups-to-escape-sandbox (so the tab opens) plus allow-top-navigation-by-user-activation (so redirect methods like PayPal and Klarna can still hand off). An incomplete set blocks the tab and customers get a fallback link instead of a working tile.

SpicePay for WooCommerce

If your store already runs on WooCommerce, spicepay-woocommerce.zip adds SpicePay as a payment gateway and changes nothing else. WooCommerce keeps the cart, the checkout page, taxes, shipping, coupons, emails, the thank-you page and the order status machine; the plugin contributes payment methods, a settings tab, a webhook receiver and refunds. It adds no custom tables and no admin menu of its own, and it is compatible with HPOS and the block checkout.

Install and connect

Install and activate WooCommerce first.
Go to Plugins → Add New → Upload Plugin, choose spicepay-woocommerce.zip, install and activate.
Go to WooCommerce → Settings → SpicePay and click Connect to SpicePay. The popup provisions the API key, the webhook secret and the webhook registration for you — no keys to copy. (A manual-credentials fallback is there for browsers that block popups.) If the standalone SpicePay plugin is already connected on the same site, the tab offers to reuse that connection with one click.
Under WooCommerce → Settings → SpicePay → Payment methods, pick the methods to offer, then enable each one under WooCommerce → Settings → Payments.

Payment methods at checkout

Each method you enable is its own row under WooCommerce → Settings → Payments, with WooCommerce's native enable toggle, title, description and icon. The plain SpicePay row offers every method your account has enabled on one hosted checkout; the per-method rows (card, Apple Pay, Google Pay, PayPal, Klarna, SEPA, iDEAL, Bancontact, crypto and more) restrict the hosted checkout to that single method, so the buyer gets exactly what they picked.

Unlike the standalone plugin, the checkout is not embedded in an iframe: the buyer is sent off-site to SpicePay's hosted checkout and returns to WooCommerce's order-received page, so the wallet caveat above does not apply.

Orders and refunds

The signed webhook is the source of truth for order status; the plugin also verifies the payment against the SpicePay API when the buyer lands back on the order-received page, so the thank-you page is right even if the webhook is a second late. A captured amount that doesn't match the order total puts the order on hold with a note rather than marking it paid.

Refunds — full or partial — are issued from the normal WooCommerce order screen and sent to SpicePay; refunds issued from the SpicePay dashboard are mirrored back as WooCommerce refunds. Every payment, refund and dispute event leaves a note on the order. Logs go to WooCommerce → Status → Logs, source spicepay, with secrets redacted.

Requirements: WordPress 6.0+, PHP 7.4+ and WooCommerce 8.0+.

Payments — the checkout the plugin embeds
Webhooks — the events that drive order status
Dashboard — manage connectors, branding, and orders