Sync with provider

Pull the latest status of a Khalti or eSewa payment directly from the provider, and reconcile out-of-band refunds issued from the provider’s own merchant dashboard.

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:

Provider	Endpoint	Identifier used
Khalti	POST /epayment/lookup/ (Khalti ePay v2)	pidx stored when the customer first checked out
eSewa	POST /api/epay/transaction/status/	transaction_uuid + total_amount stored when the customer first checked out

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

Provider state	What PayBridgeNP does	Why
succeeded	No change. Toast: “Provider confirms the payment is still valid.”	The provider agrees with your record. Sync is idempotent so you can press it any number of times without side effects.
refunded_full	Records a refund row for the full remaining amount with source provider_sync, flips the payment to Refunded, fires a payment.refunded webhook.	A full refund is a clean, unambiguous signal. The refund note reads “Detected via provider sync - refund issued outside PayBridgeNP.”
refunded_partial	Flagged for review. No state change, no refund row. Toast asks you to record the refund manually.	Neither Khalti nor eSewa expose the refunded amount in their lookup response, only a “partially refunded” boolean. We won’t guess an amount.
cancelled	Flagged for review. No state change.	A cancelled state arriving on a payment we already consider succeeded usually means the provider’s view drifted, not that your money disappeared. We don’t auto-flip a successful payment on a single suspicious response.
expired	Flagged for review. No state change.	Same reasoning as cancelled.
not_found	Flagged for review. No state change.	If the provider can’t find the transaction, we want a human to investigate before deleting anything.
pending / ambiguous	Flagged for review. No state change.	Indeterminate signal. Press Sync again later, or contact provider support if it persists.

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

Error	Meaning
Sync is not available for fonepay	Fonepay has no status endpoint. Reconcile manually.
khalti credentials not configured for this project	The provider credentials were removed after this payment was created. Re-add them in Settings → Providers to enable sync.
No pidx stored for this payment (Khalti)	Pre-feature payment. Record the refund manually.
eSewa requires both transaction_uuid and total_amount	Pre-feature payment. Record the refund manually.
Sync failed	The provider’s status endpoint returned an error or timed out. Press Sync again in a moment. The most recent state in your dashboard is still authoritative until a successful sync overrides it.