Product Setup

Loan Product Setup Guide

This guide explains how to configure loan products in the Hiana Loans system. Each product type has different requirements — this document covers the configuration layers, recommended settings, and the order of operations.

For employer-backed lending, use the complete employer-backed configuration and acceptance guide. It supersedes abbreviated workflow examples and documents employer-request delivery controls and deployment requirements.

Table of Contents

1. Prerequisites
2. Configuration Layers
3. Product Types Overview
4. Nano Loan Setup
5. Employer-Based Loan Setup
6. Traditional Loan Setup
7. Payment Config & Schedule Shape
8. Floating Rate Config
9. Staged Disbursement
10. Conditional Workflow Steps
11. Post-Setup Verification
12. Configuration Reference

For post-disbursement operations (waivers, top-ups, delinquency pause, re-aging, maker-checker, repricing), see the Loan Servicing Operations Guide.

Prerequisites

Before creating any loan product, ensure the following are in place:

• Jurisdiction — A jurisdiction record must exist first. Products reference a jurisdiction_id. Create jurisdictions via POST /api/v1/jurisdictions.
• Currency Code — Know the ISO 4217 currency code for the product (e.g., KES, USD, ZMW).
• GL Accounts — If using internal accounting, have account codes ready for fee mapping and interest income tracking.
• Permissions — The user creating products must have product.create for creation and product.update for configuration.

Configuration Layers

Each product requires multiple layers of configuration. Create them in this order:

Product Types Overview

The system supports the following product types:

Application workflow contract

Updated: 11 September 2026. Commercial values elsewhere in this guide are illustrative configurations; apply your approved policy. Supported setup requires the UI choice, save schema, backend task type, handler and operational screen to agree.

DISBURSEMENT is a linked workflow after origination, not an application step. The old auto_disburse preset cannot complete the application journey: it expects a loan to exist and creates a request rather than confirming funds transfer. New draft/save validation rejects it under any step key.

The traditional baseline is document upload → document review → KYC → automated credit → underwriting → offer acceptance → consent → signed agreement → final approval. Employer-backed products insert employer approval before credit and use a separate final lender level. Nano products use the nano template, including fraud screening and review. These are unconditional baseline sequences.

For automatic document correction, configure document_review rework to document_upload, reason DOCUMENT_NEEDS_CORRECTION, notes and borrower action required, permitted reviewer roles. The normal document approval endpoints write review audit history and synchronize the currently waiting document task. Generic completion commands cannot substitute for the evidence-producing actions above.

Keep identity policy distinct from onboarding and file approval. Configure document KYC, selfie, face matching and freshness to match the product. A document-only product does not require a selfie unless enabled; selfie-only verification must not enable face matching. IN_REVIEW means required identity work is pending. Neither document approval nor onboarding_status establishes missing face-match evidence.

Save dependent document, consent, approval and other product settings before publication. New applications freeze the published version; publishing does not modify existing task lists. After final approval, origination requires matching accepted terms and a fully signed agreement. Funding, repayment and closure have their own operational checks.

1. Nano Loan

Nano loans are short-term, small-ticket digital loans with minimal documentation and fast approval.

Base Product

POST /api/v1/products

Fees

Credit Risk Config

Approval Config

• Level 1: OPERATIONS_MANAGER, required count 1 in the reference nano setup. Scoring thresholds produce decision evidence; they do not replace the final approval task. See the nano guide for the complete sequence.

Intake Config

Required Documents

Nano loans typically require minimal documents:

• NATIONAL_ID — mandatory, stage: DOCUMENT_UPLOAD

2. Employer-Based Loan

Employer-based loans are repainted through salary deductions, with the employer providing a guarantee.

Base Product

POST /api/v1/products

Fees

Credit Risk Config

Approval Config

• Level 1: EMPLOYER, one authorized employer confirmation.
• Level 2: OPERATIONS_MANAGER, independent final approval for all amounts in the baseline. Configure the employer step, linked employment and active MOU as described in the employer guide.

Intake Config

Required Documents

3. Traditional Loan

Traditional loans are medium to long-term loans with full underwriting, collateral, and multi-level approval chains.

Base Product

POST /api/v1/products

Fees

Credit Risk Config

Approval Config

• Level 1: Loan Officer — all amounts
• Level 2: Operations Manager — amounts > 100,000
• Level 3: Compliance Officer (2 approvers) — amounts > 1,000,000

Intake Config

Required Documents

Payment Config & Schedule Shape

PUT /api/v1/products/:id/config/payment (Product Config → Payment tab) controls repayment behavior beyond the base schedule:

Interest-only and balloon can combine — e.g. 3 interest-only months then amortize 80% of principal with a 20% balloon. Restructuring regenerates a standard equal-annuity schedule and drops the shape.

Floating Rate Config

PUT /api/v1/products/:id/config/floating-rate (Product Config → Floating tab) prices the product as a rate index + spread:

{ "rate_index_id": "<index uuid>", "spread_percent": 6.0, "reprice_strategy": "REDUCE_EMI" }

Requires a rate index and at least one effective rate entry — create/manage them under Admin → Rate Indices (POST /api/v1/rate-indices, POST /api/v1/rate-indices/:id/entries). Origination fails without an effective index value. When a new in-force entry is posted, every active loan on the index reprices and its unpaid installments are rebuilt. Full operating notes: Loan Servicing Operations Guide.

Staged Disbursement

Disbursement Config → enable Staged Disbursement and define ordered tranches (percentage or fixed amount, optional required_documents per stage). Loans on staged products cannot use the single-shot disbursement endpoint — each tranche is released from the loan's funding panel and follows its own verify → process → confirm cycle. Details: Loan Servicing Operations Guide.

Disbursement Checklist

The funding gate is configured per product on the Disbursement Checklist tab (API GET/POST/PUT /api/v1/products/:id/checklist-template). The template defines the items staff must verify before funds release; each loan originated on the product gets a checklist instance from the active template, and required items block release until completed.

Each item: name, type (DOCUMENT_VERIFY, CREDIT_CHECK, FRAUD_CHECK, COMPLIANCE_CHECK, OTHER), required flag, display order. Keep items specific to the product's real release risk — the checklist is the last gate before money moves, not a re-review of evidence earlier stages already produced.

Conditional Workflow Steps

Use unconditional stages for the reference configurations in these guides. Conditions are available for additional policy-specific stages, but must not bypass required identity, employer confirmation, offers, consents, signatures or final approval.

The evaluator supports equals, not_equals, greater_than, less_than, contains and in. A missing field blocks evaluation; it does not mean false. Publication recognizes fields in Form Config plus requested_amount, requested_term, requested_term_unit, purpose, borrower_id, product_id and jurisdiction_id.

Runtime limitation: task progression evaluates the evidence supplied by the completing action. Publication accepting a field does not guarantee that every preceding action supplies it. The simulation endpoint (POST /api/v1/products/{product_id}/config/workflow/simulate) evaluates caller-supplied facts; it is not an end-to-end rehearsal. Test a real application through the exact predecessor before enabling a condition. The baseline templates use no conditions for this reason.

Do not use the former examples that skipped nano offer/consent capture or employer confirmation based on amount. Skipping an offer step does not automatically generate an accepted offer, and returning customers still need the consent/signature evidence required for their application. credit_decision is not a built-in condition field; the credit handler records decision. Automatic routing from failed KYC/fraud checks to a referral stage is not implemented by the current handlers.

Workflow Operations (Rework, Resubmit, Recovery)

Once a workflow is published and applications are flowing, staff can move applications back and forth through the workflow:

Returning Applications Back (Rework)

Staff can send an application back to an earlier step for correction (e.g., if documents are missing during underwriting). This is configured via rework_rules on each step:

• Each rework rule specifies a target_step_key, allowed_roles, reason_codes, and whether borrower_action_required
• When rework is triggered, the application moves to CORRECTION_REQUIRED status
• Compensation handlers can undo side effects of steps being rolled back
• The rework_attempts counter on the target task is incremented

API: POST /api/v1/applications/:id/workflow/rework

Resubmitting After Correction

Once corrections are made, the application is resubmitted to move forward:

• If borrower_action_required: true, the borrower calls the resubmit endpoint
• If borrower_action_required: false, staff with LoanUpdate permission resubmit
• The workflow creates a RESUBMIT transition and returns to active processing

API: POST /api/v1/applications/:id/workflow/resubmit

Available Workflow Actions

The backend provides a single source of truth for what the current actor can perform:

API: GET /api/v1/applications/:id/workflow/actions

Returns applicable complete, rework, and resubmit actions based on the actor's role and the workflow's current state. The frontend should use this endpoint to determine which buttons/actions to show — do not compute the action list client-side. Automated steps and evidence-producing document/identity/assessment/offer/consent/signature stages do not expose a generic completion action.

Recovery Operations

For automated step failures, task reassignment, and other recovery scenarios:

Full documentation: See docs/PRODUCT_WORKFLOW_SETUP_GUIDE.md for complete configuration details, transition types, notifications, borrower workflow state, and pipeline analytics.

Pipeline Analytics

The system provides real-time pipeline monitoring through analytics endpoints:

Key metrics tracked per stage: WIP count, completed/failed/rolled back/reworked counts, and duration percentiles (avg, median, P95).

Collections Pipeline

When loans become delinquent, the collections pipeline automatically manages escalation and agent assignment:

Delinquency Escalation Levels

Collections API

• POST /api/v1/collections/cases — Create a collections case
• GET /api/v1/collections/cases/:id — Retrieve case details
• POST /api/v1/collections/cases/:id/assign — Assign case to an agent

Collections policies also control re-aging (reaging_enabled): when enabled, a delinquent loan that fully cures its past-due amount resets to CURRENT classification. Delinquency can additionally be paused per loan (late fees, escalation and IFRS staging suspend while paused). See the Loan Servicing Operations Guide.

For group-based lending (e.g., employer MOU loans), a default on one loan can trigger a cascade that escalates all related loans to collections.

Full documentation: See docs/PRODUCT_WORKFLOW_SETUP_GUIDE.md → Collections Pipeline section for complete details.

Post-Setup Verification

After configuring all layers, verify the product is correctly set up:

1. Check the Full Product Schema

GET /api/v1/products/:id/schema

This returns the complete ProductSchema combining all configuration layers in one response. Verify that:

• product — base product fields are correct
• form_config — form sections and fields are defined
• intake — KYC and selfie requirements are set
• documents — required documents are listed
• workflow — workflow stages are configured
• guarantor — guarantor requirements are set
• disbursement — disbursement channel is configured
• payment — payment configuration is set
• affordability — affordability rules are defined
• credit_risk — scoring weights and thresholds are correct
• approval — approval chain is defined
• fees — all fees are listed
• rate_tiers — rate tiers if using risk-based pricing

2. Test Product Activation

PUT /api/v1/products/:id

Set is_active: true to make the product available for applications.

3. Verify Frontend Rendering

The frontend reads the product schema and dynamically renders:

• Application form fields (from form_config)
• Document checklist (from documents)
• Workflow stages (from workflow)
• Fee breakdown (from fees)

New products can reuse the supported configuration types above. Adding a new task type or automation handler requires implementation and end-to-end verification; a new display name alone is insufficient.

Configuration Reference

Available Product Types

Term Units

Interest Rate Types

Floating rates (index + spread repricing of outstanding loans) are configured separately via the Floating Rate Config layer — not through interest_rate_type.

Interest Rate Periods

Day Count Conventions

Interest Calculation Methods

Repayment Frequencies

Fee Types

Fee Calculation Methods

Fee Collection Methods

Guarantee Types

System Roles

The following roles are defined in the system. Workflow steps (auto_assign_role) and approval levels (required_role, escalate_to_role) must reference one of these roles — arbitrary strings will be rejected by the backend.

Important: Roles like BRANCH_MANAGER, UNDERWRITER, CREDIT_COMMITTEE, CREDIT_ANALYST_MANAGER, REGIONAL_MANAGER, HEAD_OF_CREDIT, and BOARD_MEMBER are not valid system roles. Use the closest match from the table above (e.g., OPERATIONS_MANAGER instead of BRANCH_MANAGER, CREDIT_ANALYST instead of UNDERWRITER).

5-Pillar Scoring Weights

Weights must sum to 1.0. Default values and recommended adjustments:

Credit Score Ranges

Quick Setup Checklist

For each product, complete these steps in order:

• Create base product — type, amounts, terms, interest, repayment
• Add fees — origination, processing, late payment, insurance
• Configure credit risk — pillar weights, DTI limits, auto-decision thresholds
• Configure approval chain — approval levels by amount threshold
• Update intake config — KYC/selfie requirements
• Add required documents — document checklist per stage
• Configure form fields — which fields to show in the application
• Configure disbursement — disbursement channel
• Configure workflow steps — step order, modes, roles, due days
• Add rework rules — which steps can be returned to, by whom, with which reason codes
• Configure notifications — borrower/assignee/role notifications per stage event
• Add rate tiers — optional, for risk-based pricing
• Set up auto-tagging — create attribute specs to auto-tag borrowers (see AUTO_TAGGING_SETUP_GUIDE.md)
• Add tag visibility rules — REQUIRE/EXCLUDE rules to control who sees this product
• Save and publish workflow — verify a new application freezes the intended task list
• Rehearse failure paths — rejected documents, incomplete KYC, retry, assessment, accepted terms, missing signatures, independent approval and funding confirmation
• Verify with schema endpoint — GET /api/v1/products/:id/schema
• Activate product — set is_active: true

Offer preparation and issuance (September 2026)

Entering OFFER_PROPOSAL prepares a DRAFT automatically. Keep this step manual for staff review. The draft uses the latest final approving underwriting assessment (amount, term, term unit, annual percentage rate and conditions). A workflow without underwriting requires an approved saved credit assessment for this application. Missing approval blocks preparation; there is no fallback interest rate or client-supplied score override.

Staff review the draft in Term Proposals, then select Issue offer. Issuance records the actor and assessment evidence, starts the seven-day acceptance period and completes OFFER_PROPOSAL. Configure the next borrower OFFER_ACCEPTANCE step and its notification policy. Draft preparation itself does not notify the borrower or make the draft acceptable. Repeated preparation returns the same draft; use Refresh draft after assessment rework. Changed terms must return through underwriting rather than a separate manual offer form.

For existing applications already at the offer stage, opening Term Proposals prepares a missing draft. If preparation fails, the page shows the reason and a retry action. Apply tenant migration 254 before running this version.

The displayed installment follows the product repayment frequency and the term retains its actual unit, including days for nano loans. Mandatory fees are itemized separately from interest. Repayment dates calculated at preparation are indicative; origination must reconcile the accepted terms with the actual funding schedule and configured fee treatment.

Final approval and signed terms

At APPROVAL, use the application approval review. The amount, interest rate, term and term unit come from the latest accepted offer and are read-only. The agreement must be fully signed before approval; a missing lender or required witness signature keeps approval blocked. To change terms, use the configured return-to-offer workflow, obtain fresh acceptance and signatures, then return for approval.

Final approval enforces the product amount and term limits, the exact product term unit, a nonnegative interest rate with at most six decimal places, the configured approval role/quorum and maker/checker separation. There is no universal minimum term for large amounts, amount-per-month threshold or restriction on round amounts. Configure additional lending policy during assessment, before the offer is accepted.

For products requiring a guarantee, an active, effective, unexpired guarantee covering the accepted amount must already exist. Complete guarantee review before final approval. Final approval does not create a guarantee or apply another interest-rate discount after signing.

The signing session coordinates required participants for one agreement version and document hash. Use electronic signing with explicit consent; borrower and lender signatures are required, with any configured additional participants. Digital certificate signing and wet-signature uploads are not currently implemented signing options. Invitations must reference the current session; replaced sessions require fresh invitations. Origination and payment confirmation remain separate operations after approval.

A generated agreement with its document ready can be reviewed and signed directly in the borrower portal; sending an email invitation is optional. The borrower selects Review and sign agreement, reviews the document and provides electronic consent. Staff then open Term Proposals → Signing and use Sign as lender. The signing checklist refreshes while signatures are pending. Final approval remains blocked until all required participants have signed.

Automatic loan creation after final approval

Completing the application workflow queues loan creation in the same database transaction. No separate workflow step, product toggle or additional API call is required. The worker creates the loan from the approved and signed terms, including its schedule and accounts. It checks workflow completion and signed evidence again before creation. Failures remain queued and retry automatically; the approved application's panel shows progress, the failure reason and an authorized retry action. Repeated requests return the existing loan. The legacy auto_create_loan request flag is deprecated and does not disable this handoff.

Open the created loan to proceed with the disbursement request and its separate funding workflow. Automatic origination does not release funds.

Assigned funding workflow

Loan creation also creates a linked funding workflow. An available loan officer receives Prepare disbursement request in My Tasks, which opens the loan. Use Manage funding to confirm the payout destination and submit the request. Verification is assigned to an operations manager, release to a finance officer distinct from the requester and verifier, and transfer reconciliation to someone other than the releasing officer. An available tenant administrator can cover an unstaffed role while preserving these separations. Missing independent staff blocks setup with an actionable error; do not bypass it by editing task records.

The loan's funding checklist shows the current step and every assignee. The borrower can see the approved loan as Awaiting disbursement. It becomes active only after transfer confirmation and posting succeed; pre-funding schedules are provisional, and unfunded loans are excluded from scheduled payment selection.