Skip to main content
A customer landing on your success page is not proof of payment. Confirm every payment on your server before you release goods, credit, or access.

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

Register an endpoint

Add an HTTPS URL in the Dashboard under Settings → Webhooks, or with the API. Save the signing secret shown once at creation.
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.
Never fulfill an order from return-URL parameters or client-side JavaScript alone. A customer can change them. Fulfill from a signature-verified webhook on your server.

Payment states

Payment states from pending and processing to success, failed, cancelled, or refunded

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 sends payment.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: no payment.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, and payment.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 reports status: "success" once it is paid.
Before you release anything, confirm three things: the 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. Use GET /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 with limit and offset and match each one:
Every payment carries a stable 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.