Skip to main content
If you issue a refund from inside the Khalti or eSewa merchant dashboard (instead of from PayBridgeNP), the customer is refunded but PayBridgeNP doesn’t know about it. Your payment row stays marked “Succeeded”, your reports overstate revenue, and any downstream system that listens to payment.refunded webhooks never gets notified. Sync with provider fixes that. It re-asks the provider what they currently think about a specific payment, and reconciles your PayBridgeNP record if the provider’s view has changed.
Sync is a read action followed by a conservative write. It will create a refund row and fire a webhook only when the provider’s signal is unambiguous (a full refund). Anything ambiguous gets flagged for you to review, never silently flipped.

​
When to use it

The most common reason: a refund was issued outside PayBridgeNP.
  • You logged into your Khalti merchant dashboard and pressed Refund there.
  • You logged into your eSewa merchant panel and pressed Refund there.
  • Khalti or eSewa support reversed a transaction on your behalf.
  • A partner system on your end issued the refund through its own integration with the provider, bypassing PayBridgeNP.
Other useful cases:
  • A payment shows as Succeeded in PayBridgeNP but you want to confirm the provider still agrees (for example, before sending a high-value receipt).
  • A customer disputes a payment and you want a fresh provider-side state on file before responding.

​
Where to find it

On any individual payment’s detail page in your dashboard (Payments → click a row), you’ll see a Sync with provider button next to “Issue refund” and “Resend receipt”. The button only appears when:
  • The provider is Khalti or eSewa.
  • The payment status is Succeeded or Refunded.
For other providers and other states, the button is hidden because the action wouldn’t do anything useful.

​
What gets synced

PayBridgeNP calls the provider’s status endpoint: The provider returns a status string (and a few related fields). PayBridgeNP maps that into one of seven states and decides what to do.

​
What happens for each provider state

The “needs review” outcomes show up as a yellow toast in the dashboard. They never delete or reverse a successful payment automatically.

​
What the merchant sees

You’ll get one of three toasts after pressing the button:
  • Success (green) - “Provider reported a full refund. Recorded refund of NPR X.” The payment row reloads as Refunded, the refund appears in your Refunds list with source provider_sync, and your payment.refunded webhook fires.
  • Info (gray) - “Provider confirms the payment is still valid.” Nothing changed.
  • Warning (yellow) - “Provider reports … Investigate before mutating.” Read the message, decide what to do, and either record a manual refund or contact support.

​
Webhook behavior

When Sync detects a full refund and creates a refund row, PayBridgeNP fires the standard payment.refunded webhook to every endpoint registered for the project. The payload includes "source": "provider_sync" so your downstream systems can distinguish reconciled refunds from refunds you issued through the API or dashboard. If your webhook handler treats provider-sync refunds differently (for example, suppressing a customer-facing email because the customer already saw the provider’s confirmation), you can branch on that field. For the partial / cancelled / expired / not-found / ambiguous outcomes, no webhook fires, because no state change occurred.

​
Audit log

Every press of the Sync button is recorded in the audit log, regardless of whether anything changed. The audit row carries:
  • The user who pressed it
  • The provider’s reported state
  • The outcome (refund_recorded, no_change, or needs_review)
  • The refund ID and amount, when applicable
This is so that when a customer asks “who refunded me?” or a teammate asks “why did this flip to Refunded?”, the answer is one query away.

​
Limitations

  • Fonepay is not supported. Fonepay’s confirmation flow is WebSocket-based and has no equivalent status endpoint. Refunds issued out-of-band from Fonepay must be reconciled manually.
  • Partial refunds need manual entry. Khalti and eSewa both omit the refunded amount from their lookup responses. PayBridgeNP can tell you a partial refund happened, but not for how much.
  • Pre-feature payments cannot sync. Sync needs the provider’s lookup identifier (Khalti pidx or eSewa transaction_uuid + total_amount) to have been stored at the time the payment was created. Payments created before this feature shipped don’t have those identifiers and will return an error advising you to record any out-of-band refund manually.
  • Sync is manual, not scheduled. PayBridgeNP does not poll providers in the background. If you regularly issue refunds from the provider’s dashboard, you’ll need to remember to press Sync afterwards (or just issue refunds from PayBridgeNP, which avoids the problem entirely).
  • One payment at a time. There’s no bulk sync. If you’ve issued many out-of-band refunds, contact support and we can run a one-off reconciliation.

​
Best practice

The simplest way to never need this feature: issue refunds from PayBridgeNP, not from the provider’s dashboard. PayBridgeNP’s refund flow calls the provider for you, records the refund row, fires the webhook, and updates the payment status in one atomic step. Sync exists for the times that’s not possible (provider support reversed something, an external system bypassed your normal flow, or a teammate reached for the provider dashboard out of habit).

​
Errors