Security

1. Always verify server-side after redirect

When a payment gateway redirects back to your callback URL, the URL parameters (like status=Completed) can be typed by anyone. They prove nothing. Always verify by calling the gateway API server-side.

Khalti

// ✅ CORRECT — always call lookupPayment() server-side
@GetMapping("/khalti/callback")
public ResponseEntity<String> callback(@RequestParam String pidx) {

    KhaltiLookupResponse lookup = khaltiClient.lookupPayment(pidx);

    if (!lookup.isPaymentSuccessful()) {
        return ResponseEntity.badRequest().body("Payment not confirmed");
    }

    // ✅ Now safe to mark as paid
    orderService.markAsPaid(pidx);
    return ResponseEntity.ok("Success");
}

eSewa

// ✅ CORRECT — verifyCallback() does all three checks:
// 1. Decode Base64 callback data
// 2. Verify HMAC-SHA256 signature (tamper protection)
// 3. Call eSewa status API for final confirmation
@GetMapping("/esewa/callback")
public ResponseEntity<String> callback(@RequestParam String data) {

    EsewaClient.EsewaVerificationResult result =
        esewaClient.verifyCallback(data);

    if (!result.isPaymentSuccessful()) {
        return ResponseEntity.badRequest().body("Payment not confirmed");
    }

    // ✅ Now safe to mark as paid
    orderService.markAsPaid(result.callbackData().transactionUuid());
    return ResponseEntity.ok("Success");
}

ConnectIPS

// ✅ CORRECT — always call validateTransaction() server-side
@GetMapping("/connectips/callback")
public ResponseEntity<String> callback(
        @RequestParam String txnId,
        @RequestParam String referenceId,
        @RequestParam long txnAmt) {

    ConnectIpsValidateResponse response =
        connectIpsClient.validateTransaction(txnId, referenceId, txnAmt);

    if (!response.isPaymentSuccessful()) {
        return ResponseEntity.badRequest().body("Payment not confirmed");
    }

    // ✅ Now safe to mark as paid
    orderService.markAsPaid(referenceId);
    return ResponseEntity.ok("Success");
}

2. Always store identifiers before redirecting

Save the payment identifier to your database before redirecting the user to the payment page. If the user's browser crashes or they close the tab, you still have the identifier to verify later.

// ✅ Khalti — save pidx before redirecting
KhaltiInitiateResponse response = khaltiClient.initiatePayment(request);

orderRepo.savePidx(orderId, response.pidx());    // ← save FIRST
return response.paymentUrl();                     // ← then redirect

// ✅ eSewa — save uuid before returning payload
String uuid = EsewaClient.generateTransactionUuid();
orderRepo.saveUuid(orderId, uuid);               // ← save FIRST
EsewaFormPayload payload = esewaClient.buildFormPayload(amount, uuid);
return payload;                                  // ← then return to frontend

// ✅ ConnectIPS — save txnId before returning payload
String txnId = "TXN-" + orderId;
orderRepo.saveTxnId(orderId, txnId);             // ← save FIRST
ConnectIpsFormPayload payload = connectIpsClient.buildFormPayload(request);
return payload;

3. Verify the amount was not tampered

A malicious user could potentially manipulate callback data to make it appear they paid a different amount. Always verify the amount matches what you originally charged.

// ✅ Khalti — verify amount after lookup
KhaltiLookupResponse lookup = khaltiClient.lookupPayment(pidx);

if (!lookup.isAmountValid(expectedAmountPaisa)) {
    // ⚠️ Amount mismatch — potential fraud attempt!
    log.error("Amount mismatch | expected={} | received={}",
        expectedAmountPaisa, lookup.totalAmount());
    return ResponseEntity.badRequest().body("Amount mismatch");
}

// ✅ eSewa — verifyCallback() calls status API which returns the amount
EsewaClient.EsewaVerificationResult result = esewaClient.verifyCallback(data);
// result.statusResponse().totalAmount() — compare to your order amount

4. Use environment variables for all secrets

Secret keys hardcoded in source code or YAML files end up in your Git history — even if you delete them later.

# ✅ CORRECT — values from environment variables
nepalpay:
  khalti:
    secret-key: ${KHALTI_SECRET_KEY}
  esewa:
    secret-key: ${ESEWA_SECRET_KEY}
  connectips:
    app-password: ${CONNECTIPS_APP_PASSWORD}
    pfx-password: ${CONNECTIPS_PFX_PASSWORD}

# ❌ WRONG — hardcoded secret in YAML
nepalpay:
  khalti:
    secret-key: live_secret_key_abc123xyz   # exposed forever in git history!

5. Protect your ConnectIPS .pfx file

The CREDITOR.pfx file contains your RSA private key. Anyone with this file can generate valid ConnectIPS payment tokens.

# ✅ Add to .gitignore — NEVER commit the .pfx file
*.pfx
CREDITOR.pfx

# ✅ Load via file path from environment variable
nepalpay:
  connectips:
    pfx-path: ${CONNECTIPS_PFX_PATH}      # e.g. file:/app/CREDITOR.pfx
    pfx-password: ${CONNECTIPS_PFX_PASSWORD}

On production servers: place the .pfx file outside the web-accessible directory and reference it by absolute path.

Never Do These Things

How NepalPay Protects You

NepalPay enforces these security patterns by design — not as optional helpers, but as the primary API surface.

Pre-Launch Security Checklist

Before switching to sandbox=false and going live, verify every item: