Lending APIs - Bridge Documentation

Overview

Loan lifecycle APIs: create applications, approve, disburse to a wallet, fetch schedules and status.

Auth: JTW token is valid for 1 hour from the time of issuance. After it expires, you must generate a new token.

Get a token

Generate a short‑lived token using your keyId and secret.

POST /api/generate-token
Content-Type: application/json

{
  "keyId": "00000000-0000-4000-8000-000000000000",
  "secret": "<your-api-secret>"
}

Response

{
  "token": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...",
  "expiresAt": "2025-01-01T12:00:00.000Z",
  "businessId": "11111111-2222-3333-4444-555555555555",
  "environment": "sandbox",
  "scopes": ["lms:read", "lms:write"]
}

Use the token in the Authorization header for all subsequent requests:

Authorization: Bearer <token>

Product management

Manage loan products used when creating loans.

Create Lending Product

POST /api/v1/lms/lending/products
Authorization: Bearer <token>
Content-Type: application/json

{
  "code": "LOAN_BASIC",
  "name": "Basic Loan",
  "currency": "TZS",
  "config": { "minPrincipal": 100000, "maxPrincipal": 10000000, "tenorMonths": 12 },
  "accountingMapping": { "glAsset": "1101", "glIncome": "4101" }
}

Response

{
  "productCode": "LOAN_BASIC",
  "type": "loan",
  "name": "Basic Loan",
  "currency": "TZS",
  "config": { "minPrincipal": 100000, "maxPrincipal": 10000000, "tenorMonths": 12 },
  "accountingMapping": { "glAsset": "1101", "glIncome": "4101" },
  "status": "draft",
  "version": 1,
  "createdAt": "2025-01-01T10:00:00.000Z",
  "updatedAt": "2025-01-01T10:00:00.000Z"
}

Get Available Lending Products

GET /api/v1/lms/lending/products
Authorization: Bearer <token>

Response

[
  {
    "productCode": "LOAN_BASIC",
    "type": "loan",
    "name": "Basic Loan",
    "currency": "TZS",
    "config": { "minPrincipal": 100000, "maxPrincipal": 10000000, "tenorMonths": 12 },
    "accountingMapping": { "glAsset": "1101", "glIncome": "4101" },
    "status": "draft",
    "version": 1,
    "createdAt": "2025-01-01T10:00:00.000Z",
    "updatedAt": "2025-01-01T10:00:00.000Z"
  },
  {
    "productCode": "LOAN_PLUS",
    "type": "loan",
    "name": "Plus Loan",
    "currency": "TZS",
    "config": { "minPrincipal": 500000, "maxPrincipal": 20000000, "tenorMonths": 24 },
    "accountingMapping": null,
    "status": "published",
    "version": 3,
    "createdAt": "2025-01-02T10:00:00.000Z",
    "updatedAt": "2025-01-10T10:00:00.000Z"
  }
]

Get Lending Product by Code

GET /api/v1/lms/lending/products/{code}
Authorization: Bearer <token>

Response

{
  "productCode": "LOAN_BASIC",
  "type": "loan",
  "name": "Basic Loan",
  "currency": "TZS",
  "config": { "minPrincipal": 100000, "maxPrincipal": 10000000, "tenorMonths": 12 },
  "accountingMapping": { "glAsset": "1101", "glIncome": "4101" },
  "status": "draft",
  "version": 1,
  "createdAt": "2025-01-01T10:00:00.000Z",
  "updatedAt": "2025-01-01T10:00:00.000Z"
}

Publish Lending Product

POST /api/v1/lms/lending/products/{code}/publish
Authorization: Bearer <token>

Response

{
  "productCode": "LOAN_BASIC",
  "type": "loan",
  "name": "Basic Loan",
  "currency": "TZS",
  "config": { "minPrincipal": 100000, "maxPrincipal": 10000000, "tenorMonths": 12 },
  "accountingMapping": { "glAsset": "1101", "glIncome": "4101" },
  "status": "published",
  "version": 2,
  "createdAt": "2025-01-01T10:00:00.000Z",
  "updatedAt": "2025-01-01T12:00:00.000Z"
}

Ensure that you publish products before making them available to your users

Loans

Create Loan Account

POST /api/v1/lms/loans
Authorization: Bearer <token>
Content-Type: application/json

{
  "businessId": "11111111-2222-3333-4444-555555555555",
  "customerId": "aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee",
  "productCode": "LOAN_BASIC",
  "amountMinor": 2500000,
  "currency": "TZS"
}

Response

{
  "loanId": "e5c8c7d2-0000-0000-0000-000000000000",
  "state": "APPLIED"
}

Get Loan Account

GET /api/v1/lms/loans/{loanId}
Authorization: Bearer <token>

Response

{
  "id": 8237,
  "accountNo": "0000008237",
  "status": { "id": 100, "value": "loanStatusType.active" },
  "loanProductId": 101,
  "loanProductName": "LOAN_BASIC",
  "principal": 25000.0,
  "currency": { "code": "TZS" }
}

Approve loan

POST /api/v1/lms/loans/{loanId}/approve
Authorization: Bearer <token>
Content-Type: application/json

{
  "approvedOnDate": "2025-01-01",
  "note": "Auto-approved by system"
}

Response

{ "status": "approved", "loanId": "e5c8c7d2-..." }

List loans

GET /api/v1/lms/loans?status=active&productCode=LOAN_BASIC&customerId=...
Authorization: Bearer <token>

Repayment schedules

GET /api/v1/lms/loans/{loanId}/schedule
Authorization: Bearer <token>

Response

{
  "loanId": "e5c8c7d2-...",
  "currency": "TZS",
  "installments": [
    { "number": 1, "dueDate": "2025-02-01", "principalMinor": 150000, "interestMinor": 50000, "totalMinor": 200000, "paid": false },
    { "number": 2, "dueDate": "2025-03-01", "principalMinor": 150000, "interestMinor": 40000, "totalMinor": 190000, "paid": false }
  ],
  "nextDue": { "number": 1, "dueDate": "2025-02-01", "totalMinor": 200000 }
}

Transactions

Disburse loan

POST /api/v1/lms/loans/{loanId}/disburse
Authorization: Bearer <token>
Content-Type: application/json

{
  "disbursedOnDate": "2025-01-02",
  "amountMinor": 2500000
}

Response

{ "status": "disbursed", "loanId": "e5c8c7d2-..." }

Repay loan

POST /api/v1/lms/loans/{loanId}/repayments
Authorization: Bearer <token>
Content-Type: application/json

{
  "amountMinor": 200000,
  "currency": "TZS"
}

Response

{
  "status": "repayment-accepted",
  "loanId": "e5c8c7d2-...",
  "amountMinor": 200000,
  "currency": "TZS"
}

Reports

Only essential, high-signal reports are shown below. All support fromDate, toDate, and optional format=json|csv|pdf.

Portfolio summary

GET /api/v1/lms/reports/portfolio-summary?fromDate=2025-01-01&toDate=2025-01-31&frequency=monthly
Authorization: Bearer <token>

Response

{
  "fromDate": "2025-01-01",
  "toDate": "2025-01-31",
  "totals": {
    "numLoans": 1200,
    "principalOutstandingMinor": 12345678900,
    "arrearsMinor": 234567800,
    "par30": 0.045
  },
  "breakdown": [
    { "key": "LOAN_BASIC", "numLoans": 800, "principalOutstandingMinor": 8234567800 },
    { "key": "LOAN_PLUS", "numLoans": 400, "principalOutstandingMinor": 4100001100 }
  ]
}

Collections

GET /api/v1/lms/reports/collections?fromDate=2025-01-01&toDate=2025-01-31&reportType=actual
Authorization: Bearer <token>

Response

{
  "fromDate": "2025-01-01",
  "toDate": "2025-01-31",
  "rows": [
    { "date": "2025-01-01", "scheduledMinor": 50000000, "collectedMinor": 48000000, "shortfallMinor": 2000000 },
    { "date": "2025-01-02", "scheduledMinor": 51000000, "collectedMinor": 50500000, "shortfallMinor": 500000 }
  ]
}

Delinquency

GET /api/v1/lms/reports/delinquency?fromDate=2025-01-01&toDate=2025-01-31&bucket=31-60
Authorization: Bearer <token>

Response

{
  "asOf": "2025-01-31",
  "bucket": "31-60",
  "counts": { "numLoans": 120, "uniqueCustomers": 110 },
  "exposureMinor": 345678900,
  "byProduct": [
    { "productCode": "LOAN_BASIC", "numLoans": 80, "exposureMinor": 245678900 },
    { "productCode": "LOAN_PLUS", "numLoans": 40, "exposureMinor": 100000000 }
  ]
}

Revenue

GET /api/v1/lms/reports/revenue?fromDate=2025-01-01&toDate=2025-01-31&revenueType=total
Authorization: Bearer <token>

NPL (Non‑Performing Loans)

GET /api/v1/lms/reports/npl?fromDate=2025-01-01&toDate=2025-01-31&daysOverdue=90&productCode=LOAN_BASIC
Authorization: Bearer <token>

Response

{
  "fromDate": "2025-01-01",
  "toDate": "2025-01-31",
  "daysOverdue": 90,
  "totals": { "numLoans": 42, "exposureMinor": 987654321 },
  "byProduct": [
    { "productCode": "LOAN_BASIC", "numLoans": 30, "exposureMinor": 700000000 },
    { "productCode": "LOAN_PLUS", "numLoans": 12, "exposureMinor": 287654321 }
  ]
}

Portfolio performance

GET /api/v1/lms/reports/portfolio/performance?fromDate=2025-01-01&toDate=2025-01-31&groupBy=product
Authorization: Bearer <token>

Response

{
  "fromDate": "2025-01-01",
  "toDate": "2025-01-31",
  "metrics": [
    {
      "key": "LOAN_BASIC",
      "newLoans": 300,
      "disbursedMinor": 7500000000,
      "repaymentsMinor": 1200000000,
      "writeOffMinor": 50000000,
      "par30": 0.038
    },
    {
      "key": "LOAN_PLUS",
      "newLoans": 120,
      "disbursedMinor": 3600000000,
      "repaymentsMinor": 600000000,
      "writeOffMinor": 20000000,
      "par30": 0.052
    }
  ]
}

Disbursements

GET /api/v1/lms/reports/disbursements?fromDate=2025-01-01&toDate=2025-01-31
Authorization: Bearer <token>

Response

{
  "fromDate": "2025-01-01",
  "toDate": "2025-01-31",
  "rows": [
    {
      "date": "2025-01-02",
      "loanId": "e5c8c7d2-...",
      "customerId": "aaaaaaaa-bbbb-...",
      "productCode": "LOAN_BASIC",
      "amountMinor": 2500000,
      "currency": "TZS"
    }
  ],
  "totals": { "count": 420, "amountMinor": 11100000000 }
}

Response

{
  "fromDate": "2025-01-01",
  "toDate": "2025-01-31",
  "totals": { "feesMinor": 1234500, "interestMinor": 5432100, "totalMinor": 6666600 },
  "byProduct": [
    { "productCode": "LOAN_BASIC", "feesMinor": 600000, "interestMinor": 3000000, "totalMinor": 3600000 },
    { "productCode": "LOAN_PLUS", "feesMinor": 634500, "interestMinor": 2432100, "totalMinor": 3066600 }
  ]
}

Finance

General ledger

GET /api/v1/lms/reports/ledger?fromDate=2025-01-01&toDate=2025-01-31&glAccountId=1101
Authorization: Bearer <token>

Response

{
  "glAccountId": "1101",
  "fromDate": "2025-01-01",
  "toDate": "2025-01-31",
  "entries": [
    { "date": "2025-01-05", "description": "Loan disbursement", "debitMinor": 250000000, "creditMinor": 0, "balanceMinor": 250000000 },
    { "date": "2025-01-10", "description": "Repayment", "debitMinor": 0, "creditMinor": 2000000, "balanceMinor": 248000000 }
  ]
}

Trial balance

GET /api/v1/lms/reports/trial-balance?fromDate=2025-01-01&toDate=2025-01-31
Authorization: Bearer <token>

Response

{
  "asOf": "2025-01-31",
  "accounts": [
    { "glAccountId": "1101", "name": "Loans outstanding", "debitMinor": 250000000, "creditMinor": 0, "balanceMinor": 250000000 },
    { "glAccountId": "4101", "name": "Interest income", "debitMinor": 0, "creditMinor": 5432100, "balanceMinor": -5432100 }
  ]
}

Product APIs

​Overview

​Get a token

​Product management

​Create Lending Product

​Get Available Lending Products

​Get Lending Product by Code

​Publish Lending Product

​Loans

​Create Loan Account

​Get Loan Account

​Approve loan

​List loans

​Repayment schedules

​Transactions

​Disburse loan

​Repay loan

​Reports

​Portfolio summary

​Collections

​Delinquency

​Revenue

​NPL (Non‑Performing Loans)

​Portfolio performance

​Disbursements

​Finance

​General ledger

​Trial balance

Overview

Get a token

Product management

Create Lending Product

Get Available Lending Products

Get Lending Product by Code

Publish Lending Product

Loans

Create Loan Account

Get Loan Account

Approve loan

List loans

Repayment schedules

Transactions

Disburse loan

Repay loan

Reports

Portfolio summary

Collections

Delinquency

Revenue

NPL (Non‑Performing Loans)

Portfolio performance

Disbursements

Finance

General ledger

Trial balance