ConnectIPS Integration

Requirements

You will need from NCHL:

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

To register, contact your bank or NCHL directly: connectips@nchl.com.np

How ConnectIPS Works

Backend: builds ConnectIpsFormPayload
         (RSA-SHA256 signed with your .pfx private key)
    ↓ return to frontend
Frontend: POSTs form to ConnectIPS gateway URL
    ↓
User completes bank transfer on ConnectIPS
    ↓
ConnectIPS redirects to your callback URL
    ↓
⚠️  DO NOT trust this redirect alone!
    ↓
Backend: calls validateTransaction() with Basic Auth
         (uses appId:appPassword for HTTP Basic Auth)
    ↓
✅ mark order as paid when status = "SUCCESS"

Key Difference from Khalti and eSewa

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}        # e.g. "MyStore"
    app-password: ${CONNECTIPS_APP_PASSWORD}
    pfx-path:     ${CONNECTIPS_PFX_PATH}       # e.g. file:/app/CREDITOR.pfx
    pfx-password: ${CONNECTIPS_PFX_PASSWORD}
    sandbox: true    # false for production

buildFormPayload()

@Service
@RequiredArgsConstructor
public class PaymentService {

    private final ConnectIpsClient connectIpsClient;

    public ConnectIpsFormPayload startPayment(String orderId, long amountNPR) {
        String txnId = "TXN-" + orderId + "-" + System.currentTimeMillis();

        // ConnectIPS uses PAISA — multiply by 100
        long amountPaisa = amountNPR * 100L;

        // Store txnId in your database before returning!
        ConnectIpsFormPayload payload = connectIpsClient.buildFormPayload(
            txnId,
            amountPaisa,
            orderId,           // referenceId — your order ID
            "Order payment",   // remarks
            "NepalPay"         // particulars
        );

        return payload;
        // Return to frontend → frontend POSTs form to payload.formActionUrl()
    }
}

Frontend Form Submission

ConnectIPS uses the same form-submission pattern as eSewa. POST all payload fields to form_action_url.

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

    const fields = ['MERCHANTID', 'APPID', 'APPNAME', 'TXNID',
        'TXNDATE', 'TXNCRNCY', 'TXNAMT', 'REFERENCEID',
        'REMARKS', 'PARTICULARS', 'TOKEN'];

    fields.forEach(field => {
        const input = document.createElement('input');
        input.type = 'hidden';
        input.name = field;
        input.value = (payload as any)[field.toLowerCase()] ?? '';
        form.appendChild(input);
    });

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

validateTransaction()

// ConnectIPS redirects to your callback URL after payment
// Always verify server-side — never trust redirect alone!

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

    ConnectIpsValidateResponse response =
        connectIpsClient.validateTransaction(txnId, referenceId, txnAmt);

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

    // ✅ Safe to mark order as paid
    orderRepo.markPaid(referenceId);
    return ResponseEntity.ok("Payment successful");
}

Security Notes