ns_erpnext_app/docs/DESIGN_SPEC.md

NS App — Design Specification

Status: Living document · reverse-engineered from the current implementation (branch main, commit 4e0acde). Owner: NS Innovations Engineering Applies to: ns_app Frappe/ERPNext custom application.

This spec describes the intended behavior, contracts, and design constraints of NS App so the system can be maintained, extended, and re-implemented consistently. For a component tour see ARCHITECTURE.md.

---

1. Goals & non-goals

Goals

• Let staff take a card payment without leaving the Sales Invoice, and have the ledger (Payment Entry) update automatically and correctly.
• Support saved cards (AutoPay) for frictionless repeat/recurring billing.
• Allow one card charge to settle multiple outstanding invoices.
• Keep the app PCI-light: card data never transits ERPNext.
• Speed up customer onboarding with a single guided dialog that produces a complete, linked Customer/Contact/Address.

Non-goals

• The app is not a general payment-gateway abstraction — it targets NMI specifically.
• It does not manage subscriptions/scheduling itself; "AutoPay" here means a vaulted card that can be charged on demand or via webhook, not a scheduler.
• It does not own the custom-field schema on Customer (assumed present).

---

2. Personas & primary use cases

Persona	Use case
AR / billing clerk	Opens an unpaid invoice, clicks Run Payment, keys the customer's card, optionally saves it for AutoPay.
Clerk (repeat customer)	Opens an unpaid invoice for a customer with AutoPay; confirms a one-click charge of the saved card.
Clerk (bulk settle)	Charges one card for several of a customer's open invoices at once.
Sales user	Creates a new customer from any link field via the guided Quick Entry dialog.
Payment gateway (system)	Posts an async confirmation to the webhook, which reconciles a Payment Entry.

---

3. Functional requirements

3.1 Payment button visibility

• Shown only when: docstatus == 1 (submitted) and a customer is set and outstanding_amount > 0.
• When outstanding_amount <= 0: show a green Paid dashboard indicator, no button.
• Otherwise: show a red Unpaid indicator plus Run Payment under Actions.

3.2 AutoPay-vs-manual branching

• On Run Payment, call check_autopay(customer).
• If autopay_enabled and autopay_id present → confirm dialog → charge the vaulted card (run_autopay_payment).
• Else → open the manual card-entry dialog.

3.3 Manual payment dialog

• Collects: first name, last name, company (optional), billing ZIP.
• Renders Collect.js inline fields for card number / expiry / CVV.
• Prefills name/company/ZIP from the invoice's customer where possible.
• Optional Save for Auto Pay checkbox.
• Optional Pay Additional Invoices toggle → loads the customer's other open invoices (get_unpaid_invoices) into a selectable table with a running selected-total and a select-all control.
• Pay button label reflects the current selected total.

3.4 Charge semantics (server)

run_token_payment must:

1. Resolve invoice_names (JSON string → list; fall back to [invoice]).
2. Force save_autopay = 0 when enable_autopay_signup is falsy.
3. Load every selected invoice; reject if any is not submitted or already fully paid.
4. Sum outstanding_amount across selected invoices as the charge amount.
5. Generate a unique orderid (<invoice-label>-<hash>).
6. POST a type=sale transaction to NMI with the payment_token.
7. On response == "1":
   • Dedup: if a Payment Entry already exists with reference_no == transactionid, return duplicate: true and do nothing.
   • Else create one Payment Entry allocated across all selected invoices.
   • If vaulting requested and a vault_id returned, persist AutoPay fields on the Customer.
8. On failure: return {success: False, error} and create no Payment Entry.

3.5 AutoPay charge (server)

run_autopay_payment → call_payment_api:

• Requires custom_auto_pay_status and custom_auto_pay_id.
• POSTs type=sale with customer_vault_id (no token, no card entry).
• Derives mode_of_payment from the response type (check → ACH, else Credit Card).
• Same dedup + create_payment_entry path.

3.6 Payment Entry creation (invariant)

create_payment_entry(invoices[], transaction_id, mode_of_payment):

• Idempotent on reference_no == transaction_id.
• paid_to = "ENB Bank Account - NIL" for ACH/Credit Card, else the company's default cash account; throw if none resolved.
• payment_type = Receive, party = customer of the first invoice.
• One references row per invoice, allocated_amount = outstanding_amount.
• Insert and submit with ignore_permissions=True.

3.7 Webhook

crystalclear_webhook (allow_guest=True):

• Ignore unless response == "1".
• Map orderid → Sales Invoice, create a Payment Entry via the shared path.
• Always return a short string ack.

3.8 Customer Quick Entry

• Override ERPNext's Customer quick-entry dialog globally, preserving the originating after_insert link-field callback.
• create_customer_full requires: customer_name, customer_type, customer_group, mobile_no, address_line1, pincode, country.
• Enforce: if custom_auto_pay_enabled then custom_auto_pay_id required.
• Create Customer + Contact + Address in a single transaction; rollback on any error and log.
• Return the new customer name; caller writes it back into the triggering field via after_insert({ name }).

---

4. Interface contracts (server API)

All are @frappe.whitelist() unless noted. Return values are dicts consumed by frappe.call on the client.

Method	Args	Returns
check_autopay	customer	{autopay_enabled: bool, autopay_id: str|None}
get_unpaid_invoices	customer	[{name, posting_date, customer_name, outstanding_amount}]
run_token_payment	invoice, token, invoice_names?, first_name?, last_name?, company?, billing_zip?, save_autopay?	{success, transaction_id?, vault_id?, duplicate?, error?}
run_autopay_payment	invoice	{success, message, transaction_id} or throws
save_to_autopay	customer, token, first_name?, last_name?, company?, billing_zip?	{success, vault_id?} / {success:False, error}
crystalclear_webhook	form dict (guest)	"ok" / "ignored"
create_customer_full	**data (see 3.8)	new customer name (str) or throws

Error conventions

• Validation / preconditions → frappe.throw (surfaces as a msgprint).
• Gateway / recoverable → {success: False, error: <message>}.
• Post-charge Payment Entry failures are caught and logged (the charge already succeeded) — they must not raise to the client.

---

5. Design constraints & rationale

Constraint	Rationale
Card fields via Collect.js iframes only	Keep PAN/CVV out of ERPNext → minimal PCI scope.
Dedup on gateway transactionid	The charge is the source of truth; retries/webhook races must not double-post to the ledger.
Charge-then-record ordering, with PE errors logged not raised	Never lose money already captured at the gateway; reconcile a missing PE manually rather than re-charging.
enable_autopay_signup feature flag	Ship vaulting code dark; enable per-site only after testing.
Preserve after_insert in quick entry	Only correct way to resume the originating document flow without racing the create transaction.
Single DB transaction in create_customer_full	Never leave an orphan Customer without Contact/Address.

---

6. Idempotency, concurrency & failure modes

• Double-click / double-submit: client guards with window.ns_payment_processing; server guards with the reference_no dedup.
• Charge succeeds, PE fails: logged under PAYMENT ENTRY FAILURE AFTER SUCCESSFUL CHARGE; invoice stays unpaid in ERPNext until reconciled. Recovery: re-run create_payment_entry using the logged transaction_id (idempotent).
• Webhook after interactive PE: dedup prevents a second PE.
• Gateway unreachable: returns a generic error; no PE created.
• Multi-invoice partial validity: if any selected invoice is unpaid-invalid (not submitted / zero balance) the whole request is rejected before charging.

---

7. Security requirements

• nmi_security_key server-side only (site_config.json); never sent to the client.
• HTTPS for every outbound gateway call.
• Store only vault IDs, never card data.
• Recommended hardening (not yet implemented):
  • Authenticate the webhook (shared secret / signature) before creating PEs.
  • Move the Collect.js tokenization key and paid_to account into config.
  • Scrub gateway response logging to guarantee no PAN/PII is written.
  • Rate-limit / permission-check payment endpoints.

---

8. Open questions / future work

• Should AutoPay include a scheduler (true recurring billing) rather than on-demand vault charges only?
• Ship the Customer custom_* fields as fixtures so installs are self-contained.
• Consolidate custom.js and customer_quick_entry.js.
• Make paid_to company-aware instead of the hard-coded ENB account.
• Add automated tests around create_payment_entry idempotency and multi-invoice allocation.

---

9. Acceptance criteria (smoke test)

1. Submitted unpaid invoice shows Run Payment; paid invoice shows Paid.
2. Manual charge with a test card creates exactly one submitted Payment Entry; invoice outstanding goes to 0.
3. Repeating the same gateway transaction (webhook replay) creates no second PE.
4. AutoPay customer: Run Payment → confirm → one-click charge succeeds.
5. Multi-invoice: selecting N invoices produces one PE with N allocations summing to the charged amount.
6. Quick Entry creates a linked Customer/Contact/Address and populates the originating link field.
7. With enable_autopay_signup = 0, checking Save for Auto Pay creates no vault entry.