WooCommerce gateway

Before you install#

• An approved NuePay account with API access and a dedicated application for your store.
• WordPress 6.4+, WooCommerce 8.3+, PHP 8.1+ with OpenSSL, and MySQL/MariaDB.
• A store priced in UGX, HTTPS, normal WordPress permalinks and working WordPress cron.

The gateway supports classic checkout, Checkout Blocks and High-Performance Order Storage (HPOS). No Node service or Composer installation is needed on the store.

Install and activate#

1. Back up your store and obtain the NuePay WooCommerce release ZIP. NuePay administrators publish approved packages in Integrations → Plugins; contact support if the package is not listed.
2. In WordPress, open Plugins → Add New → Upload Plugin, select the ZIP and choose Install Now.
3. Activate the plugin, keep WooCommerce active and open WooCommerce → Settings → Payments → NuePay.

Upload the installable ZIP, not the source repository. The package includes README.md, INSTALLATION.md and GUIDE.md.

Connect your store#

Create a dedicated application in NuePay Keys & Webhooks. Copy its test API secret and use View Signing Secret, with your transactional PIN, to obtain its separate webhook signing secret.

Save changes, then choose Check saved connection. No account number is required and no payment is requested. Saved secrets are encrypted and never shown back in the form; blank fields keep existing values.

Set the notification URL#

Copy the exact Webhook URL shown in the payment settings and save it on the matching NuePay application. Include any WordPress subdirectory.

https://YOUR-STORE-HOST/wp-json/nuepay/v1/webhook

Use a public HTTPS hostname on port 443. If WordPress generates a ?rest_route= URL, enable normal permalinks and copy the new URL. Allow POST requests through security/cache services without requiring a WordPress login.

Enable Send payment updates. Sandbox callbacks also require sandbox delivery to be enabled. Localhost cannot receive public callbacks; checkout polling can still confirm sandbox outcomes.

Test checkout#

1. Keep Test mode on, enable NuePay and place an order.
2. Choose NuePay, review the order amount, NuePay fee and total, enter a supported number and confirm the total.
3. Choose Start test payment, then use Success, Failed or Timeout.
4. Refresh during an attempt and confirm the original payment recovers without another request.

Test the checkout your store actually uses, including guest and signed-in customer access. Before real use, configure the live secrets, switch off Test mode, check the saved connection and verify an owner-approved controlled payment.

Payment totals and confirmation#

Opening checkout and loading a quote never sends a phone prompt. The customer confirms the quoted total before requesting payment. NuePay adds its quoted fee to the order principal; telecom charges may apply separately.

Checkout checks every 15 seconds. Verified notifications and background recovery can finish the same attempt after the browser closes. Only a matching live success marks the order paid. New requests stay blocked while an earlier outcome is uncertain.

Changed or cancelled orders, mismatched amounts and conflicting payments require store review. Compare the original reference in NuePay before marking an order paid or arranging a refund.

Recovery and maintenance#

Keep WordPress cron and WooCommerce Scheduled Actions working. The nuepay_reconcile action checks unresolved attempts every minute. Exclude checkout, order-pay, payment AJAX requests and the webhook from full-page caching.

Review order notes and WooCommerce → Status → Logs → nuepay. If a payment remains pending, check its original reference and delivery history; do not delete records to force another charge.