Paymentsnp for WooCommerce
Version 1.0.0 of the plugin adds one payment method for eSewa, Khalti and Fonepay to your store. It works on the classic checkout and the Checkout block, supports HPOS, and marks an order paid only when the API returns a verified payment that matches it.
- Classic checkout and Checkout block
- HPOS supported
- Store currency NPR
Requirements. Before you upload.
| Software | WordPress 6.0+, WooCommerce 7.0+ and PHP 7.4+ |
|---|---|
| Checkout | The classic checkout and the Checkout block both work; HPOS is supported |
| Currency | Store currency set to Nepalese rupee (NPR). The method is hidden for any other currency |
| Paymentsnp | At least one gateway (eSewa, Khalti or Fonepay) connected, ready and enabled in the same environment as the plugin |
| HTTPS | A public HTTPS site in live mode. Paymentsnp only accepts HTTPS return origins in production |
Install. Like any other plugin.
Download the plugin from Dashboard > Downloads in Paymentsnp. Downloads are open to verified owner, administrator and developer users.
Upload the plugin
Zip the paymentsnp-for-woocommerce folder and upload it under Plugins > Add New > Upload, or copy the folder to wp-content/plugins/. Leave out tests/.
Activate and open the settings
Activate it, then open WooCommerce > Settings > Payments > Paymentsnp.
Paste a key and test
Set the mode, paste an API key from the same environment, and use the Test connection button in the Setup row.
Settings. What each field does.
API key scopes
checkout:create, to start a checkoutcheckout:read, to read checkout status when the customer returnspayments:read, to fetch the verified payment before marking an order paid
If you restrict the key to allowed IPs, add your web server's outbound IP. Keep the per-key rate limit at the default of 600 a minute or higher.
Allowed origins
Add your store origin, such as https://shop.example.com, as shown in the plugin's Setup row, under Settings > Return origins in Paymentsnp. Without it, checkout fails with return_url_not_allowed.
| Enable | Turns the payment method on |
|---|---|
| Title and Description | What customers see at checkout. Test mode adds a no-real-money note |
| Mode | Test or Live. The key must match: np_test_… or np_live_…. A mismatched key is rejected on save |
| API key | Stored on the server and never shown again in full. Leave blank to keep the saved key |
| Webhook signing secret | Optional. The whsec_… secret from the Paymentsnp webhook endpoint |
| API URL | Keep https://api.paymentnp.com/v1 |
| Debug log | Logs API calls to WooCommerce > Status > Logs under paymentsnp. Keys and secrets are never logged |
How payment works. From Place order to paid.
A checkout session for the order
The order number becomes the Paymentsnp order reference and the amount is sent as integer paisa. The customer is redirected to hosted checkout, on your custom checkout domain if you verified one.
Idempotency-Key: wc-<order id>-<paisa>-<attempt>
No second payment
If the customer tries to pay again for the same order, the plugin reuses the open checkout. If a payment is already in progress, it sends them back to it. A new session is created only after the old one expires.
Paid only when it matches
On return, the order is marked paid only when the API returns a verified payment for that order, amount, NPR and environment. If the payment is still being confirmed, the customer sees a notice and the order updates later.
Recorded on the order
The WooCommerce transaction ID is the provider transaction ID. The Paymentsnp payment ID and provider are stored as order meta and in an order note.
Webhooks. Recommended, with a cron fallback.
The plugin checks Paymentnp-Signature (HMAC-SHA256, with a 5 minute tolerance) and ignores repeated Paymentnp-Event-Id values. It never trusts the body: for payment.succeeded it fetches the payment from the API and checks the order, amount, NPR and environment before completing the order. payment.failed adds an order note.
Without webhooks, orders are still confirmed when the customer returns, and by a WP-Cron job every 10 minutes that checks up to 20 unpaid Paymentsnp orders from the last 2 days. WP-Cron runs on site traffic, so low-traffic sites should call wp-cron.php from a real cron.
https://your-store.example/wp-json/paymentsnp/v1/webhookTroubleshooting. Codes and what they mean.
| Code or symptom | Meaning and fix |
|---|---|
| Method missing at checkout | The currency is not NPR, or the saved key does not match the mode. An admin notice says which |
insufficient_scope | The key lacks one of the three scopes. Test connection names it |
return_url_not_allowed | The store origin is not in Paymentsnp's allowed return origins |
no_available_methods | No ready and enabled gateway in this environment |
order_conflict | The order total or customer changed after a checkout was created for that order number |
payment_pending | A payment is still being confirmed. The customer is sent back to the existing checkout |
Webhook 401 invalid_signature | Wrong or missing signing secret, or the server clock is off by more than 5 minutes |
| Paid but order pending | Check the order notes and the paymentsnp log. A does-not-match note means the amount, currency or environment differed |
Questions about the plugin.
Does it work with the Checkout block?
Yes. The classic checkout and the Checkout block both work, and HPOS is supported.
My store sells in US dollars. Can I use it?
No. The store currency must be Nepalese rupee. For any other currency the payment method is hidden.
Can I test without a provider account?
Yes. Use an np_test_ key and test-environment gateways. On development setups the Sandbox gateway simulates success or failure. Test payments never complete orders in live mode, and live payments never complete orders in test mode.
What if a webhook never arrives?
The order is still confirmed when the customer returns, and the WP-Cron job checks unpaid Paymentsnp orders every 10 minutes. Paymentsnp also retries failed deliveries up to 8 times.