Standing Instructions

Standing Instructions are automated recurring transactions that execute on a defined schedule without manual intervention. The most common use case is automatically debiting a client's savings account to service their loan repayment - eliminating the need for the client to remember to pay each period.

---

What Standing Instructions Can Do

Transfer from	Transfer to	Use case
Savings account	Loan account	Auto-debit loan repayment from savings
Savings account	Savings account	Automated sweep between accounts
Savings account	Another client's account	Inter-account transfer

Standing instructions execute based on their configured schedule and the available balance in the source account. If the source account has insufficient funds, the instruction fails for that cycle (it does not retry within the same period).

---

Creating a Standing Instruction

POST /fineract-provider/api/v1/standinginstructions
Authorization: Basic <base64>
Fineract-Platform-TenantId: default
Content-Type: application/json

Example: Monthly loan repayment from savings

{
  "name": "Monthly Loan Repayment - Loan 234",
  "clientId": 101,
  "fromAccountType": 2,
  "fromAccountId": 45,
  "toClientId": 101,
  "toAccountType": 1,
  "toAccountId": 234,
  "instructionType": 1,
  "amount": 150.00,
  "validFrom": "01 April 2025",
  "validTill": "01 April 2027",
  "recurrenceType": 2,
  "recurrenceFrequency": 1,
  "recurrenceInterval": 1,
  "recurrenceOnMonthDay": "01 January",
  "priority": 1,
  "status": 1,
  "transferType": 3,
  "dateFormat": "dd MMMM yyyy",
  "monthDayFormat": "dd MMMM",
  "locale": "en"
}

---

Field Reference

Account type codes

Code	Type
1	Loan account
2	Savings account

Instruction type

Code	Meaning
1	Fixed amount - transfer exactly amount each cycle
2	Outstanding balance - transfer the full outstanding balance
3	Due for repayment - transfer whatever is due on the loan that day

instructionType: 3 (Due for repayment) is the most useful for loan servicing - it transfers exactly what is due on each repayment date, adapting automatically to the loan schedule.

Recurrence type

Code	Meaning
1	Periodic - runs every N periods
2	As per loan repayment date - runs on the loan's actual repayment dates

recurrenceType: 2 (As per loan repayment date) is recommended when the purpose is loan servicing - the instruction fires on each instalment due date rather than on a fixed calendar interval.

Recurrence frequency (when recurrenceType = 1)

Code	Period
1	Days
2	Weeks
3	Months
4	Years

recurrenceInterval sets how many periods between executions: 1 = every period, 3 = every 3 periods.

Priority

When a client has multiple standing instructions from the same source account, priority (integer, lower = higher priority) determines execution order when the account balance is insufficient to cover all of them.

Status

Code	Meaning
1	Active
2	Disabled
3	Deleted
4	Expired (past validTill date)

Transfer type

Code	Meaning
1	Account transfer
2	Loan repayment
3	Charge payment

---

When Instructions Execute

Standing instructions are processed by the Standing Instruction History Job, a scheduled batch job that runs on a configured schedule (typically daily). It evaluates all active instructions, checks whether today is an execution date, and attempts the transfer.

Check the job schedule:

GET /fineract-provider/api/v1/jobs

Look for Execute Standing Instruction. Ensure it is scheduled to run daily, typically before business opens.

---

Viewing Standing Instructions

# All standing instructions for a client
GET /fineract-provider/api/v1/standinginstructions?clientId=101

# All instructions for a specific account
GET /fineract-provider/api/v1/standinginstructions?fromAccountId=45&fromAccountType=2

# A single instruction
GET /fineract-provider/api/v1/standinginstructions/{instructionId}

---

Execution History

Each standing instruction maintains a history of its executions:

GET /fineract-provider/api/v1/standinginstructions/{instructionId}/history

Response includes:

{
  "pageItems": [
    {
      "id": 55,
      "standingInstructionId": 12,
      "status": "Success",
      "amount": 150.00,
      "executionTime": "2025-04-01T06:00:00Z",
      "errorLog": null
    },
    {
      "id": 48,
      "standingInstructionId": 12,
      "status": "Failure",
      "amount": 150.00,
      "executionTime": "2025-03-01T06:00:00Z",
      "errorLog": "Insufficient funds in account 45"
    }
  ]
}

Failed executions appear in the history with an errorLog but do not block future execution attempts.

---

Updating a Standing Instruction

PUT /fineract-provider/api/v1/standinginstructions/{instructionId}?command=update

{
  "amount": 175.00,
  "validTill": "01 April 2028",
  "dateFormat": "dd MMMM yyyy",
  "locale": "en"
}

---

Disabling and Deleting

# Disable (keeps the instruction but stops execution)
PUT /fineract-provider/api/v1/standinginstructions/{instructionId}?command=update
{ "status": 2 }

# Delete
DELETE /fineract-provider/api/v1/standinginstructions/{instructionId}

---

Savings Account Link on Loan Products

For standing instructions to work for loan servicing, the loan product should allow a linked savings account (linkedAccountAllowed: true). When a savings account is linked at the loan level:

PUT /fineract-provider/api/v1/loans/{loanId}?command=linkDebitAccount

{
  "debitAccountId": 45
}

A standing instruction can then reference this linked savings account as the source.

---

Common Issues

Issue	Cause	Fix
Instruction never executes	Execute Standing Instruction job not scheduled	Enable and schedule the job via the scheduler API
Instruction executes but source has no funds	Savings balance is zero or below minimum	Ensure clients fund their savings before the execution date
Wrong amount transferred	instructionType: 1 used with a fixed amount that no longer matches the due amount	Switch to instructionType: 3 for dynamic due-amount transfers
Instruction expired	validTill date has passed	Update validTill to extend the instruction