Finecko Documentation

Appearance

Teller & Cash Management ​

The Teller module tracks physical cash movement through your branches. Each branch can have one or more tellers (cashiers) with a defined cash float. Cash-in and cash-out transactions are recorded against the teller's position and reconciled at end of day.

Scope

The Teller module covers cash desk operations - physical cash handled by branch staff. Loan repayments and savings deposits recorded by loan officers go through the standard transaction APIs. Teller is a separate layer for branches that need to manage a physical float.

Tellers ​

A teller represents a cash desk or branch vault. It belongs to an office (branch) and holds the overall cash position for that desk.

Creating a teller ​

bash
POST /fineract-provider/api/v1/tellers
Authorization: Basic <base64>
Fineract-Platform-TenantId: default
Content-Type: application/json
json
{
  "officeId": 1,
  "name": "Main Branch Till",
  "description": "Primary teller counter, ground floor",
  "startDate": "01 January 2025",
  "status": 300,
  "dateFormat": "dd MMMM yyyy",
  "locale": "en"
}
FieldRequiredMeaning
officeIdYesThe branch this teller belongs to
nameYesDisplay name for the teller desk
startDateYesDate from which this teller is operational
statusNo300 = Active, 400 = Inactive. Defaults to Active

Listing tellers ​

bash
# All tellers
GET /fineract-provider/api/v1/tellers

# Tellers for a specific office
GET /fineract-provider/api/v1/tellers?officeId=1

# A single teller
GET /fineract-provider/api/v1/tellers/{tellerId}

Updating a teller ​

bash
PUT /fineract-provider/api/v1/tellers/{tellerId}
json
{
  "name": "Main Branch Till - Renamed",
  "status": 400,
  "locale": "en"
}

Cashiers ​

A cashier is a staff member assigned to operate a teller. One teller can have multiple cashiers (for shift work or multiple operators). Each cashier has a time-bounded assignment with an allocated starting balance.

Assigning a cashier to a teller ​

bash
POST /fineract-provider/api/v1/tellers/{tellerId}/cashiers
Authorization: Basic <base64>
Fineract-Platform-TenantId: default
Content-Type: application/json
json
{
  "staffId": 3,
  "description": "Morning shift cashier",
  "startDate": "01 March 2025",
  "endDate": "31 December 2025",
  "isFullDay": true,
  "startTime": "",
  "endTime": "",
  "locale": "en",
  "dateFormat": "dd MMMM yyyy"
}
FieldMeaning
staffIdID of the staff member assigned as cashier
startDate / endDateValidity window for this assignment
isFullDayIf true, the cashier operates the full working day
startTime / endTimeWhen isFullDay: false, specify shift hours (HH:mm format)

Listing cashiers for a teller ​

bash
GET /fineract-provider/api/v1/tellers/{tellerId}/cashiers

Allocating Cash to a Cashier ​

Before a cashier can record transactions, their cash drawer must be funded. Cash is allocated from the branch vault to the cashier at the start of a shift.

bash
POST /fineract-provider/api/v1/tellers/{tellerId}/cashiers/{cashierId}/allocate
Authorization: Basic <base64>
Fineract-Platform-TenantId: default
Content-Type: application/json
json
{
  "currencyCode": "USD",
  "txnAmount": 5000.00,
  "txnNote": "Opening float for morning shift",
  "txnDate": "01 March 2025",
  "dateFormat": "dd MMMM yyyy",
  "locale": "en"
}

This creates an allocation transaction that increases the cashier's cash position. The txnAmount is the opening balance provided to the cashier.

Recording Cash Transactions ​

Cashiers can record cash-in and cash-out transactions against their teller position. These are manual cash movements (not linked to loan or savings accounts).

Cash in (receiving cash) ​

bash
POST /fineract-provider/api/v1/tellers/{tellerId}/cashiers/{cashierId}/transactions?type=cash_in
json
{
  "currencyCode": "USD",
  "txnAmount": 200.00,
  "txnNote": "Cash deposit from client walk-in",
  "txnDate": "01 March 2025",
  "paymentTypeId": 1,
  "dateFormat": "dd MMMM yyyy",
  "locale": "en"
}

Cash out (disbursing cash) ​

bash
POST /fineract-provider/api/v1/tellers/{tellerId}/cashiers/{cashierId}/transactions?type=cash_out
json
{
  "currencyCode": "USD",
  "txnAmount": 150.00,
  "txnNote": "Loan disbursement to John Kamau",
  "txnDate": "01 March 2025",
  "paymentTypeId": 1,
  "dateFormat": "dd MMMM yyyy",
  "locale": "en"
}

Viewing cashier transactions ​

bash
# All transactions for a cashier
GET /fineract-provider/api/v1/tellers/{tellerId}/cashiers/{cashierId}/transactions

# With date filter
GET /fineract-provider/api/v1/tellers/{tellerId}/cashiers/{cashierId}/transactions?fromDate=01 March 2025&toDate=31 March 2025&dateFormat=dd MMMM yyyy&locale=en

Settling a Cashier (End-of-Day) ​

At end of shift, the cashier returns their remaining cash to the vault. The settle transaction records the amount handed back.

bash
POST /fineract-provider/api/v1/tellers/{tellerId}/cashiers/{cashierId}/settle
Authorization: Basic <base64>
Fineract-Platform-TenantId: default
Content-Type: application/json
json
{
  "currencyCode": "USD",
  "txnAmount": 4850.00,
  "txnNote": "End-of-day settlement",
  "txnDate": "01 March 2025",
  "dateFormat": "dd MMMM yyyy",
  "locale": "en"
}

After settling, the cashier's running balance should return to zero (or the expected float). Any variance between the expected balance and the settled amount represents a discrepancy to be investigated.

Checking the Cashier's Running Balance ​

bash
GET /fineract-provider/api/v1/tellers/{tellerId}/cashiers/{cashierId}/summaryandtransactions

The response includes:

  • cashierData - the cashier and staff details
  • savingsTransactions - list of all allocation, cash-in, cash-out, and settle transactions
  • Running total that reflects the current cash position

Teller Cash Summary by Currency ​

To see the overall cash position across all cashiers for a teller:

bash
GET /fineract-provider/api/v1/tellers/{tellerId}/cashiers/summaryandtransactions?currencyCode=USD

Typical End-to-End Shift Flow ​

Morning:
1. Manager allocates opening float to cashier → POST .../allocate
2. Cashier receives payments (loan repayments, savings deposits) → POST .../transactions?type=cash_in
3. Cashier disburses cash (loan disbursements, savings withdrawals) → POST .../transactions?type=cash_out

End of day:
4. Cashier counts physical cash
5. Supervisor runs GET .../summaryandtransactions to see expected balance
6. Cashier settles the drawer → POST .../settle
7. Variance (if any) is investigated and journal-adjusted manually

Common Mistakes ​

MistakeEffectFix
No allocation before recording transactionsCashier starts with zero balance; any cash-out creates a negative positionAlways allocate opening float before the first transaction
Using teller transactions for loan repayments instead of the loan APIRepayments do not update the loan scheduleRecord loan repayments via POST /loans/{loanId}/transactions?command=repayment; teller transactions are for physical cash tracking only
Settling for the wrong amountRunning balance does not zero outVerify the expected balance from summaryandtransactions before settling
Assigning the same staff as cashier on overlapping date ranges on the same tellerDuplicate assignment errorsCheck existing cashier assignments before creating new ones