Fonepay Integration

How Fonepay Works

Key Differences from Other Gateways

Configure

nepalpay:
  fonepay:
    merchant-code: ${FONEPAY_MERCHANT_CODE}    # your PID
    secret-key:    ${FONEPAY_SECRET_KEY}
    return-url:    ${FONEPAY_RETURN_URL}
    sandbox: true  # false for production
    # No retry config — Fonepay makes no HTTP calls

buildRedirectParams()

// PRN must be 3–25 chars, unique per transaction
// AFTER — Use UUID-based PRN to avoid collision from truncation
// Distinct orderIds sharing the same first 22 chars would produce
// the same truncated PRN — risking callback misattribution.
import java.util.UUID;
String prn = "FP-" + UUID.randomUUID()
        .toString()
        .replace("-", "")
        .substring(0, 22);   // 3 + 22 = 25 chars — within Fonepay limit

// ✅ Save the generated PRN mapped to orderId BEFORE returning
orderRepo.savePrn(orderId, prn);

// ✅ Save PRN to DB BEFORE returning redirectUrl
orderRepo.savePrn(orderId, prn);

FonepayRedirectParams params = fonepayClient.buildRedirectParams(
    FonepayPaymentRequest.builder()
        .prn(prn)
        .amount(100.0)         // ⚠️ NPR directly — NOT paisa
        .remarks1("Pro Plan")  // shown to user, max 160 chars
        .remarks2("MyApp")     // optional, max 50 chars
        .build()
);

// Return redirectUrl to frontend
return params.redirectUrl();

FonepayPaymentRequest builder fields

FonepayRedirectParams fields

Frontend Redirect

Unlike eSewa and ConnectIPS which use form POST, Fonepay uses a simple URL redirect.

// JavaScript / TypeScript
startFonepayPayment(redirectUrl: string): void {
    // Simple redirect — no form needed
    window.location.href = redirectUrl;
}

// Angular example
initiatePayment(orderId: string, amount: number): void {
    this.paymentService
        .startFonepay(orderId, amount)
        .subscribe(res => {
            window.location.href = res.redirectUrl;
        });
}

verifyCallback()

Fonepay redirects to your returnUrl with all payment parameters as GET query parameters. Always verify the DV signature before trusting PS=success.

@GetMapping("/fonepay/callback")
public ResponseEntity<Map<String, Object>> callback(
        @RequestParam String PRN,
        @RequestParam String PID,
        @RequestParam String PS,
        @RequestParam String RC,
        @RequestParam String UID,
        @RequestParam String BC,
        @RequestParam String INI,
        @RequestParam(name = "P_AMT") String pAmt,
        @RequestParam(name = "R_AMT") String rAmt,
        @RequestParam(name = "DV")    String dv) {

    FonepayCallbackResponse callback =
        FonepayCallbackResponse.of(
            PRN, PID, PS, RC, UID, BC, INI, pAmt, rAmt, dv);

    // ✅ ALWAYS verify signature first — redirect params can be faked
    // verifyCallback re-computes HMAC-SHA512 and compares with DV
    // THEN checks PS=success — only after HMAC passes
    FonepayClient.FonepayVerificationResult result =
        fonepayClient.verifyCallback(callback);

    if (!result.isPaymentSuccessful()) {
        return ResponseEntity.ok(Map.of(
            "verified", false,
            "message",  "Payment not successful"
        ));
    }

    // Load order using saved PRN
    orderRepo.markPaid(PRN);
    return ResponseEntity.ok(Map.of(
        "verified", true,
        "message",  "Payment confirmed"
    ));
}

FonepayVerificationResult fields

Security Rules

// ✅ Correct flow
String prn = "FP-" + orderId;
orderRepo.savePrn(orderId, prn);       // SAVE FIRST
String url = fonepayClient
    .buildRedirectParams(request)
    .redirectUrl();                     // return to frontend

// ✅ Correct verification — always verify signature first
FonepayClient.FonepayVerificationResult result =
    fonepayClient.verifyCallback(callback);
// Throws FonepayException if DV mismatch — log as fraud attempt
if (result.isPaymentSuccessful()) {
    orderRepo.markPaid(PRN);
}

// ❌ NEVER do this
if ("success".equals(ps)) {
    orderRepo.markPaid(PRN); // DV not checked — dangerous!
}

Reactive Apps — Use Blocking Client

Fonepay makes zero server-side HTTP calls. The blocking FonepayClient is safe to use inside WebFlux applications — it never touches the event loop because all it does is HMAC signing (pure CPU, no I/O).

Direct usage in reactive service

@Service
@RequiredArgsConstructor
public class FonepayService {

    // Blocking client — inject directly in reactive apps
    private final FonepayClient fonepayClient;
    private final OrderRepository orderRepo;

    public String buildRedirect(String orderId, double amountNPR) {
        String prn = "FP-" + orderId;
        orderRepo.savePrn(orderId, prn);

        return fonepayClient.buildRedirectParams(
            FonepayPaymentRequest.builder()
                .prn(prn)
                .amount(amountNPR)
                .remarks1("Pro Plan")
                .build()
        ).redirectUrl();
    }

    // Wrap in Mono if needed for reactive pipeline composition
    // subscribeOn(boundedElastic) offloads HMAC work off event-loop
    public Mono<Boolean> verifyFonepay(
            FonepayCallbackResponse callback) {
        return Mono.fromCallable(() ->
            fonepayClient.verifyCallback(callback)
                         .isPaymentSuccessful())
            .subscribeOn(
                reactor.core.scheduler.Schedulers.boundedElastic());
    }
}

Callback Parameters Reference

Fonepay redirects to your returnUrl with these GET query parameters:

Signature algorithm

# Request signature field order (MANDATORY per Fonepay spec):
# PID,MD,PRN,AMT,CRN,DT,R1,R2,RU

# Response verification field order (MANDATORY):
# PRN,PID,PS,RC,UID,BC,INI,P_AMT,R_AMT

# HMAC-SHA512(secretKey, message, UTF-8) → hex lowercase
# DV from Fonepay is UPPERCASE hex
# NepalPay normalizes BOTH to UPPERCASE before constant-time comparison