Nomod Links API

Create and list payment links via Nomod and reconcile them into internal payments once paid.

Base URL

/api/nomodLinks

Authentication & Roles

Cookie-based JWT (see Auth docs). All routes require authentication and one of the following roles:

• admin
• finance
• sales

Company scoping: If the requester is not super-admin, results are scoped to the user’s allowedCompanies.

Content Types

• Requests: application/json
• Responses: application/json

---

Object model

NomodLink

Field	Type	Description
id	number	Internal identifier of the link record.
createdBy	string	Name of the user who created the link.
createdAt	string	ISO datetime when the link was created.
amount	number	Amount in AED.
link	string	Public Nomod payment URL.
clientId	number	Client id this link is associated with.
leadClient	string	Client name.
status	string	One of pending, paid.
company	string	Company name.

Note: status is stored on our side and updated by the background reconciliation job (see Reconciliation below).

---

Endpoints

List links

GET /api/nomodLinks

List all Nomod links visible to the requester. Optionally filter by company.

Query parameters

Name	Type	Required	Description
company	number	No	Company id to filter by. If omitted, results are restricted to the requester’s allowed companies (unless super-admin).

Response — 200 OK

[
  {
    "id": 12,
    "createdBy": "Jane Doe",
    "createdAt": "2025-02-10T09:44:22.000Z",
    "amount": 1500,
    "link": "https://nomod.page/pay/abc123",
    "clientId": 87,
    "leadClient": "Ahmed Ali",
    "status": "pending",
    "company": "MyHomePlan LLC"
  }
]

Errors

• 401 Unauthorized — missing/invalid auth
• 500 Internal Server Error — unexpected error fetching links

cURL

curl -X GET \
  -b "token=<jwt>" \
  "https://<host>/api/nomodLinks?company=1"

---

Create a payment link

POST /api/nomodLinks

Creates a Nomod payment link and stores it internally.

Request body

{
  "amount": 1500,
  "company": 1,
  "clientId": 87
}

Field	Type	Required	Notes
amount	number	Yes	Amount in AED.
company	number	Yes	Company id.
clientId	number	Yes	Associated client id.

Behavior

• Performs POST https://api.nomod.com/v1/links with the payload:
  • currency: "AED"
  • items: [{ name: "fees", amount: "<amount>", quantity: 1 }]
  • title: "Fees Payment"
  • Tips/discounts/shipping disabled; success_url/failure_url not set in code.
• Requires environment variable NOMOD_API_KEY to be present.
• On success, persists a row in nomod_links table with the returned id, url, amount, company, clientId, createdBy and returns the url.

Response — 200 OK

{ "link": "https://nomod.page/pay/abc123" }

Errors

• 400 Bad Request — missing one of amount, company, or clientId
• 500 Internal Server Error — failure calling Nomod or persisting the link

cURL

curl -X POST "https://<host>/api/nomodLinks" \
  -H "Content-Type: application/json" \
  -b "token=<jwt>" \
  -d '{
    "amount": 1500,
    "company": 1,
    "clientId": 87
  }'

---

Reconciliation (background job)

A background process periodically checks Nomod for charges and updates our records.

• For each nomod_links record, calls GET https://api.nomod.com/v1/charges/{linkId} with NOMOD_API_KEY.
• If a link is currently pending and Nomod responds with status: "paid":
  1. Update the link’s status to paid.
  2. Insert an internal payments row with:
     • accountType: "nomod"
     • paymentType: "income"
     • amount from the link
     • company, clientId, createdBy from the link
     • paymentDate = now

Idempotency: The job updates only when a pending link is observed as paid, so re-running is safe.

---

Security & operational notes

• Ensure NOMOD_API_KEY is configured in the server environment.
• Consider adding success_url / failure_url to Nomod link creation if you want to route users back to the app.
• Non–super-admin users are restricted to their allowedCompanies when listing links.
• Current implementation uses a global NOMOD_API_KEY (not per-company). If per-company tokens are desired, extend the schema and selection logic accordingly.

---

Error model

All endpoints may return:

{ "message": "<human-readable description>" }

---

Changelog

• 2025-02- Initial documentation.