Troubleshooting

UniPay only appears at checkout when all of these conditions are met:

1. The plugin is enabled. Go to WooCommerce → Settings → Payments and confirm UniPay is toggled on.

2. An API key is configured. Go to the plugin settings and confirm Live API Key (or Test API Key in test mode) is filled in.

3. A Webhook Secret is configured. Both API Key and Webhook Secret must be present.

4. Your store is on HTTPS. UniPay is hidden on HTTP stores. Check that your store URL uses https:// in WooCommerce → Settings → General.

5. Test mode and live credentials match. If test mode is on, fill in the Test API Key. If test mode is off, fill in the Live API Key.

Run System Status to check all of these automatically.

The UNC amount line requires the live exchange rate from the UniPay API. If it's not showing:

1. Check your API key. Go to settings and click "Test connection". If it fails, the rate can't be fetched.

2. Check for JavaScript errors. Open your browser's developer console on the checkout page and look for errors related to unipay or wc-blocks-registry.

3. Check for plugin conflicts. Deactivate other plugins temporarily and reload checkout. If the UNC line appears, reactivate plugins one by one to find the conflict.

The QR code requires the qrcode.js library to load from cdnjs.cloudflare.com. If it's not showing:

1. Check your Content Security Policy (CSP). If your server or a security plugin sets a CSP header, it may be blocking external scripts. Add https://cdnjs.cloudflare.com to your script-src and connect-src directives.

2. Check for JavaScript errors. Open the browser console on the payment page and look for errors related to QRCode or cdnjs.

3. On mobile, QR is hidden by design. On screens under 600px wide, the QR is automatically hidden — use the "Open UniCash App" button instead.

This usually means the order confirmation page is being cached. A cached version of the page doesn't have the correct order context.

Fix: exclude the order confirmation page (/order-received/ or /checkout/order-received/) from your cache plugin. See System Requirements → Cache plugins for per-plugin instructions.

If orders don't auto-confirm after the customer pays, the webhook isn't reaching your store. This is the most common issue.

1. Run System Status → Webhook reachability test. It will tell you directly whether your webhook URL is reachable from outside.

2. Verify your webhook URL is registered in the merchant portal. Go to merchant.unipay.network → Settings → Integrations → WooCommerce and confirm the URL matches the one shown in your plugin settings.

3. Check for firewall rules. Some hosting providers block inbound HTTP requests from unknown IPs. UniPay's webhook sender IPs need to be whitelisted. Contact your host or run the "Send test webhook" button and check server logs for blocked requests.

4. Check the webhook secret. A wrong webhook secret causes signature verification to fail silently — the webhook is received but rejected. Go to settings, re-enter your webhook secret exactly as shown in the merchant portal, and save.

5. Enable debug logging in settings, trigger a payment, and check WooCommerce → Status → Logs for webhook-related entries.

This means the webhook is being received but the HMAC signature doesn't match. Causes:

1. Wrong webhook secret. The most common cause. In plugin settings, re-copy your webhook secret from the merchant portal exactly. Watch for leading/trailing spaces.

2. Wrong mode. If test mode is on, the plugin uses the Test Webhook Secret. If you're running a test payment, make sure your Test Webhook Secret matches the one in the merchant portal's test environment.

3. Clock skew. The webhook includes a timestamp and is rejected if the timestamp is more than 5 minutes from server time. Check your server's clock with date — it should be within a few seconds of real time. Most servers sync via NTP automatically.

UniPay webhook delivery is idempotent — if the same webhook is delivered twice (rare but possible during retry), the plugin recognises the order is already confirmed and does nothing on the second delivery. You should not see duplicate order notes or status changes.

If you are seeing duplicate confirmations, enable debug logging and share the log output with support — include the Payment ID from the order notes.

1. Re-copy the key from the merchant portal. Go to merchant.unipay.network → Settings → Integrations → WooCommerce and copy the API key fresh. Paste it into the plugin settings and save before clicking Test connection.

2. Check live vs test mode. If test mode is enabled, the plugin uses the Test API Key. Make sure you're copying from the correct environment in the merchant portal.

3. Check account status. Log in to the merchant portal and confirm your account is active and not suspended.

The rate display calls the UniPay API when the settings page loads. If it can't fetch:

1. Your API key may be invalid — click "Test connection" to verify.

2. Your server may be blocking outbound HTTPS requests. Some shared hosts restrict this. Check with your host or test with curl https://api.unicash.network/v1/plugin/rate -I from your server.

The rate display issue doesn't affect checkout — the rate for customers is fetched server-side at payment creation.

The "Refund via UniPay" button only appears on orders that were paid via UniPay. Check that the order's payment method shows "UniPay" in the order details.

If the button appears but nothing happens, enable debug logging, retry the refund, and check WooCommerce → Status → Logs for the error. Common causes: expired payment (>90 days), already fully refunded, API key issue.

If the refund record appears in WooCommerce but the customer says they haven't received the UNC, check the UniPay merchant portal. Go to the transaction in question and look for a refund record.

Refunds normally complete within seconds. If more than a few minutes have passed, contact support with the order number and UniPay Payment ID (visible in the order notes).

Go to WooCommerce → Settings → Payments → UniPay → Manage and confirm the Enable test mode checkbox is unchecked. Click Save changes. If it's already unchecked, try clearing your site cache.

This is usually a WordPress nonce issue caused by aggressive caching. Clear your site cache, reload the settings page fresh (Ctrl+Shift+R), make your changes, and save. Do not navigate to the settings page from a cached bookmark.

If the problem persists, check for a security plugin (Wordfence, iThemes Security) blocking form submissions. Check the error message in the top of the page after attempting to save.

Currency switcher plugins that change the active WooCommerce currency at checkout are not compatible with UniPay v1. The UNC amount is calculated from the store's base currency — a switched currency leads to incorrect amounts.

If you need multi-currency support, configure UniPay with your store's primary currency and handle currency display separately. Full multi-currency support is planned for a future version.

Deactivate the newly installed plugin and test if UniPay works again. If it does, the new plugin is conflicting.

Common conflict types: plugins that modify WooCommerce payment forms, plugins that add custom CSP headers, aggressive security plugins that block external scripts, and plugins that override WooCommerce templates.

Report the conflict to support with the conflicting plugin name and version — we add new incompatibilities to this documentation as they're discovered.

UniPay loads two small JavaScript files on checkout pages only (not on all pages). The QR library (qrcode.js) loads from Cloudflare's CDN and is cached aggressively — it should not noticeably affect load time.

If you're seeing measurable slowdowns, check whether the rate display in settings is the issue — it calls the API on settings page load (admin only, not customer-facing). The checkout itself only calls the API on "Place Order", not on page load.

Use your browser's Network tab to identify which request is slow, and share the findings with support.

UniPay updates are delivered through wordpress.org. If you're not seeing updates:

1. Check your WordPress auto-update settings. Go to Dashboard → Updates and check if plugin auto-updates are enabled. Alternatively, click "Check Again" to force WordPress to check for updates.

2. Confirm the plugin is from wordpress.org. If you installed from a ZIP directly, make sure it was downloaded from unipay.network/woocommerce or wordpress.org — not a third-party source. Third-party installs won't receive auto-updates.

1. Clear your site cache. Many issues after an update are caused by the old JavaScript or CSS being cached. Clear your cache plugin and browser cache.

2. Check the changelog for the version you updated to — there may be a note about a required action (e.g. re-saving settings, re-registering your webhook URL).

3. Run System Status to see if any requirement is now unmet.

If the issue persists, contact support with the version you updated from and to, and your System Status output.