eSewa Integration

How eSewa Works

Configure

nepalpay:
  esewa:
    secret-key:   ${ESEWA_SECRET_KEY}
    product-code: ${ESEWA_PRODUCT_CODE}
    success-url:  ${ESEWA_SUCCESS_URL}
    failure-url:  ${ESEWA_FAILURE_URL}
    sandbox: true    # false for production

    # Optional retry (applies to checkStatus() inside verifyCallback)
    retry:
      enabled: true
      max-attempts: 3
      initial-delay-ms: 500
      multiplier: 2.0
      max-delay-ms: 5000

buildFormPayload()

Simple overload — amount only

// Generate a unique UUID for this transaction
String uuid = EsewaClient.generateTransactionUuid();

// ✅ Save uuid to DB BEFORE returning payload to frontend
orderRepo.saveUuid(orderId, uuid);

// eSewa uses NPR directly — NOT paisa like Khalti
EsewaFormPayload payload =
    esewaClient.buildFormPayload(
        new BigDecimal("100.00"),   // NPR 100
        uuid
    );

// Return payload to frontend — they will POST it

Full overload — with charges

EsewaFormPayload payload =
    esewaClient.buildFormPayload(
        new BigDecimal("100.00"),   // base amount NPR
        new BigDecimal("10.00"),    // tax NPR (null = zero)
        uuid,
        new BigDecimal("5.00"),     // service charge NPR (null = zero)
        new BigDecimal("0.00")      // delivery charge NPR (null = zero)
    );
// totalAmount = 100 + 10 + 5 + 0 = 115.00

EsewaFormPayload fields

Frontend Form Submission

Your frontend must POST all payload fields as a form submission to payload.formActionUrl().

// Angular / TypeScript example
submitEsewaPayment(payload: EsewaFormPayload): void {
    const form = document.createElement('form');
    form.method = 'POST';
    form.action = payload.form_action_url;

    const fields = {
        amount:                 payload.amount,
        tax_amount:             payload.tax_amount,
        total_amount:           payload.total_amount,
        transaction_uuid:       payload.transaction_uuid,
        product_code:           payload.product_code,
        product_service_charge: payload.product_service_charge,
        product_delivery_charge:payload.product_delivery_charge,
        success_url:            payload.success_url,
        failure_url:            payload.failure_url,
        signed_field_names:     payload.signed_field_names,
        signature:              payload.signature
    };

    Object.entries(fields).forEach(([key, value]) => {
        const input = document.createElement('input');
        input.type  = 'hidden';
        input.name  = key;
        input.value = value ?? '';
        form.appendChild(input);
    });

    document.body.appendChild(form);
    form.submit();
}

verifyCallback()

eSewa redirects to your success-url with a ?data=BASE64_ENCODED_JSON query parameter. verifyCallback() handles all three steps automatically.

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

    // verifyCallback does all three steps:
    // 1. Decode Base64 → JSON
    // 2. Verify HMAC-SHA256 signature (constant-time)
    // 3. Call eSewa status API
    EsewaClient.EsewaVerificationResult result =
        esewaClient.verifyCallback(data);

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

    // Load order using saved uuid
    String uuid = result.callbackData().transactionUuid();
    orderRepo.markPaid(uuid);

    return ResponseEntity.ok("Payment confirmed");
}

// Handle failure redirect
@GetMapping("/esewa/failed")
public ResponseEntity<String> failed() {
    return ResponseEntity.ok("Payment was canceled or failed");
}

EsewaVerificationResult fields

checkStatus()

Call the eSewa status API directly without going through the callback flow. Useful for:

• Manually checking a payment status
• Background reconciliation jobs
• Handling cases where the callback was missed

// uuid = the transaction_uuid you saved during initiation
// totalAmount = the exact total amount string used during initiation
EsewaStatusResponse status =
    esewaClient.checkStatus(uuid, "100.00");

if (status.isPaymentSuccessful()) {
    // status.status() == "COMPLETE"
    orderRepo.markPaid(uuid);
}

Security Rules

# Correct eSewa flow — all steps required:

1. generateTransactionUuid()   → save to DB
2. buildFormPayload()          → return to frontend
3. Frontend POSTs to eSewa
4. eSewa redirects ?data=BASE64
5. verifyCallback(data)        → all 3 sub-steps automatic
6. isPaymentSuccessful()       → then mark paid

Reactive Usage

Use EsewaReactiveClient from the reactive starter. buildFormPayload() is synchronous (no HTTP). verifyCallback() and checkStatus() return Mono.

Build payload — synchronous

// Synchronous — no Mono needed
public EsewaFormPayload startEsewa(
        String orderId, BigDecimal amount) {

    String uuid = EsewaReactiveClient.generateTransactionUuid();
    orderRepo.saveUuid(orderId, uuid); // save first!

    return esewaReactiveClient.buildFormPayload(amount, uuid);
}

Verify callback — reactive

public Mono<Boolean> verifyEsewa(String encodedData) {
    return esewaReactiveClient.verifyCallback(encodedData)
        .map(EsewaReactiveClient.EsewaVerificationResult
                ::isPaymentSuccessful);
}

Check status directly — reactive

public Mono<Boolean> checkEsewaStatus(
        String uuid, String totalAmount) {
    return esewaReactiveClient.checkStatus(uuid, totalAmount)
        .map(EsewaStatusResponse::isPaymentSuccessful);
}

eSewa Status Values

Sandbox Credentials