Configuration

Khalti Properties

KhaltiClient (and KhaltiReactiveClient) is created when nepalpay.khalti.secret-key is present.

eSewa Properties

EsewaClient (and EsewaReactiveClient) is created when nepalpay.esewa.secret-key is present.

ConnectIPS Properties

Fonepay Properties

Retry Configuration

nepalpay:
  khalti:
    retry:
      enabled: true           # opt-in — false by default
      max-attempts: 3         # retries after first failure (4 total calls)
      initial-delay-ms: 500   # wait 500ms before first retry
      multiplier: 2.0         # 500 → 1000 → 2000ms
      max-delay-ms: 5000      # never wait more than 5 seconds

What gets retried

Retry Properties Reference

Exponential backoff with jitter

# initial-delay-ms=500, multiplier=2.0, max-delay-ms=5000, max-attempts=3

First call  → fails 5xx → wait ~500ms  (±10% jitter)
Retry 1     → fails 5xx → wait ~1000ms (500 × 2.0)
Retry 2     → fails 5xx → wait ~2000ms (1000 × 2.0)
Retry 3     → fails 5xx → throw exception — no more retries

# Jitter: ±10% random offset prevents thundering herd
# All clients retry on 4xx → never

Micrometer Metrics (v1.2.0)

Add spring-boot-starter-actuator — metrics register automatically. Opt-out with:

nepalpay:
  metrics:
    enabled: false  # opt-out — true by default when Actuator present

Example Grafana queries

# Khalti P99 initiation latency
histogram_quantile(0.99,
  rate(nepalpay_khalti_payment_initiate_duration_seconds_bucket[5m])
)

# eSewa fraud alert — HMAC mismatch spike
rate(nepalpay_esewa_callback_signature_failed_total[5m]) > 5

# ConnectIPS retry rate
rate(nepalpay_connectips_retry_attempts_total[5m])

Actuator Health Indicators (v1.2.0)

Each configured gateway exposes its own health component. Opt-out with:

nepalpay:
  health:
    enabled: false  # opt-out — true by default when Actuator present

Example response

GET /actuator/health

{
  "status": "UP",
  "components": {
    "nepalpayKhalti": {
      "status": "UP",
      "details": { "gateway": "Khalti", "mode": "SANDBOX", "configured": true }
    },
    "nepalpayEsewa": {
      "status": "UP",
      "details": { "gateway": "eSewa", "mode": "SANDBOX", "configured": true }
    },
    "nepalpayConnectIps": {
      "status": "UP",
      "details": { "pfxLoaded": true, "configured": true }
    },
    "nepalpayFonepay": {
      "status": "UP",
      "details": { "note": "URL redirect — no HTTP calls", "configured": true }
    }
  }
}

Sandbox Configuration

nepalpay:

  khalti:
    secret-key:  ${KHALTI_SECRET_KEY:test_key_placeholder}
    return-url:  http://localhost:8080/api/khalti/callback
    website-url: http://localhost:8080
    sandbox: true

  esewa:
    # Sandbox: ID=9806800001 Password=Nepal@123 MPIN=1122 Token=123456
    secret-key:   ${ESEWA_SECRET_KEY:8gBm/:&EnhH.1/q}
    product-code: EPAYTEST
    success-url:  http://localhost:8080/api/esewa/callback
    failure-url:  http://localhost:8080/api/esewa/failed
    sandbox: true

  fonepay:
    merchant-code: ${FONEPAY_MERCHANT_CODE}
    secret-key:    ${FONEPAY_SECRET_KEY}
    return-url:    http://localhost:8080/api/fonepay/callback
    sandbox: true

  # ConnectIPS — uncomment when you have NCHL UAT credentials
  # connectips:
  #   merchant-id:     ${CONNECTIPS_MERCHANT_ID}
  #   app-id:          ${CONNECTIPS_APP_ID}
  #   app-name:        ${CONNECTIPS_APP_NAME}
  #   app-password:    ${CONNECTIPS_APP_PASSWORD}
  #   pfx-path:        ${CONNECTIPS_PFX_PATH}
  #   pfx-password:    ${CONNECTIPS_PFX_PASSWORD}
  #   timeout-seconds: 30
  #   sandbox: true

Production Configuration

nepalpay:

  khalti:
    secret-key:  ${KHALTI_SECRET_KEY}
    return-url:  https://yourapp.com/api/khalti/callback
    website-url: https://yourapp.com
    sandbox: false                      # ← production

  esewa:
    secret-key:   ${ESEWA_SECRET_KEY}
    product-code: ${ESEWA_PRODUCT_CODE} # ← your real merchant code
    success-url:  https://yourapp.com/api/esewa/callback
    failure-url:  https://yourapp.com/payment/failed
    sandbox: false                      # ← production

  connectips:
    merchant-id:     ${CONNECTIPS_MERCHANT_ID}
    app-id:          ${CONNECTIPS_APP_ID}
    app-name:        ${CONNECTIPS_APP_NAME}
    app-password:    ${CONNECTIPS_APP_PASSWORD}
    pfx-path:        ${CONNECTIPS_PFX_PATH}
    pfx-password:    ${CONNECTIPS_PFX_PASSWORD}
    timeout-seconds: 30
    sandbox: false                      # ← production

  fonepay:
    merchant-code: ${FONEPAY_MERCHANT_CODE}
    secret-key:    ${FONEPAY_SECRET_KEY}
    return-url:    https://yourapp.com/api/fonepay/callback
    sandbox: false                      # ← production

Environment Variables

# Khalti
KHALTI_SECRET_KEY=live_secret_key_here
KHALTI_RETURN_URL=https://yourapp.com/api/khalti/callback
YOUR_WEBSITE_URL=https://yourapp.com

# eSewa
ESEWA_SECRET_KEY=your_esewa_secret_key
ESEWA_PRODUCT_CODE=your_merchant_code
ESEWA_SUCCESS_URL=https://yourapp.com/api/esewa/callback
ESEWA_FAILURE_URL=https://yourapp.com/payment/failed

# ConnectIPS
CONNECTIPS_MERCHANT_ID=550
CONNECTIPS_APP_ID=MER-550-APP-1
CONNECTIPS_APP_NAME=YourApp
CONNECTIPS_APP_PASSWORD=your_app_password
CONNECTIPS_PFX_PATH=file:/app/CREDITOR.pfx
CONNECTIPS_PFX_PASSWORD=your_pfx_password

# Fonepay
FONEPAY_MERCHANT_CODE=your_merchant_pid
FONEPAY_SECRET_KEY=your_fonepay_key
FONEPAY_RETURN_URL=https://yourapp.com/api/fonepay/callback

Override Beans

Every NepalPay bean uses @ConditionalOnMissingBean. Define your own bean and NepalPay steps aside automatically.

@Configuration
public class MyPaymentConfig {

    // Override KhaltiClient — NepalPay's auto-configured bean is skipped
    @Bean
    public KhaltiClient customKhaltiClient(
            NepalPayProperties props,
            RestClient.Builder builder) {
        return new KhaltiClient(props.khalti(), builder);
    }
}

Works for all four clients: KhaltiClient, EsewaClient, ConnectIpsClient, FonepayClient — and their reactive equivalents.