Return URL
Navigation only. Treat every query parameter as untrusted.
Signed webhook
Your real-time signal. Verify the raw body before reading the event.
Payment API
Your fallback check. Match status, amount, and currency to your order.
Webhooks are the source of truth
PayBridgeNP sends a signed webhook the instant a payment reaches a terminal state. This is the reliable, real-time signal to act on. Do not build your fulfillment around the browser redirect.1
2
Verify the signature
Every delivery carries an
X-PayBridgeNP-Signature: t=<timestamp>,v1=<hmac> header. Parse out t and v1, compute HMAC-SHA256(signing_secret, "<t>.<raw_request_body>"), and compare the hex digest to v1 in constant time before you trust the payload. Or let the SDK’s constructEvent() do it. Full walkthrough in Verifying webhooks.3
Act on the event
Fulfil on
payment.succeeded, release any hold on payment.failed. A delivery can repeat, so key fulfilment on the payment id and ignore repeats.Payment states
Release value only after the provider-verified payment reaches success.
When a payment fails or the buyer cancels
If a payment fails or the buyer cancels, the same checkout link (while still valid) goes back to the method picker. A notice names the provider that failed, and that provider is no longer pre-selected, so the buyer can try again or pick another method. A retry reuses the same session and does not extend its 30-minute expiry, which starts at creation. An older attempt can still settle; any extra charge is recorded as a duplicate payment. For your webhooks: a session that times out unpaid sends nothing. A buyer’s cancel sendspayment.cancelled, possibly more than once per session (one per cancelled attempt). Treat repeats as information only.
When the provider cannot be reached
If eSewa or Khalti cannot be reached to confirm a payment, it is not marked failed: nopayment.failed, and the buyer sees it is still being checked. It settles the next time the provider answers (it resends the result, or the buyer checks the status), and you get payment.succeeded if it was paid. Until then, do not release the order or ask the buyer to pay again.
Amount mismatch
If the provider reports a paid amount that differs from what the session billed, PayBridgeNP does not record a success. The payment is stored as failed with the decline reason Amount mismatch, the order is never marked paid, no receipt goes out, andpayment.failed is sent with reason set to Amount mismatch: expected <paisa>, received <paisa>.
In live mode, the amount the buyer paid has still reached your provider account: the provider moves money before we see the result. Reconcile it against your statement, and refund it from the provider’s merchant panel if needed. The payment’s page in the dashboard shows both amounts side by side.
In test mode, the eSewa and Khalti sandboxes move no real money, so a test-mode mismatch has nothing to refund. Fonepay has no sandbox: a test-mode Fonepay payment runs on your real merchant account and is real money (see Sandbox testing).
Verify before you release value
When a webhook is delayed, or you want a second confirmation before handing over something valuable, read the payment back and check its status yourself. The payment object reportsstatus: "success" once it is paid.
status is success, and the amount and currency match what you charged.
Do not poll in a tight loop
Reading the payment endpoint on a fast timer is unreliable and will run into rate limits. Let webhooks do the waiting. UseGET /v1/payments/{id} for a one-off check or to reconcile a specific payment after the fact, not as a polling loop.
Reconciliation
To reconcile a batch against your own records, page through your payments withlimit and offset and match each one:
id, status, amount, provider, and provider_ref you can match against your ledger. Page with offset until you have covered the window you care about.