Guide

Payment plans and expected payments

Send a plan as terms Fence calculates or as your own schedule, change it, and read the expected payments.

A payment plan says how an asset is meant to be repaid. From it, Fence keeps the asset's expected payments: what it expects on each date.

Two ways to send a plan

Your program says which modes it takes. An asset's plan keeps the mode it was first sent in.

Built: you send the loan's terms, and Fence calculates the schedule. plan_type (equal_instalments, equal_principal, bullet, interest_only), term_periods and start_date are required. The rate (annual_rate_bps, 100 is 1%), frequency and day_count may be left out when your program gives defaults. Terms carry no principal: the principal is the money actually paid out, which your disbursements declare.

Custom: you send your own schedule in lines, and Fence keeps it as sent. Each line has a due_date, its principal, interest and fees (0 when left out) and a line_id, your key for that instalment. Send the same line_id for the same instalment every time; a line without one is refused.

{"records": [
  {"asset_id": "L-123", "currency": "EUR",
   "terms": {"plan_type": "equal_instalments", "term_periods": 12, "start_date": "2026-10-01",
             "annual_rate_bps": "1200", "frequency": "monthly"}},
  {"asset_id": "L-124", "currency": "EUR",
   "lines": [{"line_id": "L-124-1", "due_date": "2026-11-01",
              "principal": "100.00", "interest": "4.50", "fees": "0.00"}]}
]}

Send it to POST …/submissions/payment-plans. A plan for an asset Fence does not hold yet is refused asset_not_declared, so send assets first.

Changing a plan

One plan is in force per asset. Each plan you send replaces it from its effective_from date. Say why with reason:

Reason	When
`initial`	The asset's first plan.
`normal_change`	A change the loan's terms allow.
`correction`	The earlier plan was wrong. Only a correction may change the past.
`forbearance`	Relief for a borrower in difficulty, with a `forbearance_type`: `payment_holiday`, `term_extension` or `rate_reduction`.
`re_age`	Arrears folded back into the schedule. Your program sets how many it accepts.

Expected payments

Each row of an asset's schedule is an expected payment. Its kind is collection, money the borrower owes, or disbursement, the payout Fence expects from each disbursement you declare. Each row has a reference: your line_id, or one Fence made. Payments name these references in instalment_keys.

Rows are never edited: a new plan replaces them, and every version stays readable at GET …/assets/{id}/expected-payments/history.

The program-wide list shows each current row with what was paid, diluted and left, and its status: unpaid, partly_paid or paid.

curl -s "$FENCE_API/v1/api/asset-programs/$PROGRAM_ID/expected-payments?from=2026-11-01&to=2026-11-30" \
  -H "Authorization: Bearer $TOKEN"