Skip to content

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/json
json
{
  "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
}
FieldMeaning
nameDisplay name shown in UI and API responses
descriptionOptional description for internal reference
isCashPaymenttrue for physical cash; affects teller cash management
positionSort order in dropdown lists
NameisCashPaymentNotes
CashtruePhysical cash at branch
Bank TransferfalseWire / EFT
Mobile MoneyfalseM-Pesa, MTN, Airtel, etc.
ChequefalsePaper cheque
POSfalsePoint of sale terminal
Standing OrderfalseAutomatic bank standing order

Listing payment types ​

bash
GET /fineract-provider/api/v1/paymenttypes

Using 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/codes

Important system code types ​

Code nameUsed for
Customer IdentifierTypes of client identification documents (passport, national ID, driver's licence)
LoanCollateralTypes of collateral (land, vehicle, jewellery, savings)
GenderClient gender options
ClientTypeClient classification (individual, small business, cooperative)
ClientClassificationCustomer segment (e.g., rural, urban, SME)
ADDRESS_TYPEAddress classification (home, business, postal)
RELATIONSHIPRelationship of a client's family members
MARITAL STATUSMarital status of a client's family members
PROFESSIONProfession of a client's family members

Adding code values ​

Find the code ID first:

bash
GET /fineract-provider/api/v1/codes

Then add a value to it:

bash
POST /fineract-provider/api/v1/codes/{codeId}/codevalues
json
{
  "name": "National ID",
  "description": "Government-issued national identity card",
  "position": 1,
  "isActive": true
}

Listing code values ​

bash
GET /fineract-provider/api/v1/codes/{codeId}/codevalues

Or by code name:

bash
GET /fineract-provider/api/v1/codes/name/Customer%20Identifier/codevalues

Client 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}/codevalues
json
{ "name": "National ID", "position": 1, "isActive": true }

Attach an identifier to a client:

bash
POST /fineract-provider/api/v1/clients/{clientId}/identifiers
json
{
  "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}/codevalues
json
{ "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/funds
json
{
  "name": "World Bank Development Fund"
}

Assign a fund to a loan product or individual loan account:

json
{
  "fundId": 2
}

Before creating any loan or savings products, ensure the following are configured:

  1. Payment types - Cash, bank transfer, mobile money at minimum
  2. Customer identifier types - Code values under Customer Identifier
  3. Collateral types - Code values under LoanCollateral
  4. Client classification types - Code values under ClientClassification
  5. Gender - Code values under Gender
  6. 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.