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.

Two colleagues looking at a laptop together, one leaning over the other's shoulder

Payments and money. Pending, Fonepay, refunds, settlement.

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

  2. 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
    1. Find the payment in your Fonepay merchant panel and check the amount.
    2. After the attempt has expired, record a manual confirmation on the order with the Fonepay reference.
    3. It is marked Manually confirmed, audited, and sends a payment.manually_confirmed webhook. A later signed return from Fonepay upgrades it to paid.
  3. 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 (scope refunds:write, with an Idempotency-Key).

    Recorded refunds never exceed the payment, each provider reference is accepted once, and a payment.refunded webhook is sent.

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

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

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

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

Integration. Webhooks and API errors.

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

    Webhook signatures and retries

  2. The API answers 409 idempotency_conflict or payment_pending

    What you see

    Creating a checkout returns 409 idempotency_conflict, or starting a payment returns 409 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.

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