ConnectIPS Integration

Requirements

From NCHL you will receive:

• Merchant ID (integer)
• Application ID and Application Name
• Application Password (for HTTP Basic Auth)
• CREDITOR.pfx certificate file
• Password for the .pfx file

How ConnectIPS Works

Configure

nepalpay:
  connectips:
    merchant-id:  ${CONNECTIPS_MERCHANT_ID}    # e.g. 550
    app-id:       ${CONNECTIPS_APP_ID}          # e.g. "MER-550-APP-1"
    app-name:     ${CONNECTIPS_APP_NAME}
    app-password: ${CONNECTIPS_APP_PASSWORD}
    pfx-path:     ${CONNECTIPS_PFX_PATH}        # file:/app/CREDITOR.pfx
    pfx-password: ${CONNECTIPS_PFX_PASSWORD}
    timeout-seconds: 30    # default 30s — increase for slow banks
    sandbox: true          # false for production

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

pfx-path formats

buildFormPayload()

// Generate a unique transaction ID
String txnId = "TXN-" + orderId + "-" + System.currentTimeMillis();

// ✅ Save txnId to DB BEFORE returning to frontend
orderRepo.saveTxnId(orderId, txnId);

ConnectIpsFormPayload payload = connectIpsClient.buildFormPayload(
    ConnectIpsPaymentRequest.builder()
        .txnId(txnId)
        .amountNPR(100L)     // auto-converts NPR → paisa (×100)
        .referenceId(orderId)
        .remarks("Payment for order " + orderId)
        .particulars("MyApp")
        .build()
);

// Return payload to frontend
// Frontend POSTs UPPERCASE field names to payload.formActionUrl()

ConnectIpsPaymentRequest builder fields

Frontend Form Submission

ConnectIPS uses UPPERCASE field names in the form POST. The TOKEN field contains the RSA-SHA256 digital signature — generated on your server using the CREDITOR.pfx private key, which never reaches the frontend. Only the resulting signed token value is sent as a form field.

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

    // ConnectIPS field names are UPPERCASE
    const fields = {
        MERCHANTID:  payload.MERCHANTID,   // merchantId()
        APPID:       payload.APPID,        // appId()
        APPNAME:     payload.APPNAME,      // appName()
        TXNID:       payload.TXNID,        // txnId()
        TXNDATE:     payload.TXNDATE,      // txnDate()
        TXNCRNCY:    payload.TXNCRNCY,     // txnCrncy() — always "NPR"
        TXNAMT:      payload.TXNAMT,       // txnAmt() — in paisa
        REFERENCEID: payload.REFERENCEID,  // referenceId()
        REMARKS:     payload.REMARKS,      // remarks()
        PARTICULARS: payload.PARTICULARS,  // particulars()
        TOKEN:       payload.TOKEN         // RSA-SHA256 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();
}

validateTransaction()

Called after ConnectIPS redirects to your callback URL. Always call this — never trust the redirect.

@GetMapping("/connectips/callback")
public ResponseEntity<String> callback(
        @RequestParam String txnId,
        @RequestParam String referenceId,
        @RequestParam long txnAmt) {

    // ✅ Always validate server-side — never trust redirect params
    ConnectIpsValidateResponse res =
        connectIpsClient.validateTransaction(
            txnId, referenceId, txnAmt);

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

    // ✅ Load order from DB using the saved txnId — NOT referenceId from redirect
    // The redirect referenceId can be attacker-controlled.
    // Use the txnId you saved during buildFormPayload() to look up the order.
    String orderId = orderRepo.findOrderByTxnId(txnId);
    orderRepo.markPaid(orderId);
    return ResponseEntity.ok("Payment confirmed");
}
}

ConnectIpsValidateResponse fields

Test-friendly overload

// Skips RSA signing — useful in tests with mock token
ConnectIpsValidateResponse res =
    connectIpsClient.validateTransactionWithToken(
        referenceId,     // your order/reference ID
        txnAmtPaisa,     // amount in paisa
        "MOCK_TOKEN"     // pre-built token
    );

Security Rules

# .gitignore — add these immediately
*.pfx
CREDITOR.pfx

# application.yml — always load from environment variable
nepalpay:
  connectips:
    pfx-path:     ${CONNECTIPS_PFX_PATH}       # file:/app/CREDITOR.pfx
    pfx-password: ${CONNECTIPS_PFX_PASSWORD}

Reactive Usage

Use ConnectIpsReactiveClient from the reactive starter. buildFormPayload() is synchronous. validateTransaction() returns Mono with both validation and RSA signing wrapped inside Mono.defer().

Build form payload — synchronous

// Synchronous — RSA signing, no HTTP
public ConnectIpsFormPayload startConnectIps(
        String orderId, long amountNPR) {

    String txnId = "TXN-" + orderId + "-"
            + System.currentTimeMillis();
    orderRepo.saveTxnId(orderId, txnId); // save first!

    return connectIpsReactiveClient.buildFormPayload(
        ConnectIpsPaymentRequest.builder()
            .txnId(txnId)
            .amountNPR(amountNPR)
            .referenceId(orderId)
            .build()
    );
}

Validate transaction — reactive

@GetMapping("/connectips/callback")
public Mono<ResponseEntity<String>> callback(
        @RequestParam String txnId,
        @RequestParam String referenceId,
        @RequestParam long txnAmt) {

    // Both validation and RSA signing inside Mono.defer()
    // All errors emitted as Mono.error() — never thrown
    return connectIpsReactiveClient
        .validateTransaction(txnId, referenceId, txnAmt)
        .flatMap(res -> {
            if (!res.isPaymentSuccessful()) {
                return Mono.just(ResponseEntity.badRequest()
                    .body("Not confirmed: " + res.statusDesc()));
            }
            return orderRepo.markPaid(referenceId)
                .thenReturn(ResponseEntity.ok(
                    "Payment confirmed"));
        });
}

How ConnectIPS Differs from Other Gateways