Loan Disbursement: End-to-End Workflow Guide

Disbursing a loan is one of the highest-stakes operations in Agatabo. A single miskeyed amount, a missing security, or a skipped eligibility check can cause months of accounting problems. This guide walks you through every stage — from the initial eligibility review all the way through ongoing payment monitoring — so every disbursement is accurate, compliant, and fully documented.

How disbursement works today: Loan creation and disbursement happen in a single atomic API call. When POST /loans succeeds, the loan is immediately ACTIVE and funds are considered disbursed. There is no separate approval step in the current release.

Workflow Overview

Pre-Loan Preparation → Loan Creation & Disbursement → Post-Disbursement Monitoring

Stage 1: Pre-Loan Preparation

Who: Loan Officer or Administrator Complete all of the following checks before you open the loan creation form. Rushing through preparation is the leading cause of disbursement errors and non-performing loans.

Verify member eligibility

Confirm the borrower meets every eligibility requirement:

Has a savings balance that meets your organization’s minimum threshold (typically 20–30% of the requested loan amount)
Has no existing ACTIVE or DEFAULTED loan — Agatabo allows only one active loan per member
Has the “member” role assigned (a savings ledger account must exist)
Is currently active in the organization (not deactivated or suspended)

If any of these conditions is not met, stop here and resolve the issue before proceeding.

Assess repayment capacity

Beyond the minimum eligibility rules, evaluate whether the member can realistically repay:

Review the member’s income sources and stability
Check their loan history for past defaults or late payments
Confirm they can afford the calculated monthly installment amount
Consider existing financial obligations outside the tontine

Collect and document securities

Your organization must hold sufficient security to cover the full loan amount. Accepted security types:

Type	Description	What to Collect
Guarantor	An active member who co-signs	Written guarantor agreement, guarantor’s member ID
Collateral	A physical asset pledged by the borrower	Photos, ownership title or receipt, estimated market value
Savings lien	Borrower’s own savings frozen until repayment	Minimum savings balance requirement documented

The total value of all securities must equal or exceed the principal amount. Collect all supporting documents before creating the loan.

Calculate and agree on loan terms

Settle on the final terms with the borrower and loan committee before system entry:

Principal amount — must be within your organization’s configured limits
Period — number of months (must not exceed max_period in org settings)
Interest rate — as a monthly or yearly percentage
Interest calculation method — Simple, Compound, or Reducing Balance
Disbursement fee — percentage or fixed amount, if applicable

Calculate the estimated installment amounts so the borrower knows exactly what they are committing to.

Pre-creation checklist:

✅ Member eligibility fully verified (savings, loan history, active status)
✅ Securities documented and values confirmed adequate
✅ Loan terms calculated and within organizational policy limits
✅ All supporting documents collected and filed
✅ Loan committee approval obtained (if your bylaws require it)
✅ Borrower understands and accepts the repayment terms

Stage 2: Loan Creation & Disbursement

Who: User with loans:write (ANY scope) permission

The API Call

Endpoint: POST /loans

POST /loans
Headers:
  x-organization-id: {organizationId}
  x-idempotency-key: {unique-key}
Body:
{
  "organizationUserId": "orguser-123",
  "principalAmount": 500000,
  "period": 12,
  "interestRate": 10,
  "interestRateType": "YEARLY",
  "interestCalculationType": "REDUCING_BALANCE",
  "interestPaymentTiming": "WITH_INSTALLMENTS",
  "installmentType": "EQUAL_TOTAL",
  "paymentAllocationOrder": "INTEREST_FIRST",
  "startDate": "2026-06-01",
  "purpose": "Business expansion – inventory purchase",
  "bankAccountId": "bank-456",
  "loanSecurities": [
    {
      "type": "GUARANTOR",
      "organizationUserId": "orguser-789",
      "description": "John Doe – guarantor and co-signer"
    },
    {
      "type": "COLLATERAL",
      "value": 600000,
      "description": "Motorcycle, 2020 model, estimated value 600,000 RWF"
    }
  ],
  "disbursementFeePercentage": 1.0,
  "disbursementFeeType": "PERCENTAGE"
}

Required fields:

Field	Type	Description
`organizationUserId`	string	Borrower — must have “member” role, be active, and have no existing ACTIVE or DEFAULTED loan
`principalAmount`	number	Loan amount in the organization’s currency
`period`	number	Loan term in months
`interestRate`	number	Rate as a percentage (e.g., `10` for 10%)
`interestRateType`	enum	`"MONTHLY"` or `"YEARLY"`
`interestCalculationType`	enum	`"SIMPLE"`, `"COMPOUND"`, or `"REDUCING_BALANCE"`
`startDate`	string	Loan start date in ISO 8601 format
`bankAccountId`	string	Organization bank account used for disbursement

Optional fields (defaults come from organization loan settings):

Field	Default	Description
`interestPaymentTiming`	Org setting	`"IN_ADVANCE"` or `"WITH_INSTALLMENTS"`
`installmentType`	Org setting	`"EQUAL_PRINCIPAL"` or `"EQUAL_TOTAL"`
`paymentAllocationOrder`	Org setting	`"INTEREST_FIRST"`, `"PRINCIPAL_FIRST"`, or `"PROPORTIONAL"`
`purpose`	null	Free-text description of loan purpose
`loanSecurities`	`[]`	Array of guarantor, collateral, or savings-lien objects
`disbursementFeeType`	Org setting	`"PERCENTAGE"` or `"FIXED_AMOUNT"`
`disbursementFeePercentage`	Org setting	Fee as a percentage (e.g., `1.0` = 1%)
`disbursementFeeFixedAmount`	Org setting	Fee as a flat amount
`bankChargeAmount`	null	Bank transfer charges, if any
`skipNegativeBalanceCheck`	`false`	Override the negative-balance check — use only in exceptional circumstances

What Agatabo Does Automatically

When POST /loans succeeds, the system executes all of the following steps atomically — either everything completes, or nothing is saved.

Validate member eligibility

Agatabo confirms:

The organization user exists and is active
The user has the “member” role assigned
The user has no existing loan in ACTIVE or DEFAULTED status

If any check fails, the API returns a 409 Conflict or 404 Not Found and no loan is created.

Validate against organization policies

Agatabo checks:

The principal amount is within configured min/max limits
The period does not exceed max_period (if set)
The principal does not exceed member savings × max_loan_percentage (if set)
The currency scale matches your organization’s precision settings

If any check fails, the API returns a 400 Bad Request with a specific message.

Validate securities

Agatabo confirms:

The total declared security value equals or exceeds the principal amount
All named guarantors are active members in your organization
Any savings-lien amount does not exceed the member’s available savings balance

If securities are insufficient, the API returns 400 Bad Request: "Insufficient security coverage".

Generate the installment schedule

Using the interest calculation method and installment type you specified, Agatabo:

Computes the EMI (Equated Monthly Installment)
Generates a full repayment schedule with due dates
Calculates the total interest payable over the loan term
Applies your organization’s configured rounding rules

Create the loan record

The loan record is saved with:

Status: ACTIVE (not PENDING)
A unique account number (e.g., L-00042)
The locked installment schedule
Securities stored as structured JSON

Create dedicated ledger accounts

Three new ledger accounts are created for this specific loan:

LOAN_RECEIVABLE — tracks the outstanding principal
INTEREST_RECEIVABLE — tracks interest owed but not yet collected
PENALTY_RECEIVABLE — tracks any penalties applied

These accounts appear on the balance sheet and feed directly into the Loans Outstanding report.

Post the disbursement journal entry

Agatabo posts the appropriate journal entry based on your fee and interest timing configuration. See the Disbursement Journal Entries section below for all four patterns.

Send a disbursement notification

If your organization has SMS or email notifications enabled, Agatabo sends the borrower a confirmation:

“Your loan of 500,000 RWF has been approved. 12 monthly installments of 45,000 RWF each. First payment due 2026-07-01.”

Sample success response (201 Created):

{
  "message": "Loan created successfully",
  "data": {
    "id": "loan-123",
    "accountNumber": "L-00042",
    "organizationUserId": "orguser-123",
    "principalAmount": 500000,
    "period": 12,
    "interestRate": 10,
    "interestRateType": "YEARLY",
    "status": "ACTIVE",
    "startDate": "2026-06-01T00:00:00.000Z",
    "disbursementFee": 5000,
    "loanReceivableLedgerAccountId": "acc-456",
    "interestReceivableLedgerAccountId": "acc-457",
    "penaltyReceivableLedgerAccountId": "acc-458",
    "createdAt": "2026-06-13T10:30:00.000Z"
  }
}

Disbursement Journal Entries

The exact journal entry pattern depends on two settings: when interest is paid, and whether the disbursement fee is deducted from cash or from the member’s savings. All four combinations are shown below.

Fee from cash, interest with installments
Fee from savings, interest with installments
Interest paid in advance from cash
Interest paid in advance from savings

The most common configuration. The member receives principal − fee in cash and pays interest gradually with each monthly installment.

Dr  LOAN_RECEIVABLE              500,000
Dr  INTEREST_RECEIVABLE           60,000   (total interest over 12 months)
Cr  CASH (bank account)          495,000   (500,000 − 5,000 fee)
Cr  INTEREST_INCOME               60,000
Cr  DISBURSEMENT_FEE_INCOME        5,000

Member receives: 495,000 RWF

The fee is deducted from the member’s savings account rather than from the cash disbursement. The member receives the full principal in cash.

Main disbursement entry:
Dr  LOAN_RECEIVABLE              500,000
Dr  INTEREST_RECEIVABLE           60,000
Cr  CASH                         500,000
Cr  INTEREST_INCOME               60,000

Separate fee entry:
Dr  SAVINGS (member account)       5,000
Cr  DISBURSEMENT_FEE_INCOME        5,000

Member receives: 500,000 RWF in cash; 5,000 RWF deducted from savings

The full interest amount is deducted from the cash disbursement. The member receives principal − interest and pays principal only in installments.

Dr  LOAN_RECEIVABLE              500,000
Cr  CASH                         440,000   (500,000 − 60,000 interest)
Cr  INTEREST_INCOME               60,000

Member receives: 440,000 RWF

Interest is collected upfront by debiting the member’s savings account. The member receives the full principal in cash.

Main disbursement entry:
Dr  LOAN_RECEIVABLE              500,000
Cr  CASH                         500,000

Advance interest entry:
Dr  SAVINGS (member account)      60,000
Cr  INTEREST_RECEIVABLE           60,000

Member receives: 500,000 RWF in cash; 60,000 RWF deducted from savings

Stage 3: Post-Disbursement

Who: Loan Officer, Treasurer

Immediate Actions

Disburse the physical funds to the member

Cash disbursement
Bank transfer

Count the cash with the member present
Have the member sign a disbursement receipt
File the signed receipt in the loan folder
Confirm the amount matches the system record

File all loan documentation

Assemble and file the following in the member’s loan folder:

Signed loan agreement
Collateral documents (titles, appraisals, photographs)
Signed guarantor agreements
Disbursement receipt signed by the borrower
Any security valuation reports

Provide the member with their payment schedule

Export the installment schedule from Agatabo
Print a copy and hand it to the borrower
Confirm the borrower understands each due date and the amount owed
Explain the accepted payment methods (cash, mobile money, bank transfer)
Provide the treasurer’s contact details for payment questions

Set up payment reminders and monitoring

Add the loan to your active monitoring list
Configure automatic payment reminders to send 3–5 days before each due date
Note the first payment due date in your calendar
Confirm penalty rules are in place if your policy requires them

Ongoing Monitoring

Record payments promptly

Use POST /loans/{loanId}/repay to record each installment payment as soon as it is received. Delayed recording causes the Loans Outstanding report to show inaccurate arrears figures and may trigger unwarranted penalty calculations.

Manage delinquencies

Identify overdue installments immediately after each due date
Make a personal phone call within 24 hours of a missed payment
Apply penalties per your organization’s policy
Escalate to the loan committee if the member misses two consecutive payments
Consider restructuring the loan for members facing genuine hardship

Monitor portfolio health

Run the Loans Outstanding report regularly and classify loans by aging:

Days Overdue	Status	Recommended Action
0	Current	No action needed
1–30	Watch	Send reminder, follow up
31–90	Substandard	Escalate to loan committee
90+	Doubtful/Loss	Consider default proceedings

Complete Workflow Checklist

Pre-Creation

✅ Member eligibility verified — savings, loan history, active status
✅ Securities documented with adequate total value
✅ Loan terms within organizational policy limits
✅ Supporting documents collected and filed
✅ Loan committee approval obtained (if required)
✅ Borrower acknowledges and accepts repayment terms

During Creation (API)

✅ x-idempotency-key header included in the request
✅ All required fields present in the request body
✅ Principal within policy limits
✅ Securities declared with sufficient total coverage
✅ Borrower has no existing ACTIVE or DEFAULTED loan
✅ API returns a 201 Created response

Post-Disbursement

✅ Funds physically disbursed to the member (cash or bank transfer)
✅ Borrower signed the disbursement receipt
✅ Loan documents filed in the member’s folder
✅ Installment schedule printed and given to the borrower
✅ Member added to payment reminder schedule
✅ First payment due date noted in monitoring system

Ongoing

✅ Payments recorded promptly after each due date
✅ Overdue payments followed up within 24 hours
✅ Penalties applied according to your policy
✅ Loan status updated as needed (COMPLETED, DEFAULTED)

Common Issues

Member already has an active or defaulted loan

Error: "Organization user already has an active or defaulted loan"Cause: Agatabo enforces a one-active-loan-per-member rule. The member’s current loan is in ACTIVE or DEFAULTED status.Resolution:

Wait until the existing loan is fully repaid and its status changes to COMPLETED.
If the loan is uncollectible, process a formal default via POST /loans/{id}/default — this attempts recovery from securities and writes off any unrecovered balance.
You cannot issue a second concurrent loan to the same member.

Insufficient security coverage

Error: "Insufficient security coverage"Cause: The total declared value of all securities is less than the principal amount.Resolution:

Add one or more additional guarantors.
Increase the declared value of existing collateral (with supporting documentation).
Reduce the loan principal to match the available security coverage.
Require the member to maintain a higher minimum savings balance as a savings lien.

Principal exceeds the maximum allowed amount

Error: "Principal exceeds max allowed from max loan percentage rule"Cause: Your organization has a max_loan_percentage setting (e.g., 3.0 = members may borrow up to 3× their savings). The requested principal exceeds member savings × max_loan_percentage.Example: Savings = 100,000 RWF, max_loan_percentage = 3.0 → maximum loan = 300,000 RWF. A request for 400,000 RWF would fail.Resolution:

Reduce the requested principal to within the allowed limit.
Ask the member to make additional deposits to increase their savings balance, then reapply.
Request that an administrator review and potentially update the max_loan_percentage setting in Organization Settings.

Period exceeds the maximum allowed term

Error: "Loan period cannot exceed X month(s)"Cause: The period field in your request exceeds the organization’s max_period setting.Resolution:

Reduce the loan period to within the configured maximum.
If the member needs a longer term for affordability reasons, request that an administrator update the max_period setting in Organization Settings.

Journal Entry Types

Full reference for every disbursement and payment entry pattern

Idempotency

Prevent duplicate disbursements from network errors or double-clicks

Monthly Closing Checklist

Reconcile your loan portfolio before each period close

Permissions Matrix

Verify that your loan officer account has the right permissions

​Workflow Overview

​Stage 1: Pre-Loan Preparation

​Stage 2: Loan Creation & Disbursement

​The API Call

​What Agatabo Does Automatically

​Disbursement Journal Entries

​Stage 3: Post-Disbursement

​Immediate Actions

​Ongoing Monitoring

​Complete Workflow Checklist

​Pre-Creation

​During Creation (API)

​Post-Disbursement

​Ongoing

​Common Issues

Journal Entry Types

Idempotency

Monthly Closing Checklist

Permissions Matrix

Workflow Overview

Stage 1: Pre-Loan Preparation

Stage 2: Loan Creation & Disbursement

The API Call

What Agatabo Does Automatically

Disbursement Journal Entries

Stage 3: Post-Disbursement

Immediate Actions

Ongoing Monitoring

Complete Workflow Checklist

Pre-Creation

During Creation (API)

Post-Disbursement

Ongoing

Common Issues