Khalti Integration

How Khalti Works

Configure

nepalpay:
  khalti:
    secret-key:  ${KHALTI_SECRET_KEY}
    return-url:  ${KHALTI_RETURN_URL}
    website-url: ${YOUR_WEBSITE_URL}
    sandbox: true    # false for production

    # Optional retry
    retry:
      enabled: true
      max-attempts: 3
      initial-delay-ms: 500
      multiplier: 2.0
      max-delay-ms: 5000

initiatePayment()

KhaltiInitiateResponse response =
    khaltiClient.initiatePayment(
        KhaltiInitiateRequest.builder()
            .amount(10000L)               // NPR 100 in PAISA
            .purchaseOrderId("ORD-001")
            .purchaseOrderName("Pro Plan")
            .build()
    );

// ✅ Save pidx to DB BEFORE redirecting user
orderRepo.savePidx(orderId, response.pidx());

// Then redirect user
return response.paymentUrl();

KhaltiInitiateRequest fields

Handle the Callback

After payment, Khalti redirects to your return-url with query parameters. Never trust these parameters alone.

// Khalti redirects to:
// GET /api/khalti/callback
//     ?pidx=bZQLD9wRVWo4CdESSfuSsB
//     &status=Completed
//     &purchase_order_id=ORD-001
//     &transaction_id=GFq9DrfGSZQKjsj

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

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

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

    // Load order using saved pidx
    String orderId = orderRepo.findOrderByPidx(pidx);

    // Verify amount was not tampered
    long expectedPaisa = orderRepo.getAmountPaisa(orderId);
    if (!lookup.isAmountValid(expectedPaisa)) {
        log.error("SECURITY: Amount mismatch | pidx={} | expected={} | got={}",
            pidx, expectedPaisa, lookup.totalAmount());
        return ResponseEntity.badRequest().body("Amount mismatch");
    }

    // Safe to mark as paid
    orderRepo.markPaid(orderId, lookup.transactionId());
    return ResponseEntity.ok("Payment confirmed");
}

lookupPayment()

KhaltiLookupResponse lookup =
    khaltiClient.lookupPayment(pidx);

if (lookup.isPaymentSuccessful()) {
    // status == "Completed" — safe to mark as paid
}

// Get the typed status enum
KhaltiPaymentStatus status = lookup.paymentStatus();
// COMPLETED, PENDING, USER_CANCELED, CANCELED,
// EXPIRED, FAILED, REFUNDED, UNKNOWN

KhaltiLookupResponse fields

isAmountValid() — Tamper Protection

Always verify the amount returned by Khalti matches the amount in your database. A malicious actor could pay a different amount and try to claim a product was paid for.

KhaltiLookupResponse lookup = khaltiClient.lookupPayment(pidx);

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

// 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 this
    return ResponseEntity.badRequest().body("Amount mismatch");
}

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

refundPayment()

Full Refund

// Get transactionId from lookupPayment() first
KhaltiLookupResponse lookup = khaltiClient.lookupPayment(pidx);
String transactionId = lookup.transactionId();

KhaltiRefundResponse refund =
    khaltiClient.refundPayment(transactionId);

if (refund.isRefundSuccessful()) {
    orderRepo.markRefunded(orderId);
}

Partial Refund

// Refund NPR 50 = 5000 paisa
KhaltiRefundResponse refund =
    khaltiClient.refundPayment(transactionId, 5000L);

if (refund.isRefundSuccessful()) {
    orderRepo.markPartiallyRefunded(orderId, 5000L);
}

KhaltiRefundResponse fields

Security Rules

# Correct flow — never skip any step:

1. initiatePayment()      → save pidx to DB → redirect user
2. User returns           → ignore URL params (except pidx)
3. lookupPayment(pidx)    → verify on your server
4. isAmountValid(paisa)   → compare with DB amount
5. isPaymentSuccessful()  → then and only then mark paid

Reactive Usage

Use KhaltiReactiveClient from the reactive starter. All validation is inside Mono.defer() — errors are always emitted as reactive signals, never thrown.

@Service
@RequiredArgsConstructor
public class ReactivePaymentService {

    private final KhaltiReactiveClient khaltiReactiveClient;

    // Initiate
    public Mono<String> initiate(String orderId, long amountNPR) {
        return khaltiReactiveClient.initiatePayment(
            KhaltiInitiateRequest.builder()
                .amount(amountNPR * 100L)
                .purchaseOrderId(orderId)
                .purchaseOrderName("Pro Plan")
                .build()
        )
        .doOnNext(res -> orderRepo.savePidx(orderId, res.pidx()))
        .map(KhaltiInitiateResponse::paymentUrl);
    }

    // Lookup + amount validation
    public Mono<Boolean> verify(String pidx) {
        return khaltiReactiveClient.lookupPayment(pidx)
            .flatMap(lookup -> {
                if (!lookup.isPaymentSuccessful()) {
                    return Mono.just(false);
                }
                String orderId = orderRepo.findOrderByPidx(pidx);
                long expected = orderRepo.getAmountPaisa(orderId);
                if (!lookup.isAmountValid(expected)) {
                    log.error("Amount mismatch | pidx={}", pidx);
                    return Mono.just(false);
                }
                return orderRepo.markPaid(
                    orderId, lookup.transactionId()
                ).thenReturn(true);
            });
    }

    // Full refund
    public Mono<Boolean> refund(String transactionId) {
        return khaltiReactiveClient.refundPayment(transactionId)
            .map(KhaltiRefundResponse::isRefundSuccessful);
    }

    // Partial refund
    public Mono<Boolean> partialRefund(
            String transactionId, long amountPaisa) {
        return khaltiReactiveClient
            .refundPayment(transactionId, amountPaisa)
            .map(KhaltiRefundResponse::isRefundSuccessful);
    }
}

Payment Status Reference

Use paymentStatus().isTerminalFailure() to stop polling and offer the user a new payment link.