NS App – ERPNext Custom Integrations

Overview

NS App is a custom ERPNext application that:

Adding a manual payment form using Collect.js
Processing secure card payments through NMI
Optionally saving payment methods to the NMI Customer Vault
Storing the returned vault ID on the ERPNext Customer for future autopay use

This part of the app is designed to integrate directly into the Sales Invoice workflow.

Features
Secure card entry using NMI Collect.js (tokenization)
Manual payment dialog inside ERPNext
Optional “Subscribe to Autopay” checkbox
Conditional vault creation in NMI
Storage of customer_vault_id in ERPNext Customer
Configurable enable/disable of autopay via site_config.json

Requirements
ERPNext / Frappe Bench environment
NMI gateway account
Collect.js enabled in NMI
Access to modify site_config.json

Installation
1. Get the app
cd ~/frappe-bench
bench get-app git@git.nsinnovations.net:nsinnovations/ns_erpnext_app.git --skip-assets
2. Install on site
bench --site "site name" install-app ns_app
3. Build and restart
bench build
bench restart

Configuration

Edit site configuration:
nano ~/frappe-bench/sites/site-name/site_config.json

Add:

{
  "nmi_security_key": "your_nmi_security_key",
  "enable_autopay_signup": 0
}
Notes
nmi_security_key is required for all payment and vault operations
enable_autopay_signup controls whether the checkbox actually triggers vault creation
Frontend Behavior

The payment dialog includes:

Cardholder Name
Billing ZIP
Secure card fields via Collect.js
“Subscribe to Autopay” checkbox

If the checkbox is selected and autopay is enabled in config, the backend will attempt to create a vault entry.

Backend Flow:
Payment
Collect.js generates a payment token
Token is sent to backend API
Backend sends transaction to NMI
Payment is processed
Autopay (Optional)

If enabled and selected:

Backend sends customer_vault=add_customer request to NMI
Uses the same payment token
Parses response for customer_vault_id
Saves ID to ERPNext Customer
Example Vault Request
vault_data = {
    "security_key": frappe.conf.get("nmi_security_key"),
    "customer_vault": "add_customer",
    "payment_token": token,
    "first_name": first_name,
    "last_name": last_name,
    "zip": billing_zip
}
Error Handling

Vault creation is wrapped in a try/except block to prevent payment failures:

try:
    if int(save_autopay or 0):
        # vault logic
        pass
except Exception:
    frappe.log_error(frappe.get_traceback(), "Autopay Vault Error")
Testing Strategy

Before enabling in production:

Set in site_config.json:

"enable_autopay_signup": 0
Verify:
Payments process correctly
No vault entries are created

Enable autopay:

"enable_autopay_signup": 1
Test:
Checkbox unchecked → no vault
Checkbox checked → vault created and saved
Deployment Notes
Do not expose autopay functionality until fully tested
Keep enable_autopay_signup disabled in production until ready
Always run:
bench build
bench restart


Troubleshooting:
1. App not found

Ensure app is in apps.txt:

nano ~/frappe-bench/sites/apps.txt

Add:

ns_app

2. ModuleNotFoundError

Ensure app is installed in environment:

./env/bin/pip install -e apps/ns_app
Asset build errors

Skip during install:

bench get-app <repo> --skip-assets

Then fix frontend paths before running bench build.

Vault not saving

Check logs:

frappe.log_error(response.text, "Vault Response")

Verify:

customer_vault_id is returned
Security key is correct
File Structure
apps/ns_app/
├── ns_app/
│   ├── api/
│   │   └── payments.py
│   ├── public/
│   │   └── js/
│   └── hooks.py
├── setup.py
├── pyproject.toml
└── MANIFEST.in

Security Notes: 
Never store raw card data
Always use Collect.js tokenization
Keep nmi_security_key private
Use HTTPS for all requests