Product Setup

Salary Loan Product Setup Guide

This guide walks you through configuring a Salary Loan Product in Hiana Loans, where employees apply for loans and their employers approve or decline the application.

Overview

Use the complete employer-backed configuration guide as the implementation and acceptance checklist. The former three-step example was incomplete: document upload, employer approval and final approval do not cover document review, identity checks, credit assessment, offers, consent or agreement signing.

The full journey is submission → document review → identity verification → employer verification → credit/underwriting → borrower offer acceptance → consent → agreement signatures → final internal approval → loan origination → separate funding workflow → servicing → closure.

Employer approval delivery (10 September 2026): the code now connects normal task completion to durable employer-request preparation. Apply tenant migration 000237_external_approval_delivery and restart the updated API/workers. The complete guide describes task-bound approval levels, confirmation links, retries and the acceptance rehearsal. Existing frozen workflows are not rewritten and historical emails are not resent.

Step 1: Create the Product

1. Go to Admin → Loan Products
2. Click Create Product
3. Enter:
   • Product Name: e.g., "Salary Loan"
   • Description: e.g., "Loans for salaried employees with employer approval"
   • Interest Rate: e.g., 12.5% per annum
   • Term: e.g., 12 months
   • Repayment Frequency: Monthly
4. Click Save

Step 2: Configure Workflow (Critical for Employer Approval)

Select DOCUMENT REVIEW in Step Type; the API value is DOCUMENT_REVIEW. Offer, consent and agreement types are available in the same dropdown. CREDIT_CHECK must use AUTOMATED mode with credit_decision. See the complete guide for each operational screen and the exact document-rework rule.

Go to Product Configuration → Workflow. Configure the complete sequence below; the detailed ownership, evidence and notification settings are in the complete configuration guide.

Set the top-level Approval Levels field (in the Workflow tab) to 2. Then on each APPROVAL step, set its Approval Level input: employer_approval (step 5) → level 1, approval (step 12) → level 2. Finally, open the Approval tab and configure each level's required role, required count, and timeout — level 1 uses EMPLOYER, level 2 uses OPERATIONS_MANAGER. Save both tabs before publishing. A role assigned to monitor a task does not replace the actual signer/checker. Use EMPLOYER for the external approval chain identity where an employer portal representative is configured; assigning LOAN_OFFICER does not make that officer an employer. fraud_screening (step 4) is optional — include it when your credit-risk policy requires fraud screening; omit it if your policy does not use it.

For each step, configure the notification policy (stage_entry, stage_completion, rework, assignment) using the per-step table in the complete configuration guide. Key points: notify the borrower on stage_entry for steps they must act on (document upload, offer proposal, offer acceptance, consent, agreement); add the EMPLOYER role to stage_entry and assignment for the employer_approval step; leave automated steps (credit_check) without staff notifications.

Configure rework rules per step using the per-step rework table in the complete configuration guide. Key rules: document_review → document_upload (document corrections), kyc_verification → document_upload (identity recapture), employer_approval → document_upload (employment corrections), underwriting → document_upload (income evidence, with credit_decision_compensation if credit_check is crossed), offer_acceptance → offer_proposal (counteroffer), and approval → offer_proposal (final approval rejects terms).

Step order defines sequential routing. Reusing an approval-level number does not create parallel branches in this single-cursor workflow. Required approvals define the quorum within the relevant approval group.

Save the draft configuration first. Complete all related tabs, then publish the immutable version. Keep DISBURSEMENT out of the application sequence: funding has its own linked workflow after origination.

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.

Step 3: Configure Approval Chain (Required Before Publishing)

The workflow's APPROVAL steps reference approval levels, but the Approval tab defines who approves at each level and how many approvals are required. The backend will reject publishing if this is not configured.

Go to: Product Configuration → Approval tab

The level_name is a display label — name it whatever makes sense to your team. It shows up in the admin UI and approval task descriptions. Routing is driven by the level number, not the name.

Level 1: Employer Confirmation

Level 2: Operations Manager Sign-off

Click Save Configuration.

Publish Workflow (Required Before Applications Can Be Submitted)

Now go back to the Workflow tab and click Publish immutable version.

Why Publishing Is Required

Saving the workflow configuration only stores a draft. The system does not use the draft when processing loan applications. Instead, it looks for a published immutable version — a snapshot of the workflow that cannot be changed after publication.

When a borrower submits an application, the backend fetches the published workflow definition for the product. If no published version exists, the application will fail with the error:

product has no published application workflow

How It Works

1. Save stores the workflow configuration as a draft that can be edited freely.
2. Publish creates an immutable snapshot with a version number and a SHA-256 hash. This is the version the system uses when creating applications.
3. If you need to change the workflow later, update the draft and publish again — this creates a new version. Existing applications continue on the version they were created with; new applications use the latest published version.

Publishing Order

Make sure all dependent configurations are saved before publishing:

1. Workflow tab — save the workflow steps and approval levels
2. Approval tab — save the approval chain (who approves at each level)
3. Workflow tab — click Publish immutable version

The backend validates cross-references at publish time. If any APPROVAL step references approval levels that don't exist in the Approval tab, publishing will be rejected.

Important: If you get a validation error like "approval step has no approval levels", it means the Approval tab has not been configured. The backend checks the Approval Chain configuration (not the workflow step's approval_level field) when publishing. Make sure you've added approval levels in the Approval tab and saved before publishing.

Note: The top-level approval_levels in the Workflow tab must equal the highest approval_level among your steps. If you have levels 1 and 2, set approval_levels to 2. The Approval tab levels must cover all levels referenced by your workflow steps.

Step 4: Configure Guarantor Settings

Go to: Product Configuration → Guarantor tab

Employer Verification Settings

1. Check "Requires Employer Verification"

2. Check "Employer Must Pre-Approve"

3. In the "Employer Verification Step" dropdown, select: Employer Approval

   • This dropdown is populated from the workflow steps you just created
   • It tells the system which step sends the approval email to the employer

4. For this MOU-backed baseline, enable "Requires MOU with Employer" and configure an active linked MOU.

Click Save Configuration.

Step 5: Configure Other Product Settings

Complete the remaining tabs as needed:

Step 6: Configure Pre-Disbursement Checklist

Before a loan can be disbursed, the system verifies that all required checks and documents are complete. The pre-disbursement checklist is a product-level template — when a loan is approved, the system creates a checklist instance from this template. All required items must be marked as completed before disbursement can proceed.

Go to: Product Configuration → Checklist tab

Click Create Checklist Template and configure the following items:

Item Types Explained

Key Items for Employer-Based Lending

Items 3, 7, and 12 are specific to employer-based (salary deduction) loans:

• Item 3 — Salary Deduction Mandate: The borrower signs a mandate authorizing the employer to deduct loan repayments from their salary. Without this, the repayment mechanism doesn't exist.
• Item 7 — Employer MOU Validity Check: Confirms the Memorandum of Understanding with the employer is still active. MOUs can expire or be terminated — this check prevents disbursing a loan that can't be repaid via salary deduction.
• Item 12 — Salary Deduction Setup Confirmation: The employer's payroll/HR department confirms the deduction has been configured in their payroll system for the next pay cycle. This is the final operational check before funds are released.

API Example

POST /api/v1/products/{product_id}/checklist-templates

{
  "template_name": "Salary Loan Pre-Disbursement Checklist",
  "description": "Standard checklist for MOU-backed salary deduction loans",
  "items": [
    { "item_name": "National ID Verification", "item_type": "DOCUMENT_VERIFY", "is_required": true, "display_order": 1 },
    { "item_name": "Employment Confirmation Letter", "item_type": "DOCUMENT_VERIFY", "is_required": true, "display_order": 2 },
    { "item_name": "Employer Authorization / Salary Deduction Mandate", "item_type": "DOCUMENT_VERIFY", "is_required": true, "display_order": 3 },
    { "item_name": "Latest Payslip (≤30 days)", "item_type": "DOCUMENT_VERIFY", "is_required": true, "display_order": 4 },
    { "item_name": "Bank Statement (3 months)", "item_type": "DOCUMENT_VERIFY", "is_required": true, "display_order": 5 },
    { "item_name": "Credit Bureau Check", "item_type": "CREDIT_CHECK", "is_required": true, "display_order": 6 },
    { "item_name": "Employer MOU Validity Check", "item_type": "COMPLIANCE_CHECK", "is_required": true, "display_order": 7 },
    { "item_name": "Fraud / Blacklist Screening", "item_type": "FRAUD_CHECK", "is_required": true, "display_order": 8 },
    { "item_name": "Guarantor Consent (if applicable)", "item_type": "DOCUMENT_VERIFY", "is_required": false, "display_order": 9 },
    { "item_name": "Loan Agreement Signing", "item_type": "DOCUMENT_VERIFY", "is_required": true, "display_order": 10 },
    { "item_name": "Disbursement Account Verification", "item_type": "DOCUMENT_VERIFY", "is_required": true, "display_order": 11 },
    { "item_name": "Salary Deduction Setup Confirmation", "item_type": "COMPLIANCE_CHECK", "is_required": true, "display_order": 12 }
  ]
}

How It Works in the Workflow

1. After loan origination, verify that the funding process creates the product checklist instance for that loan before release. Application approval alone is not funding confirmation.
2. Loan officers see the checklist items in their dashboard under the loan.
3. Each item is marked as Completed, Failed, or Skipped (optional items only).
4. The loan cannot be disbursed until all required items are marked as Completed.
5. Once all required items are complete, the checklist is approved and disbursement can proceed.

Note: Optional items (like Guarantor Consent) can be skipped without blocking disbursement. Required items that fail will block disbursement and trigger a review.

Step 7: Set Up QuickBooks Integration (Accounting)

Go to: Accounting → Account Mappings

Map internal account codes to your QuickBooks accounts:

See QUICKBOOKS_ACCOUNT_SETUP_GUIDE.md for detailed instructions on finding QB Account IDs.

How the Approval Process Works

The complete configuration guide defines the intended sequence and the current engineering blockers. Run its acceptance rehearsal before enabling employer invitations.

1. Employee submits; the system acknowledges receipt and displays application status.
2. Staff review required documents and complete aggregate identity verification.
3. At employer_approval, the intended behavior is an employer-specific approval request and secure email. Verify the task-bound EMPLOYER_APPROVAL row and delivery outbox entry; generic staff tasks do not prove it occurred.
4. Employer confirmation allows credit assessment and underwriting to proceed. It does not grant final loan approval.
5. Borrower reviews/accepts the offer, supplies required consent and signs the agreement. The lender and required witnesses sign too.
6. Independent internal approval completes the application workflow. Staff then originate the loan using the accepted matching terms and signed agreement.
7. Finance completes the separate funding checklist and release/confirmation process. A loan is not active merely because an operations manager approved an application.
8. Servicing records repayments and manages arrears, settlement and closure.

Email Templates

Employer Approval Email

The employer request template should produce a message like this after the request/delivery path has passed acceptance testing:

Subject: Loan Approval Request - [Employee Name]

Dear [Employer Name],

[Employee Name] from your organization has applied for a salary loan.

Loan Details:
- Amount: KES 50,000
- Term: 12 months
- Monthly Payment: KES 4,500
- Interest Rate: 12.5% per annum

Please review and approve or decline:

[APPROVE] [DECLINE]

This link expires at the configured approval deadline.

Thank you,
Hiana Loans

Disbursement Checklist

The funding gate is configured per product on the Disbursement Checklist tab (API GET/POST/PUT /api/v1/products/:id/checklist-template). 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. A typical salary-loan template:

Suggested item names in display order:

Employment and income current
Employer confirmation recorded
Deduction mandate signed
Agreement signed
Within deduction cap
Credit decision in force
Fraud screening cleared
Payout destination verified
Consents acknowledged
Independent release authorization
Transfer confirmation captured

Troubleshooting

"Employer Verification Step" dropdown is empty

• Cause: No workflow steps configured yet
• Fix: Go to Workflow tab and add at least one step, then save

Employer doesn't receive approval email

Check the employer-specific approval record first, then the notification record, provider delivery and inbox. For the application inspected on 10 September 2026, the required product switch and contact email were present but the employer-specific request was absent. That was the pre-repair wiring gap. Deploy the repair and test a correctly configured application; the old frozen workflow is not backfilled. See delivery diagnosis and operations.

Application stuck in "Employer Approval" step

Distinguish a missing request, undelivered message, unanswered request, expired token and unsatisfied approval group. Escalate using the configured timeout. Do not manually move past mandatory employer approval to make the application proceed. Any repaired/resend operation must be authorized and auditable.

Employer declines but employee should resubmit with different terms

• Cause: Employer declined the original loan amount or terms
• Fix: Operations Manager can use the Rework operation to send the application back to Document Upload for the employee to update the requested amount. See POST /api/v1/applications/:id/workflow/rework with target_step_key: "document_upload" and an appropriate reason code. The employee then resubmits via POST /api/v1/applications/:id/workflow/resubmit.

Application needs correction after employer approval

• Cause: Documents are incomplete or incorrect after employer approved
• Fix: Operations Manager can rework the application back to Document Upload without restarting the entire workflow. Reassess employer and downstream approval evidence affected by the correction. Do not assume approval remains valid after material employment, amount or term changes.

Best Practices

1. Set realistic due days:

   • Document Upload: 7 days (employees need time to gather documents)
   • Employer Approval: 72 hours as an initial operational target; agree it with the employer
   • Final Approval: 2 working days as an initial operational target

2. Test the workflow:

   • Create a test application and verify emails are sent correctly
   • Check that employer approval buttons work

3. Communicate with employers:

   • Send employers a welcome email explaining the process
   • Provide a phone number for questions

4. Monitor approval times:

   • Track how long each step takes
   • Adjust due days if needed

Next Steps

1. Save the product configuration (all tabs)
2. Test with a sample application to verify the workflow
3. Train loan officers on the approval process
4. Notify employers about the new approval system
5. Monitor the first few applications to ensure everything works

Support

For questions or issues:

• Contact the Hiana Loans support team
• Check the LOAN_PRODUCT_SETUP_GUIDE.md for general product configuration
• Check the AUTO_TAGGING_SETUP_GUIDE.md for auto-tagging setup (e.g., civil servants, MNO staff, MOU partners)
• Check the PRODUCT_WORKFLOW_SETUP_GUIDE.md for workflow operations (rework, resubmit, recovery, pipeline analytics, collections)
• Check the QUICKBOOKS_ACCOUNT_SETUP_GUIDE.md for accounting integration
• Check the LOAN_SERVICING_OPERATIONS_GUIDE.md for post-disbursement operations (waivers, top-ups, delinquency pause, re-aging, maker-checker, floating rates)