Security

1. Always Verify Server-Side After Redirect

When a gateway redirects to your callback URL, the URL parameters can be typed by anyone. They prove nothing. Always verify using the gateway API from your backend.

Khalti

@GetMapping("/khalti/callback")
public ResponseEntity<String> callback(
        @RequestParam String pidx,
        @RequestParam(required = false) String status) {

    // ⚠️ IGNORE ?status=Completed from URL — it can be forged
    // ✅ ALWAYS verify server-side
    KhaltiLookupResponse lookup = khaltiClient.lookupPayment(pidx);

    if (!lookup.isPaymentSuccessful()) {
        return ResponseEntity.badRequest()
            .body("Not confirmed: " + lookup.status());
    }

    // Verify amount from YOUR database
    String orderId = orderRepo.findOrderByPidx(pidx);
    long expectedPaisa = orderRepo.getAmountPaisa(orderId);
    if (!lookup.isAmountValid(expectedPaisa)) {
        log.error("SECURITY: Amount mismatch | pidx={}", pidx);
        return ResponseEntity.badRequest().body("Amount mismatch");
    }

    orderRepo.markPaid(orderId, lookup.transactionId());
    return ResponseEntity.ok("Confirmed");
}

eSewa

@GetMapping("/esewa/callback")
public ResponseEntity<String> callback(@RequestParam String data) {

    // verifyCallback: decode Base64 → verify HMAC → call status API
    EsewaClient.EsewaVerificationResult result =
        esewaClient.verifyCallback(data);

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

    orderRepo.markPaid(result.callbackData().transactionUuid());
    return ResponseEntity.ok("Confirmed");
}

ConnectIPS

@GetMapping("/connectips/callback")
public ResponseEntity<String> callback(
        @RequestParam String txnId,
        @RequestParam String referenceId,
        @RequestParam long txnAmt) {

    // validateTransaction uses HTTP Basic Auth with NCHL
    ConnectIpsValidateResponse res =
        connectIpsClient.validateTransaction(
            txnId, referenceId, txnAmt);

    if (!res.isPaymentSuccessful()) {
        return ResponseEntity.badRequest().body("Not confirmed");
    }

    orderRepo.markPaid(referenceId);
    return ResponseEntity.ok("Confirmed");
}

Fonepay

// verifyCallback re-computes HMAC-SHA512, compares DV,
// THEN checks PS=success — never trust PS alone
// Build callback from query parameters
// Fonepay sends all params as GET query params to your returnUrl
FonepayCallbackResponse callback =
    FonepayCallbackResponse.of(
        PRN,   // your original Product Reference Number
        PID,   // Fonepay merchant code
        PS,    // payment status — DO NOT trust alone
        RC,    // response code
        UID,   // Fonepay unique transaction ID
        BC,    // bank code
        INI,   // transaction initiator
        pAmt,  // paid amount
        rAmt,  // refund amount
        dv     // HMAC-SHA512 signature — the only real proof
    );

// verifyCallback: re-computes HMAC-SHA512, compares DV (constant-time),
// THEN checks PS=success — only after signature verification passes
FonepayClient.FonepayVerificationResult result =
    fonepayClient.verifyCallback(callback);

if (result.isPaymentSuccessful()) {
    // Load order using saved PRN
    orderRepo.markPaid(callback.prn());
}

2. Store Identifiers Before Redirecting

Save payment identifiers to your database before redirecting the user. If the browser crashes or the user closes the tab, you still have the ID to verify later.

// ✅ Khalti
KhaltiInitiateResponse res = khaltiClient.initiatePayment(request);
orderRepo.savePidx(orderId, res.pidx());   // ← SAVE FIRST
return res.paymentUrl();                    // ← THEN redirect

// ✅ eSewa
String uuid = EsewaClient.generateTransactionUuid();
orderRepo.saveUuid(orderId, uuid);          // ← SAVE FIRST
EsewaFormPayload payload = esewaClient.buildFormPayload(amount, uuid);
return payload;                             // ← THEN return to frontend

// ✅ ConnectIPS
String txnId = "TXN-" + orderId;
orderRepo.saveTxnId(orderId, txnId);        // ← SAVE FIRST
ConnectIpsFormPayload payload =
    connectIpsClient.buildFormPayload(req);
return payload;

// ✅ Fonepay
String prn = "FP-" + orderId;
orderRepo.savePrn(orderId, prn);            // ← SAVE FIRST
String redirectUrl = fonepayClient
    .buildRedirectParams(req).redirectUrl();
return redirectUrl;

3. Verify the Amount Was Not Tampered

A malicious user could initiate a payment for NPR 1 and try to claim a product worth NPR 1000. Always compare the gateway-confirmed amount with the amount stored in YOUR database.

// Khalti — isAmountValid() checks totalAmount matches
KhaltiLookupResponse lookup = khaltiClient.lookupPayment(pidx);

// Load expected amount from YOUR database — NOT from redirect URL
long expectedPaisa = orderRepo.getAmountPaisa(orderId);

if (!lookup.isAmountValid(expectedPaisa)) {
    log.error(
        "SECURITY ALERT: Amount mismatch | orderId={}" +
        " | expected={}paisa | received={}paisa",
        orderId, expectedPaisa, lookup.totalAmount()
    );
    // Do NOT fulfil the order — investigate immediately
    return ResponseEntity.badRequest().body("Amount mismatch");
}

if (!lookup.isPaymentSuccessful()) {
    return ResponseEntity.badRequest().body("Not paid");
}

// Both checks passed — safe to fulfil
orderRepo.markPaid(orderId, lookup.transactionId());

4. Use Environment Variables for All Secrets

# ✅ Correct — values from environment variables
nepalpay:
  khalti:
    secret-key: ${KHALTI_SECRET_KEY}

# ❌ Wrong — hardcoded in YAML
nepalpay:
  khalti:
    secret-key: live_secret_key_abc123
    # This is now in your Git history forever
    # Even after you delete it, it remains in past commits

5. Protect Your ConnectIPS .pfx File

The CREDITOR.pfx contains your RSA private key. Anyone with it can forge ConnectIPS payment tokens and steal from your merchant account.

# .gitignore — add these BEFORE your first commit
*.pfx
CREDITOR.pfx

# Verify it is not already tracked
git check-ignore -v CREDITOR.pfx

# application.yml — always load from environment variable path
nepalpay:
  connectips:
    pfx-path:     ${CONNECTIPS_PFX_PATH}     # file:/app/CREDITOR.pfx
    pfx-password: ${CONNECTIPS_PFX_PASSWORD}

Never Do These Things

How NepalPay Protects You

Pre-Launch Security Checklist

Before setting sandbox=false for any gateway, verify every item: