Configuration — NepalPay

Khalti Properties

The KhaltiClient bean is created automatically when nepalpay.khalti.secret-key is present in your configuration.

Property	Required	Default	Description
`nepalpay.khalti.secret-key`	✅	—	Your Khalti secret key from the merchant dashboard. Creates `KhaltiClient` bean when present.
`nepalpay.khalti.return-url`	✅	—	URL Khalti redirects to after payment. Example: `https://yourapp.com/api/payment/khalti/callback`
`nepalpay.khalti.website-url`	✅	—	Your merchant website URL. Example: `https://yourapp.com`
`nepalpay.khalti.sandbox`	No	`true`	`true` → dev.khalti.com (sandbox) `false` → khalti.com (production)
`nepalpay.khalti.timeout-seconds`	No	`10`	HTTP timeout in seconds for Khalti API calls.

eSewa Properties

The EsewaClient bean is created automatically when nepalpay.esewa.secret-key is present.

Property	Required	Default	Description
`nepalpay.esewa.secret-key`	✅	—	eSewa HMAC-SHA256 secret key. Creates `EsewaClient` bean when present. Sandbox value: `8gBm/:&EnhH.1/q`
`nepalpay.esewa.product-code`	✅	—	eSewa merchant/product code. Sandbox: `EPAYTEST` Production: your real merchant code. ⚠️ Most common cause of sandbox-to-production breakage.
`nepalpay.esewa.success-url`	✅	—	URL eSewa redirects to on successful payment. Example: `https://yourapp.com/api/payment/esewa/callback`
`nepalpay.esewa.failure-url`	✅	—	URL eSewa redirects to on failed or canceled payment. Example: `https://yourapp.com/payment/failed`
`nepalpay.esewa.sandbox`	No	`true`	`true` → rc-epay.esewa.com.np (sandbox) `false` → epay.esewa.com.np (production)
`nepalpay.esewa.timeout-seconds`	No	`10`	HTTP timeout in seconds for eSewa status API calls.

ConnectIPS Properties

⚠️ Merchant registration required. ConnectIPS requires registration with NCHL before use. Contact connectips@nchl.com.np or your bank to register. You will receive a merchant ID, app credentials, and a CREDITOR.pfx certificate file.

Property	Required	Default	Description
`nepalpay.connectips.merchant-id`	✅	—	Integer merchant ID assigned by NCHL. Example: `550`
`nepalpay.connectips.app-id`	✅	—	Application ID from NCHL. Example: `MER-550-APP-1`
`nepalpay.connectips.app-name`	✅	—	Application name from NCHL. Example: `MyStore`
`nepalpay.connectips.app-password`	✅	—	Application password used for HTTP Basic Auth on the validation API.
`nepalpay.connectips.pfx-path`	✅	—	Path to your CREDITOR.pfx certificate file. Example: `file:/app/CREDITOR.pfx` ⚠️ Never commit this file to Git.
`nepalpay.connectips.pfx-password`	✅	—	Password for the CREDITOR.pfx file.
`nepalpay.connectips.sandbox`	No	`true`	`true` → uat.connectips.com (UAT) `false` → connectips.com (production)

Sandbox Configuration

Use this for local development. Safe to commit (no production keys).

nepalpay:

  khalti:
    # Get test key from: https://test-admin.khalti.com
    secret-key:  ${KHALTI_SECRET_KEY:test_secret_key_placeholder}
    return-url:  http://localhost:8080/api/payment/khalti/callback
    website-url: http://localhost:8080
    sandbox: true

  esewa:
    # Official eSewa sandbox credentials
    # 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/payment/esewa/callback
    failure-url:  http://localhost:4200/payment/failed
    sandbox: true

  # ConnectIPS — uncomment when you have NCHL 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}
  #   sandbox: true

Production Configuration

🔴 Never hardcode production keys. Always use environment variables. Never commit real credentials to Git.

nepalpay:

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

  esewa:
    secret-key:   ${ESEWA_SECRET_KEY}
    product-code: ${ESEWA_PRODUCT_CODE}     # ⚠️ must be your real merchant code!
    success-url:  https://yourapp.com/api/payment/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}    # e.g. file:/app/CREDITOR.pfx
    pfx-password: ${CONNECTIPS_PFX_PASSWORD}
    sandbox: false                          # ← production!

Environment Variables

Set these in your deployment environment. Never put real values in application.yml or commit them to version control.

# ── Khalti ─────────────────────────────────────────────
KHALTI_SECRET_KEY=live_secret_key_your_key_here
KHALTI_RETURN_URL=https://yourapp.com/api/payment/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/payment/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=YourAppName
CONNECTIPS_APP_PASSWORD=your_app_password
CONNECTIPS_PFX_PATH=file:/app/CREDITOR.pfx
CONNECTIPS_PFX_PASSWORD=your_pfx_password

Platform-specific setup

Platform	How to set environment variables
Render	Dashboard → Your Service → Environment → Add variables
Railway	Project → Variables → Add variable
Heroku	`heroku config:set KHALTI_SECRET_KEY=xxx`
Docker	`docker run -e KHALTI_SECRET_KEY=xxx yourimage`
Local dev	`.env` file (add to `.gitignore`!) or IntelliJ → Run Configuration → Environment variables

Override Beans

Every NepalPay bean uses @ConditionalOnMissingBean. If you define your own bean of the same type, NepalPay's auto-configured bean is skipped entirely.

@Configuration
public class MyPaymentConfig {

    // Defining this bean means NepalPay's KhaltiClient is NOT created.
    // Useful when you need custom configuration, logging, or proxying.
    @Bean
    public KhaltiClient customKhaltiClient(
            NepalPayProperties props,
            RestClient.Builder builder) {
        return new KhaltiClient(props.khalti(), builder);
    }
}

This pattern also works for EsewaClient and ConnectIpsClient.