Documentation
Everything you need to install, configure, and manage security deposits with SecureHold WP.
Getting Started
SecureHold WP works alongside WooCommerce and the official WooCommerce Stripe Gateway. Install the Free plugin, run the Setup Wizard, and you can place your first hold in minutes.
Requirements
| Component | Required version |
|---|---|
| WordPress | 5.8+ |
| WooCommerce | 5.0+ |
| WooCommerce Stripe Gateway | Required |
| PHP | 7.4+ |
| Stripe account | Required |
SecureHold WP requires the official WooCommerce Stripe Gateway plugin. It is not compatible with other payment gateways.
Install Free
- WordPress admin → Plugins > Add New
- Search SecureHold WP
- Install and activate
Install Pro
After purchasing SecureHold Pro, the Pro plugin ZIP will be available from your SecureHold WP account.
- Log in → My Licenses → Download SecureHold Pro
- WordPress admin → Plugins > Add New > Upload Plugin
- Upload the ZIP → Install → Activate
- The Free plugin must remain active. Pro is an extension, not standalone.
If the download button is not yet visible in your account, contact support with your purchase email and license key.
Setup Wizard
After activation, run the Setup Wizard. It guides you through:
- Dependency check
- Stripe API key entry
- Webhook configuration
- WooCommerce recommended settings
- Complete setup
Free vs Pro: quick view
SecureHold Free
- Global deposit amount (fixed or %)
- Immediate & manual timing
- Deposits list and detail pages
- Health check & customer emails
SecureHold Pro Pro
- Per-product & per-category rules
- Delayed, scheduled, and status-based capture
- Auto-release cron & admin notifications
- Dashboard analytics, log viewer, tools
Stripe Setup
SecureHold connects to Stripe with its own API keys and webhook endpoint, separate from the WooCommerce Stripe Gateway.
API Keys
Enter your Stripe publishable and secret keys in SecureHold → Settings → Stripe. You can find them in your Stripe Dashboard under Developers → API keys.
SecureHold WP uses its own Stripe keys, separate from WooCommerce Stripe Gateway. Both must be configured and must use the same mode (test or live). A mismatch will cause holds to fail silently.
Webhook
The webhook lets Stripe notify SecureHold WP when a hold is authorized, captured, released, or failed. Without it, deposit statuses will not update.
Manual webhook endpoint
https://secureholdwp.com/wp-json/securehold/v1/webhook
Events to subscribe to
- payment_intent.amount_capturable_updated
- payment_intent.succeeded
- payment_intent.canceled
- payment_intent.payment_failed
Test vs Live
Test mode and live mode require separate webhook endpoints and signing secrets. When you flip a store from test to live, register the live webhook in Stripe and update the signing secret in SecureHold.
WooCommerce Setup
Make sure WooCommerce, the Stripe Gateway, and your account settings are aligned with how SecureHold places holds.
Required plugins
| Plugin | Role | Required |
|---|---|---|
| WooCommerce | Storefront, products, orders | Yes |
| WooCommerce Stripe Gateway | Card collection at checkout | Yes |
| SecureHold WP (Free) | Hold engine and deposit settings | Yes |
| SecureHold Pro | Per-product rules, automation, analytics | Optional |
Recommended WooCommerce settings
- Enable account creation at checkout
- Enable login from checkout page
- Generate username from email
Run a test order
- Switch SecureHold and Stripe Gateway to test mode.
- Place an order using card
4242 4242 4242 4242. - In WordPress admin, open the order. You should see the SecureHold metabox showing an Authorized hold.
- Click Capture or Release to verify both flows.
Order payment vs deposit hold
WooCommerce order payment
Captured immediately at checkout via the WooCommerce Stripe Gateway. Refunds and reconciliation happen the standard WooCommerce way.
SecureHold deposit hold
A second Stripe PaymentIntent with capture_method: manual. It reserves funds without transferring them. You capture or release from the order screen.
Security Deposits
How authorization holds work, what SecureHold creates behind the scenes, and what is and is not stored in WordPress.
What is an authorization hold?
An authorization hold reserves funds on a customer’s card without transferring them. SecureHold WP creates holds using Stripe’s PaymentIntent API with capture_method: manual.
Why the card must be reusable off-session
To create a hold that can be captured later (even minutes later), Stripe requires the PaymentMethod to be saved with setup_future_usage. Without it, the card cannot be re-used to authorize the deposit and the hold will fail.
Why SecureHold creates a separate PaymentIntent
The order payment and the deposit hold are two distinct Stripe PaymentIntents on purpose: refunds, captures, and dispute flows for the order itself stay clean, while the deposit can be captured or released independently without touching the order’s accounting.
Authorization windows are time-limited and depend on card networks and Stripe rules. There is no guaranteed fixed duration. Do not assume a hold will remain valid indefinitely. Capture or release as soon as your use case allows.
WordPress and SecureHold WP never store card numbers or CVVs. All payment data is handled by Stripe. SecureHold only stores Stripe references (PaymentIntent and PaymentMethod IDs) and deposit metadata.
Configure Deposits
Define how much to hold and when to authorize. Free includes a single global rule with two timing modes; Pro adds product/category rules and automation.
Global amount
Set a single deposit amount that applies to every order. Choose between a fixed value or a percentage of the order total.
Fixed amount
Enter a number in the store’s currency:
300 = $300.00 (or equivalent in store currency)Percentage amount
Enter a value between 1 and 100:
20 = 20% of the WooCommerce order totalHold timing (Free)
Choose when the authorization hold is created on the customer’s card.
Immediate
Best for rentals and bookings where the deposit needs to exist the moment the customer commits.
Manual
Useful when the deposit amount depends on a check-in, inspection, or staff review.
Product rules Pro
Override the global amount for individual products. Edit any product → SecureHold tab → set a fixed or percentage deposit specific to that product.
Category rules Pro
Apply a deposit rule to a whole product category. Useful for entire ranges (e.g. Camera bodies or Premium suites) without editing each product.
Rule resolution cascade Pro
SecureHold Pro resolves the deposit amount per cart line in this order, taking the first match:
- Per-product rule
- Per-category rule
- Global rule
Automation strategies Pro
Pro adds three more authorization-timing strategies on top of Immediate and Manual:
- Delayed timing: authorize N minutes/hours after order creation
- Scheduled timing: authorize at a specific date/time per order
- By order status: authorize when the order transitions to a chosen status
Automation strategies rely on WP-Cron. If hosting disables WP-Cron, scheduled holds may not fire on time. Run wp-cron.php via a real system cron for reliable timing.
Manage Deposits
Every deposit has a status. Capture, release, or jump to Stripe directly from the order screen.
Deposit statuses
| Status | Meaning |
|---|---|
| pending_manual | Card saved at checkout. Waiting for you to authorize the hold. |
| scheduled | Authorization scheduled by a Pro automation strategy and not yet fired. |
| Funds reserved on the card. You can capture or release. | |
| captured | Funds transferred from the card to your Stripe balance. |
| released | Hold cancelled. No funds transferred. The customer’s available balance is restored. |
| failed | Authorization or capture did not succeed. See the deposit detail page for the Stripe error. |
Capture
From the order screen, click Capture to charge the authorized deposit amount. Stripe transfers the funds from the customer’s card to your Stripe balance and the deposit moves to captured once the webhook confirms.
Release
Click Release to cancel the hold. No funds change hands. The status moves to released and the order screen reflects the change as soon as Stripe confirms via webhook.
View in Stripe
Every SecureHold deposit links to its underlying Stripe PaymentIntent. Click View in Stripe on the deposit detail page to open the intent in your Stripe Dashboard.
Free vs Pro
Both plans run on the same engine. Pro unlocks per-product/category rules, scheduled and status-based automation, analytics, and admin tooling.
| Capability | Free | Pro |
|---|---|---|
| Global deposit amount | ||
| Immediate timing | ||
| Manual timing | ||
| Deposits list and detail pages | ||
| Health check | ||
| Customer emails | ||
| Checkout deposit notice | ||
| Per-product deposit rules | ||
| Per-category deposit rules | ||
| Rule resolution cascade | ||
| Delayed capture | ||
| Scheduled capture | ||
| Status-based capture | ||
| Auto-release cron | ||
| Admin email notifications | ||
| Dashboard analytics | ||
| Log viewer | ||
| Tools and diagnostics | ||
| My Account deposits tab | ||
| Advanced checkout message variables |
Licensing
Pro is licensed per site. Activate, deactivate, and move your license between sites from your SecureHold WP account.
Activate your license
- WordPress admin → SecureHold → License
- Paste your license key (from My Licenses in your account)
- Click Activate. The site is registered against your license.
Sites and activations
Each Pro license includes a fixed number of activations (1, 5, or 25 sites depending on plan). The current count is visible in My Licenses under each license.
Deactivate a site
Two ways:
- From WordPress admin → SecureHold → License → Deactivate
- From your account → My Licenses → Active sites → remove a site
Expired, past due, cancelled
When a license expires, existing authorized holds are not affected. Holds already in progress continue to execute. Only new Pro-specific features become inaccessible.
Manage billing
Update payment methods, view invoices, and cancel or resume a subscription from your account: /account/ → Billing.
Your Account
Manage licenses, downloads, billing, and active sites from your SecureHold WP account.
Access /account/
Visit /account/. If you already have an account, log in. If not, you can register with the same email used at purchase.
Create account
New customers can register at /account/register/. Choose a strong password. Your account is the only place to download Pro and manage license activations.
Password setup
If you purchased SecureHold Pro, an account was automatically created with your purchase email. Use /account/forgot-password/ to set your password. You do not need to register again.
View licenses
Every license you own appears under My Licenses with status, expiry, activations remaining, and download links.
View active sites
Open any license to see which sites are currently activated. Remove a site to free up an activation slot.
Change password
Account → Profile → Change password. You’ll need to enter your current password to set a new one.
Troubleshooting
The most common issues, what causes them, and how to fix them. If your problem isn’t here, contact support. We’ll add it.
Hold not created after checkout
Walk through these checks in order:
- Both SecureHold and the WooCommerce Stripe Gateway are in the same mode (test or live).
- The webhook is registered in Stripe and the signing secret is saved in SecureHold.
- The product or category is included in your deposit rules (Pro) or a global rule is set (Free).
- The order’s payment was successful. A failed primary payment will block the hold.
Webhook not receiving events
Open SecureHold → Tools → Health check. If the webhook hasn’t received events in the last 24 hours, the dashboard flags it.
- Confirm the endpoint URL exactly matches:
/wp-json/securehold/v1/webhook - Check Stripe Dashboard → Developers → Webhooks → Event log for delivery failures.
- Verify the signing secret in SecureHold matches the one shown in Stripe.
Test mode and live mode mismatch
SecureHold and the WooCommerce Stripe Gateway must be in the same mode. A common cause: the Stripe Gateway is flipped to live but SecureHold still uses test keys.
Fix: SecureHold → Settings → Stripe to confirm the keys correspond to the same Stripe account and mode as the gateway.
Invalid or incorrect API keys
If Stripe rejects every request, double-check that the publishable key starts with pk_ and the secret with sk_, and that both belong to the same Stripe account.
Use the Test connection button in SecureHold → Settings → Stripe to verify.
PaymentMethod not reusable
SecureHold needs the customer’s PaymentMethod to be saved off-session so it can authorize the deposit later. If the gateway is configured to not save methods, the hold cannot be created.
Fix: in the WooCommerce Stripe Gateway, ensure customers can save payment methods, or use Immediate timing so the hold is authorized at checkout while the method is still active.
setup_future_usage missing
If Stripe returns this error, the PaymentIntent that collected the card was created without setup_future_usage. SecureHold sets this automatically; if you’ve heavily customized the WooCommerce Stripe Gateway behavior, those customizations may be stripping it.
Fix: revert custom gateway filters that modify PaymentIntent creation parameters, or contact support with the failing intent ID.
account_mismatch error
The PaymentMethod and PaymentIntent must belong to the same Stripe account. This error means SecureHold is configured with one account and the WooCommerce Stripe Gateway with a different one.
Fix: align the Stripe API keys for both plugins so they point to the same Stripe account.
WP-Cron not running
Scheduled and delayed Pro automations rely on WP-Cron. On low-traffic sites, WP-Cron can lag. Some hosts disable it entirely.
Fix: replace WP-Cron with a real system cron that hits wp-cron.php every minute. The exact command is in SecureHold → Tools → WP-Cron status.
License not recognized after activation
Confirm the license key was copied without surrounding whitespace and that the site URL hasn’t recently changed (HTTP → HTTPS, or domain rename). A URL change can leave the activation pointing to an old domain.
Fix: from your account, remove the old site under Active sites, then re-activate from WordPress admin.
Activation limit reached
Your license is at its activation cap. From your account, deactivate a site you no longer use, or upgrade to a plan with more activations.
Customer not receiving emails
SecureHold sends emails through WordPress’s standard wp_mail() pipeline. If WooCommerce order emails work, SecureHold emails should work too.
- Check the customer’s spam folder.
- Use a transactional email plugin (e.g. an SMTP plugin) to ensure deliverability.
- In SecureHold → Settings → Emails, confirm customer notifications are enabled.
Customer cannot log in or account not found
If a customer who purchased Pro can’t log in, they may be trying to register a new account instead of resetting the password on the auto-created one.
Fix: direct them to /account/forgot-password/ with their purchase email. If the email truly doesn’t exist on the system, contact support with their order details.
Frequently asked questions
Quick answers to the questions we get most often.
Does SecureHold WP charge the customer immediately?
No. SecureHold creates an authorization hold: funds are reserved on the card without being transferred. The charge only happens if you capture the hold.
Is the deposit separate from the WooCommerce order payment?
Yes. The order payment is one Stripe PaymentIntent (charged at checkout). The deposit is a second, independent PaymentIntent with manual capture. They are tracked separately throughout their lifecycle.
How long does a hold last?
It depends on the card network and Stripe’s rules. Authorization windows are time-limited and there is no guaranteed fixed duration. Capture or release the hold as soon as your use case allows.
Can I capture only part of the deposit?
SecureHold captures the authorized deposit amount in full. There is no partial-capture option in the admin UI today.
Can I release a hold without charging?
Yes. Click Release on the deposit. Funds are never transferred, and the customer’s available balance is restored once their card issuer reflects the cancellation.
Is guest checkout supported?
Guest checkout works for the order itself. For SecureHold to authorize a hold against a saved PaymentMethod (especially with Manual or Pro automation timing), the customer must have an account so the PaymentMethod is attached to a Stripe Customer. The recommended setting is to enable account creation at checkout.
Does it work in Stripe test mode?
Yes. Use Stripe’s test cards (e.g. 4242 4242 4242 4242) and ensure both SecureHold and the WooCommerce Stripe Gateway are set to test mode with their corresponding test keys and webhook.
What if the hold fails?
The deposit moves to the failed status with the underlying Stripe error visible on the deposit detail page. Common causes: insufficient funds, card declined, card not eligible for off-session reuse. You can retry the authorization once the customer updates their payment method.
What is the difference between Free and Pro?
Free covers a single global rule, immediate and manual timing, customer emails, and the deposits screen. Pro adds per-product/category rules, scheduled and status-based capture, auto-release cron, dashboard analytics, log viewer, and admin tools. See the full comparison.
Are card numbers stored in WordPress?
Never. WordPress and SecureHold WP do not store card numbers, expiry dates, or CVVs. All card data is handled by Stripe; SecureHold stores only Stripe references and deposit metadata.
Does the customer need an account before purchasing?
Not before purchasing. But for SecureHold to manage holds reliably, an account is created at checkout (using their email). This attaches their PaymentMethod to a Stripe Customer so deposits can be authorized later.
How do I manage my license?
Visit your account and open My Licenses. From there you can download Pro, view active sites, see expiry, and manage billing.
How do I move my license to a new site?
Deactivate the old site first (either from its WordPress admin or from My Licenses → Active sites), then activate Pro on the new site using the same license key.
Still need help?
Our team replies to support tickets within one business day. Pricing and account help available too.
