Appearance
Payment Types & System Codes
Payment types and system codes are foundational configuration to set up before staff record transactions. Deposits and withdrawals on savings accounts require a payment type; on loan repayments and disbursements it is optional. System codes define dropdown lists throughout the platform.
Payment Types
A payment type represents the channel through which a transaction is made - cash, bank transfer, mobile money, cheque, etc. Loan and savings transaction templates list them as paymentTypeOptions, and transaction requests refer to one by paymentTypeId.
Creating a payment type
bash
POST /fineract-provider/api/v1/paymenttypes
Authorization: Basic <base64>
Fineract-Platform-TenantId: default
Content-Type: application/jsonjson
{
"name": "Cash",
"description": "Physical cash payment",
"isCashPayment": true,
"position": 1
}json
{
"name": "Mobile Money",
"description": "M-Pesa or similar mobile money transfer",
"isCashPayment": false,
"position": 2
}json
{
"name": "Bank Transfer",
"description": "Direct bank transfer",
"isCashPayment": false,
"position": 3
}| Field | Meaning |
|---|---|
name | Display name shown in UI and API responses |
description | Optional description for internal reference |
isCashPayment | true for physical cash; affects teller cash management |
position | Sort order in dropdown lists |
Recommended payment types to create
| Name | isCashPayment | Notes |
|---|---|---|
| Cash | true | Physical cash at branch |
| Bank Transfer | false | Wire / EFT |
| Mobile Money | false | M-Pesa, MTN, Airtel, etc. |
| Cheque | false | Paper cheque |
| POS | false | Point of sale terminal |
| Standing Order | false | Automatic bank standing order |
Listing payment types
bash
GET /fineract-provider/api/v1/paymenttypesUsing a payment type in transactions
When recording a loan repayment or a savings deposit or withdrawal, include the paymentTypeId:
json
{
"transactionDate": "15 March 2025",
"transactionAmount": 150.00,
"paymentTypeId": 1,
"dateFormat": "dd MMMM yyyy",
"locale": "en"
}System Codes
System codes are administrator-configurable dropdown lists used throughout Fineract. They control the options available in many fields without requiring code changes. Each code has a name and a set of code values. The values are configurable; system-defined codes cannot be renamed or deleted, and you can add codes of your own.
Listing all code types
bash
GET /fineract-provider/api/v1/codesImportant system code types
| Code name | Used for |
|---|---|
Customer Identifier | Types of client identification documents (passport, national ID, driver's licence) |
LoanCollateral | Types of collateral (land, vehicle, jewellery, savings) |
Gender | Client gender options |
ClientType | Client classification (individual, small business, cooperative) |
ClientClassification | Customer segment (e.g., rural, urban, SME) |
ADDRESS_TYPE | Address classification (home, business, postal) |
RELATIONSHIP | Relationship of a client's family members |
MARITAL STATUS | Marital status of a client's family members |
PROFESSION | Profession of a client's family members |
Adding code values
Find the code ID first:
bash
GET /fineract-provider/api/v1/codesThen add a value to it:
bash
POST /fineract-provider/api/v1/codes/{codeId}/codevaluesjson
{
"name": "National ID",
"description": "Government-issued national identity card",
"position": 1,
"isActive": true
}Listing code values
bash
GET /fineract-provider/api/v1/codes/{codeId}/codevaluesOr by code name:
bash
GET /fineract-provider/api/v1/codes/name/Customer%20Identifier/codevaluesClient Identifier Types
Client identifiers allow storing official identification document references against client profiles. A new Fineract tenant already has Passport, Id, Drivers License and Any Other Id Type under Customer Identifier, and value names must be unique within a code, so add only the types you are missing. Set up identifier types before onboarding clients:
bash
# Get the "Customer Identifier" code and its ID
GET /fineract-provider/api/v1/codes/name/Customer%20Identifier
# Add identifier types as code values
POST /fineract-provider/api/v1/codes/{codeId}/codevaluesjson
{ "name": "National ID", "position": 1, "isActive": true }Attach an identifier to a client:
bash
POST /fineract-provider/api/v1/clients/{clientId}/identifiersjson
{
"documentTypeId": 1,
"documentKey": "ID-123456789",
"description": "National ID card",
"locale": "en"
}Collateral Types
Collateral types for loan collateral records (/loans/{loanId}/collaterals) are managed as code values under LoanCollateral:
bash
# Get the LoanCollateral code and its ID
GET /fineract-provider/api/v1/codes/name/LoanCollateral
# Add collateral types
POST /fineract-provider/api/v1/codes/{codeId}/codevaluesjson
{ "name": "Real Estate / Land", "position": 1, "isActive": true }
{ "name": "Vehicle", "position": 2, "isActive": true }
{ "name": "Savings / Fixed Deposit", "position": 3, "isActive": true }
{ "name": "Jewellery", "position": 4, "isActive": true }
{ "name": "Group Guarantee", "position": 5, "isActive": true }Fund Sources
Fund sources represent the origin of loan capital - useful for tracking loans backed by different funding lines (donor funds, own capital, bond issuance).
bash
POST /fineract-provider/api/v1/fundsjson
{
"name": "World Bank Development Fund"
}Assign a fund to a loan product or individual loan account:
json
{
"fundId": 2
}Recommended Setup Order
Before creating any loan or savings products, ensure the following are configured:
- Payment types - Cash, bank transfer, mobile money at minimum
- Customer identifier types - Code values under
Customer Identifier - Collateral types - Code values under
LoanCollateral - Client classification types - Code values under
ClientClassification - Gender - Code values under
Gender - Fund sources - If tracking loan funding origin
This takes 15-30 minutes for a standard setup and avoids missing dropdowns when staff start onboarding clients.