Support and troubleshooting
The problems merchants and developers run into most, with what you see, why it happens and what to do. Each answer describes how Paymentsnp works today.

Payments and money. Pending, Fonepay, refunds, settlement.
A payment shows Pending or Unknown
- What you see
The order is not paid yet and the attempt shows Pending or Unknown in the dashboard, even though the customer may say they have paid.
- Why it happens
The provider has not given a clear answer: the customer is still on its page, it is still processing, or a request timed out. Unknown is treated as possibly paid, so no second payment can start on that order.
- What to do
Give it time. Unfinished eSewa and Khalti payments are re-checked in the background with growing gaps, for about 14 hours.
To ask the provider now, open the stuck payments list in the dashboard and use the re-check button. Never mark an order paid from a screenshot.
A customer paid with Fonepay, but the order is not paid
- What you see
The customer shows a Fonepay payment in their bank app. The order stays pending, then the attempt expires after 30 minutes.
- Why it happens
Fonepay has no status lookup. Paymentsnp can only confirm a Fonepay payment from the signed return when the customer comes back to checkout. If they close the app first, there is nothing for us to check.
- What to do
- Find the payment in your Fonepay merchant panel and check the amount.
- After the attempt has expired, record a manual confirmation on the order with the Fonepay reference.
- It is marked Manually confirmed, audited, and sends a
payment.manually_confirmedwebhook. A later signed return from Fonepay upgrades it to paid.
You need to refund a customer
- What you see
A customer should get money back, and there is no refund button that sends money.
- Why it happens
Paymentsnp never holds your money and does not call provider refund APIs. The money sits in your provider account, so only the provider can send it back.
- What to do
Refund in the eSewa, Khalti or Fonepay merchant panel first. Then record the refund on the payment in Paymentsnp, from the dashboard or with
POST /v1/payments/:id/refunds(scoperefunds:write, with an Idempotency-Key).Recorded refunds never exceed the payment, each provider reference is accepted once, and a
payment.refundedwebhook is sent.
Money has not reached your bank
- What you see
The dashboard shows verified payments, but your bank account does not show the money yet.
- Why it happens
Settlement happens between the provider and you, on the schedule and fees in your merchant agreement. The dashboard shows verified payments, not a balance.
- What to do
Ask the provider, through the support channel in your agreement. Paymentsnp cannot see or move settlement.
To check what arrived, upload the provider's settlement CSV under Reconciliation. Each row is matched, unmatched or a mismatch.
Checkout. Missing methods, return URLs, popups.
Khalti does not appear at checkout
- What you see
Customers see eSewa or Fonepay, but not Khalti.
- Why it happens
Khalti's minimum is Rs 10, so Khalti is hidden below that amount and left out of payment links that allow less. Otherwise Khalti is not enabled, or not ready, in this environment.
- What to do
Check the order amount. Then open Gateways in the same environment (Test or Live) and confirm Khalti's credentials are saved, ready and switched on.
A payment method does not show at checkout
- What you see
You connected a method, but customers do not see it.
- Why it happens
Saving credentials does not switch a method on. A method is offered only when its credentials are saved, it is ready and it is enabled.
Test and Live are separate, and your server can limit one checkout to specific methods. Checkout does not offer NEPALPAY QR yet.
- What to do
In Gateways, switch the method on in the environment you are testing. Check which environment your API key belongs to, and whether your checkout request limits the methods.
Creating a checkout fails with return_url_not_allowed
- What you see
The API answers 400
return_url_not_allowed: “Return URLs must belong to your workspace's allowed origins.”- Why it happens
The success or cancel URL is on an origin (scheme, host and port) that is not in your workspace's allowed origins, or it contains a username or password.
- What to do
Add the exact origin, for example https://shop.example.com, to the allowed origins in your workspace settings, then send the request again.
The popup checkout does not open
- What you see
Nothing appears when the customer clicks Pay, or your page never hears the result.
- Why it happens
The browser blocked the popup because it did not open from a click, or your site is not an approved embed domain, so the result message is not sent to it.
- What to do
Call
Paymentnp.open()directly inside the click handler. If a popup is still blocked, checkout.js falls back to opening checkout in the same tab.Add your site's origin to the approved embed domains in Settings (per environment, up to 20). Checkout never runs inside an iframe.
Integration. Webhooks and API errors.
Webhooks are failing
- What you see
Deliveries show as retrying or failed in the dashboard under Webhooks.
- Why it happens
The endpoint must be HTTPS on port 443 or 8443, at a public address, and answer within 10 seconds. Redirects are not followed.
A signature check that always fails usually means the body was parsed before verifying. Verify the signature against the raw request body.
- What to do
Fix the endpoint, then replay the event from the delivery history, or use the test send. Failed deliveries retry with growing gaps up to an hour apart and are marked failed after 8 attempts.
The API answers 409 idempotency_conflict or payment_pending
- What you see
Creating a checkout returns
409 idempotency_conflict, or starting a payment returns409 payment_pending.- Why it happens
idempotency_conflict: the same Idempotency-Key was sent with a different body.payment_pending: an earlier attempt on the order is unresolved and could still succeed, so a second one cannot start.- What to do
Use a new Idempotency-Key for each new checkout and reuse a key only to retry the identical request. For payment_pending, let the customer finish or wait for the re-check; do not create a new order to get around it.
Your account. Approval and sign-in.
Your account is awaiting approval
- What you see
Sign-in says “Your account is awaiting approval or has been disabled. Contact support.”
- Why it happens
New accounts are approved by the Paymentsnp team by default before they can be used. The same message appears if an account has been suspended.
- What to do
Make sure you verified your email from the link we sent. If approval is taking a while, or you think your account was suspended by mistake, send us a message from the email address you registered with.