Product Setup

Nano Loan Product Setup Guide

Updated: 11 September 2026

This guide describes the supported nano loan setup in the current application. A nano product can automate identity-policy checks, fraud screening and credit scoring. It still needs an accepted offer, required consents, a signed agreement and final approval before loan origination. Funding follows in the separate disbursement workflow. The previous five-step preset did not provide a complete instant-lending journey and must not be used for new configurations.

1. Configure the product

Open Admin → Loan Products → product → Configuration (/admin/products/{product_id}/config). Use your approved commercial policy for currency, amount limits, term, rate period, repayment frequency and fees. Enter rates as percentages, for example 12.5, not 0.125; this illustrates input format, not a recommended price. A term in days must retain DAYS through assessment, offer and repayment schedule.

Complete the following configuration before publishing:

A required national ID file and require_document_kyc are different settings: document upload/review confirms evidence availability; identity policy determines whether that evidence must pass identity verification. Do not enable face matching for a selfie-only or document-only product.

2. Apply and review the nano workflow template

On the Workflow tab, select Apply Nano Template. This replaces the draft in the editor; review it before saving. The template uses requires_manual_review: true, one approval level, and no auto-approval threshold. The top-level switch alone does not generate offers, approve applications or transfer funds.

All steps are unconditional in this baseline. The template's two-day due values are editable calendar-day starting values, not an instant-processing SLA. It configures document rework to document_upload with reason DOCUMENT_NEEDS_CORRECTION, notes and borrower action required.

Do not insert DISBURSEMENT, rename it to auto_disburse, or attach auto_disburse to another application step. The legacy handler needs an already-created loan and only creates a disbursement request; it cannot originate a loan or confirm transferred funds. New application workflow saves/publication reject that configuration.

3. What automation actually does

Compensation handlers kyc_verification_compensation, fraud_screening_compensation and credit_decision_compensation are for configured rework across completed automation. They do not approve an application. The baseline includes no conditional credit_decision == REFER rule: the previous guide used a field that did not match the handler's decision evidence and was not a built-in publication field.

The supported baseline deliberately keeps review unconditional. Do not skip offer acceptance, required consent or signatures based on amount or returning-customer status. The system does not synthesize that evidence when a task is skipped.

4. Where staff and borrowers act

Open the application at /loans/applications/{application_id}?mode=view&tab=workflow to inspect the frozen tasks and automation recovery actions.

• Document review: /admin/documents/queue. Verify/reject with the appropriate document permissions. The normal document endpoints now synchronize the active DOCUMENT_REVIEW task and write review audit history. All active mandatory quantities must be verified before the task completes. A document shared with an older application must not make the current review fail.
• KYC: /admin/kyc-verifications, with the identity-document and selfie review screens linked from borrower review. Approving a file does not establish a missing face match. For automated KYC, retry the current task after evidence is corrected.
• Underwriting: the application's Workflow tab displays the assessment form when the current task type is UNDERWRITING. Saving claims the review; a draft keeps it open, and a final assessment records the recommendation and advances it. It does not replace final approval.
• Offer and agreement: the application's Term Proposals tab. Prepare/publish the offer, obtain borrower acceptance, then generate and sign its agreement. The borrower uses their application/offer/signing screens.
• Final approval: the application's Approval tab, with the configured role/quorum and independent checker.
• Funding: originate the approved application, then use the linked disbursement screens/checklist. Confirm actual release before describing the loan as funded.

Generic workflow completion must not substitute for document, KYC, underwriting, offer, consent or signature evidence. Access depends on both the staff identity and the corresponding permissions; assigning a role to a workflow does not grant API permissions.

5. Notifications and channel readiness

Configure stage-entry/completion/rework recipients on the Workflow tab, then configure active notification templates, real senders and workers. Selecting “borrower” does not force SMS or USSD delivery; the configured notification channel and reachable contact determine delivery. Do not announce “approved” on credit-check completion or “funds sent” on disbursement-request creation.

The preset is a workflow configuration, not proof of a USSD or payment-provider integration. Rehearse the actual enabled channel and provider separately before advertising instant mobile-money lending.

6. Save, publish and test

1. Save all supporting tabs, then save Workflow. Fix inline validation errors.
2. Publish the immutable workflow version. Document and consent prerequisites and approval setup must exist first.
3. Submit a new controlled test application and confirm that its frozen task list matches the published sequence.
4. Test missing/rejected/reused documents, product-specific KYC, failed automation and retry, assessment draft/final, offer rejection/counteroffer/acceptance, missing signatures, final approval and duplicate origination.
5. Test disbursement authorization, failure and actual confirmation; reconcile the payout amount, fees, schedule and internal subledger.
6. Test repayment, allocation, settlement and closure using approved test procedures.

Publishing does not repair previously frozen application workflows. Do not manually edit task rows or mark missing evidence complete. Use authorized cancellation/replacement for disposable test applications; live contractual applications need an explicitly reviewed migration.

See generic setup and employer-backed setup for the other product configurations. Provider delivery and a live customer journey still require deployment and controlled acceptance testing.

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.

Disbursement checklist

The funding gate is configured per product on the Disbursement Checklist tab (API GET/POST/PUT /api/v1/products/:id/checklist-template). Nano intake is mostly automated, so the checklist is intentionally short — it verifies what could have drifted between decision and release, plus the release controls themselves:

Suggested item names in display order:

Fraud screening cleared
Credit decision in force
Agreement and consents captured
Payout wallet verified
Device ownership verified
Independent release authorization
Transfer confirmation captured

Servicing features — nano applicability

Nano loans are days-term, single or few-installment credit-limit draws. Most servicing features from the Loan Servicing Operations Guide apply normally; a few are not meaningful for this product shape: