Finecko Documentation

Appearance

Payment Types & System Codes ​

Payment types and system codes are foundational configuration that must be set up before staff can record transactions. Every repayment, disbursement, deposit, and withdrawal requires a payment type. 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. Payment types appear in every transaction form and API call.

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 any transaction, 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 code name (fixed, system-defined) and a set of code values (configurable).

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)
LoanCollateralTypeTypes of collateral (land, vehicle, jewellery, savings)
GenderClient gender options
ClientTypeClient classification (individual, small business, cooperative)
ClientClassificationCustomer segment (e.g., rural, urban, SME)
AddressTypeAddress classification (home, business, postal)
YesNoBoolean dropdown for various fields
RelationshipRelationship types for next of kin
MaritalStatusClient marital status options
ProfessionClient profession/occupation options
EducationLevelClient education level options

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/codevalues?name=Customer+Identifier

Client Identifier Types ​

Client identifiers allow storing official identification document references against client profiles. Set up identifier types before onboarding clients:

bash
# Get the "Customer Identifier" code ID
GET /fineract-provider/api/v1/codes?name=Customer+Identifier

# Add identifier types as code values
POST /fineract-provider/api/v1/codes/{codeId}/codevalues
json
{ "name": "National ID", "position": 1, "isActive": true }
json
{ "name": "Passport", "position": 2, "isActive": true }
json
{ "name": "Driver's Licence", "position": 3, "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 are managed as code values under LoanCollateralType:

bash
# Get LoanCollateralType code ID
GET /fineract-provider/api/v1/codes?name=LoanCollateralType

# 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 LoanCollateralType
  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.