proxmox/docs/04-configuration/OMNL_DEPOSITS_PLAN.md

OMNL Fineract — Plan: Adding All Deposits

Last updated: 2026-02-10
Tenancy: https://omnl.hybxfinance.io/
Related: OMNL_FINERACT_CONFIGURATION.md

---

1. Objective

Add all deposits to the OMNL tenancy in Fineract. This can mean one or more of:

• Savings accounts — Create and/or activate savings accounts for clients, then post deposit transactions.
• Fixed deposit accounts — Create, approve, activate fixed deposit accounts; initial deposit is part of activation.
• Recurring deposit accounts — Create, approve, activate; then post recurring deposits.
• Bulk import — If deposit data exists in CSV/Excel, plan a script or batch flow to create accounts and post transactions via the API.

---

2. Fineract API Endpoints (Relevant to Deposits)

Resource	Endpoint	Purpose
Savings products	GET /savingsproducts	List product IDs for new savings accounts
Savings accounts	POST /savingsaccounts	Submit new savings application
	GET /savingsaccounts	List applications/accounts
	GET /savingsaccounts/{accountId}	Get one account
	savingsaccounts/{id}?command=approve	Approve application
	savingsaccounts/{id}?command=activate	Activate account (then deposits allowed)
Savings deposit	POST /savingsaccounts/{accountId}/transactions?command=deposit	Post a deposit
Fixed deposit products	GET /fixeddepositproducts	List FD product IDs
Fixed deposit accounts	POST /fixeddepositaccounts	Submit FD application
	fixeddepositaccounts/{id}?command=approve	Approve
	fixeddepositaccounts/{id}?command=activate	Activate (initial deposit in body)
Recurring deposit products	GET /recurringdepositproducts	List RD product IDs
Recurring deposit accounts	POST /recurringdepositaccounts	Submit RD application
	recurringdepositaccounts/{id}/transactions?command=deposit	Post a deposit
Clients	GET /clients	List clients (for linking accounts)
Offices	GET /offices	List offices (already verified)

All requests require:

• Header: Fineract-Platform-TenantId: omnl
• Basic auth: app.omnl + password (from omnl-fineract/.env or root .env).

---

3. Prerequisites (Complete Before Adding Deposits)

• OMNL API accessible (base URL, tenant omnl, Basic auth).
• omnl-fineract/.env created and working (verified with GET /offices).
• Decide deposit type(s): savings only, fixed deposits, recurring, or mix.
• Data source: list of clients + amounts (and product IDs if multiple products), or bulk file (CSV/Excel).
• Products: note savings/fixed/recurring product IDs from GET /savingsproducts, GET /fixeddepositproducts, GET /recurringdepositproducts.

---

4. Suggested Phases

Phase A: Discovery (API only)

1. List products
   • GET /savingsproducts → note id and names.
   • GET /fixeddepositproducts, GET /recurringdepositproducts if using FD/RD.
2. List clients
   • GET /clients → note id and office for each client.
3. List existing savings/deposit accounts
   • GET /savingsaccounts, GET /fixeddepositaccounts, GET /recurringdepositaccounts to see what already exists.

Phase B: Create accounts (if needed)

• For each client that should have a deposit account:
  • Savings: POST /savingsaccounts (clientId, productId, submittedOnDate, etc.) → then approve → activate.
  • Fixed deposit: POST /fixeddepositaccounts → approve → activate (initial deposit in activate payload).
  • Recurring deposit: POST /recurringdepositaccounts → approve → activate.

Use one product ID from Phase A; optionally use a script that reads a list of clients and product IDs from config/CSV.

Phase C: Post deposits

• Savings: For each active savings account, POST /savingsaccounts/{accountId}/transactions?command=deposit with date, amount, paymentTypeId (optional), note (optional).
• Recurring: Same pattern: POST /recurringdepositaccounts/{accountId}/transactions?command=deposit.
• Fixed deposit: Initial deposit is typically part of the activate command; additional deposits may not apply depending on product.

Phase D: Bulk / automated option

• If you have a CSV (e.g. clientId, productId, amount, date):
  • Small script (Node.js or shell + curl) that:
    1. Reads CSV.
    2. For each row: ensure account exists (create/approve/activate if needed), then post deposit.
  • Add idempotency (e.g. skip if deposit for same account+date+amount already exists) and error logging.

---

5. Next Steps (Concrete)

1. Run discovery using omnl-fineract/.env:
   • Script: bash scripts/omnl/omnl-discovery.sh (from repo root). Optionally OUT_DIR=./output/omnl bash scripts/omnl/omnl-discovery.sh to save JSON.
   • Lists: offices, clients, savings products, savings accounts, fixed/recurring deposit products.
2. Document product IDs and (if applicable) client list + desired product per client.
3. Choose approach: manual (curl/Postman) vs. script (Node/shell) for creating accounts and posting deposits.
4. Implement script or runbook for “add all deposits” (per your data source and product choice).
5. Test on one client/account before running for all.

---

6. Example: Single savings deposit (curl)

# Load OMNL env (from repo root or omnl-fineract)
source omnl-fineract/.env

# 1) List savings products (get productId)
curl -s -u "${OMNL_FINERACT_USER}:${OMNL_FINERACT_PASSWORD}" \
  -H "Fineract-Platform-TenantId: ${OMNL_FINERACT_TENANT}" \
  "${OMNL_FINERACT_BASE_URL}/savingsproducts"

# 2) List clients (get clientId)
curl -s -u "${OMNL_FINERACT_USER}:${OMNL_FINERACT_PASSWORD}" \
  -H "Fineract-Platform-TenantId: ${OMNL_FINERACT_TENANT}" \
  "${OMNL_FINERACT_BASE_URL}/clients"

# 3) Post deposit to existing savings account (accountId from GET /savingsaccounts)
curl -s -X POST -u "${OMNL_FINERACT_USER}:${OMNL_FINERACT_PASSWORD}" \
  -H "Fineract-Platform-TenantId: ${OMNL_FINERACT_TENANT}" \
  -H "Content-Type: application/json" \
  -d '{"transactionDate":"2026-02-10","transactionAmount":100.00,"paymentTypeId":1,"note":"Initial deposit"}' \
  "${OMNL_FINERACT_BASE_URL}/savingsaccounts/{accountId}/transactions?command=deposit"

Replace {accountId} and adjust transactionDate, transactionAmount, paymentTypeId as needed. Use dateFormat=yyyy-MM-dd and locale=en in query string if required by your Fineract version.

---

7. References

• Fineract legacy API (savings/deposits)
• OMNL Swagger UI
• OMNL_FINERACT_CONFIGURATION.md — credentials and env
• omnl-fineract/ — local env and scripts directory