eSewa Intent

Mobile-app deeplink + cross-device QR for eSewa payments. Buyer pays inside the eSewa app or by scanning a QR with their phone, never leaves your checkout.

eSewa Intent is a newer payment flow from eSewa that lets buyers pay inside the eSewa mobile app instead of the eSewa web page. PayBridgeNP handles both the deeplink (mobile) and the cross-device QR (desktop) automatically - same POST /v1/checkout call, eSewa just feels faster and more native.

Intent is currently sandbox-only. We are waiting for eSewa to publish their production endpoint and per-merchant access keys. When live opens, Intent becomes a Premium feature; in sandbox it is open to everyone so you can prove the integration before deciding to upgrade.

Why Intent matters

Compared to the existing eSewa v2 ePay (web) flow, Intent gives you:

	v2 ePay (web)	Intent
Mobile UX	Browser detour, retype password, OTP	One tap, native app, biometric
Desktop UX	Browser redirect to eSewa.com.np	QR code on your checkout, scan with phone
Conversion	Baseline	Higher on mobile (less drop-off)
Brand feel	”I left your store and went to a website"	"I tapped pay and it just worked”

Most NP commerce is mobile-heavy. Intent removes the web detour for the majority of your buyers, which usually shows up as a measurable conversion lift.

How it works

You don’t change anything about how you create checkout sessions. PayBridgeNP picks Intent automatically when:

1. The buyer’s session is in sandbox mode (today’s only supported mode), AND
2. The merchant has eSewa configured (existing merchantCode + secretKey is enough), AND
3. The merchant has flipped the eSewa Intent toggle on at Dashboard → Providers → eSewa (off by default), AND
4. The merchant’s plan allows Intent - Free in sandbox, Premium in live (when live opens).

If any of these fail, the existing v2 ePay flow runs instead - buyer sees no difference.

What the buyer sees

1. Buyer picks eSewa on the checkout page

   Same picker tile as before. No “Intent vs Web” choice - we route automatically.

2. On mobile: deeplink opens the eSewa app

   The page fires the eSewa deeplink. The eSewa app launches with the payment pre-filled. Buyer authenticates with biometric / PIN and pays. If the app does not open within 3 seconds (e.g. the buyer does not have the eSewa app installed), the page silently submits the v2 ePay web form so the buyer never gets stuck.

3. On desktop: QR with sonar rings + scan-line animation

   The page renders a QR encoding the same deeplink. Buyer scans it with the eSewa app on their phone, pays, and the desktop page polls our /status endpoint and flips to “Payment received” within seconds. There is also a “Pay on the web instead” link for buyers who do not have the eSewa app on their phone.

4. Server-to-server callback + polling worker

   eSewa POSTs the result to our callback URL. We also run an in-process polling worker that hits eSewa’s /status API every 3-30 seconds (backoff) as a safety net in case the callback drops. Whichever lands first wins; the other is deduplicated.

What changes on your side

Nothing in the API. Your existing POST /v1/checkout request shape is unchanged. Your existing webhooks fire with the same payment.succeeded event and the same payload - provider is still "esewa". The only outward signal that Intent was used is metadata.esewa_intent.bookingId on the checkout_sessions row, which is internal-only.

Testing in sandbox

In sandbox mode, any merchant on any plan can test Intent. You do not need to upgrade. The dashboard auto-fills eSewa’s public sandbox merchant code, secret key, and Intent access key for you - no setup beyond flipping the toggle.

To test the full flow you will need:

1. A sandbox merchant account on PayBridgeNP (any plan).
2. eSewa Intent toggled on at Dashboard → Providers → eSewa (off by default - flip it to enable Intent for your sandbox).
3. eSewa’s sandbox test app (UAT APK). Direct download from eSewa: esewa_rc_release.apk (~58 MB). Install it on an Android device alongside your real eSewa app - the UAT app is a separate package and points at eSewa’s sandbox backend, so live payments cannot leak through it.
4. A phone on the same WiFi as your dev server (for the desktop QR scan flow). Or just open the deeplink URL on the phone directly.

Then create a session normally:

curl -sS -X POST https://api.paybridgenp.com/v1/checkout \
  -H "Authorization: Bearer sk_test_..." \
  -H "Content-Type: application/json" \
  -d '{
    "amount": 100,
    "currency": "NPR",
    "description": "Test payment",
    "returnUrl": "https://yourstore.com/done",
    "customer": {
      "name": "Test Customer",
      "email": "[e-mail]",
      "phone": "[phone]"
    }
  }'

Open the returned checkout_url and pick eSewa. Mobile gets the deeplink; desktop gets the QR.

What lives in metadata.esewa_intent

When Intent is dispatched, PayBridgeNP writes to checkout_sessions.metadata:

{
  "esewa_intent": {
    "bookingId": "VkRSRg==",
    "correlationId": "01KQKSG7HZ0EM28TYMS0XDFKY8"
  }
}

These are eSewa’s internal references. You can use bookingId to look up the payment in eSewa’s merchant dashboard (when live opens). They are visible to merchants on the dashboard’s payment detail page but are not part of the public API surface today.

Refunds

Refunds for Intent payments behave the same as v2 ePay: PayBridgeNP records the refund as requires_action and returns a message asking you to process it manually through the eSewa merchant dashboard. eSewa has not yet exposed an automated refund API for Intent (or for v2 ePay). When they do, refunds will become automatic for both flows in the same release.

What is coming

When eSewa hands over their production endpoint + per-merchant access keys, we will:

1. Wire the production URL into our eSewa adapter.
2. Surface the Intent Access Key field on the dashboard’s eSewa credentials form (already pre-built, hidden behind the Premium gate today).
3. Update this guide with the live-mode merchant onboarding steps (how to request your access key from eSewa).

Until then, every live-mode session will silently use v2 ePay.

Frequently asked

Will my existing eSewa integration keep working? Yes. Intent is additive - v2 ePay is still the only path for live mode and remains the fallback for sandbox merchants whose buyers do not have the eSewa app installed.

Do I need to change my SDK / webhook code? No. The provider is still reported as "esewa", the payload shape is unchanged, and the only new field is internal metadata.

What happens if the buyer does not have the eSewa app installed? On mobile, the page detects the deeplink did not open the app (3-second timeout via visibilitychange) and auto-submits the v2 ePay web form so the buyer continues without friction. On desktop, the QR is the primary call to action and there is a “Pay on the web instead” link beside it.

Can buyers refund themselves? No. Refunds are merchant-initiated, same as today.

Why is there a 30-minute session expiry? Buyers may background the eSewa app (phone call, app switch) and come back later. 30 minutes matches the picker’s expiry and gives buyers cushion. eSewa’s own session window is shorter; if they expire on eSewa’s side first the buyer gets a clear “session expired” message and can restart from your store.