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
PaymentTotal NPR 3,250.00
Cash on delivery
Pay with eSewa, Khalti or FonepayYou will choose a method on the next page.
Place order

Requirements. Before you upload.

SoftwareWordPress 6.0+, WooCommerce 7.0+ and PHP 7.4+
CheckoutThe classic checkout and the Checkout block both work; HPOS is supported
CurrencyStore currency set to Nepalese rupee (NPR). The method is hidden for any other currency
PaymentsnpAt least one gateway (eSewa, Khalti or Fonepay) connected, ready and enabled in the same environment as the plugin
HTTPSA 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.

  1. 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/.

  2. Activate and open the settings

    Activate it, then open WooCommerce > Settings > Payments > Paymentsnp.

  3. 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 checkout
  • checkout:read, to read checkout status when the customer returns
  • payments: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.

Plugin settings
EnableTurns the payment method on
Title and DescriptionWhat customers see at checkout. Test mode adds a no-real-money note
ModeTest or Live. The key must match: np_test_… or np_live_…. A mismatched key is rejected on save
API keyStored on the server and never shown again in full. Leave blank to keep the saved key
Webhook signing secretOptional. The whsec_… secret from the Paymentsnp webhook endpoint
API URLKeep https://api.paymentnp.com/v1
Debug logLogs API calls to WooCommerce > Status > Logs under paymentsnp. Keys and secrets are never logged

How payment works. From Place order to paid.

  1. 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>

  2. 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.

  3. 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.

  4. 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.

Webhook URL
https://your-store.example/wp-json/paymentsnp/v1/webhook
Add it in Paymentsnp > Webhooks in the same environment as the plugin mode, then paste the whsec_ secret.

Troubleshooting. Codes and what they mean.

Common WooCommerce plugin issues
Code or symptomMeaning and fix
Method missing at checkoutThe currency is not NPR, or the saved key does not match the mode. An admin notice says which
insufficient_scopeThe key lacks one of the three scopes. Test connection names it
return_url_not_allowedThe store origin is not in Paymentsnp's allowed return origins
no_available_methodsNo ready and enabled gateway in this environment
order_conflictThe order total or customer changed after a checkout was created for that order number
payment_pendingA payment is still being confirmed. The customer is sent back to the existing checkout
Webhook 401 invalid_signatureWrong or missing signing secret, or the server clock is off by more than 5 minutes
Paid but order pendingCheck 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.