Promise to Pay

Promise to Pay functionality lets back-office teams capture, monitor, and enforce customer commitments to pay over a defined schedule. It keeps promises separate from the loan’s normal schedule, tracks standing, and provides APIs to create, evaluate, and close promises.

What It Covers

Create a promise – Set amount, start date, frequency (weekly/biweekly/monthly) or bespoke installment list, and number of installments.
Standing tracking – Marks plans GOOD_STANDING when installments due to date are paid, BAD_STANDING when any due installment is unpaid/partial.
Plan lifecycle – ACTIVE when created, COMPLETED when all installments are paid after maturity, DEFAULTED when unpaid past maturity, CANCELLED with required reason.
Installment status – Each installment moves through SCHEDULED → DUE → PAID/PARTIALLY_PAID/MISSED with cancellation inherited if the plan is cancelled.
Evaluation – Run evaluation manually or on a daily batch job to update standing, mark missed installments, and close matured plans.

Lifecycle (Plan & Installments)

Event	Plan State	Installments	Standing
Promise created	`ACTIVE`	Schedule generated (`SCHEDULED`)	`GOOD_STANDING`
Evaluation hits due date	`ACTIVE`	Due installments marked `DUE`; overdue become `MISSED` if unpaid	`GOOD` or `BAD` based on payments
Installment paid	`ACTIVE`	Specific installment → `PAID` (or `PARTIALLY_PAID`)	Recomputed on next evaluation
Plan cancelled	`CANCELLED`	Remaining installments → `CANCELLED`; reason required	n/a
Plan matures, all paid	`COMPLETED`	All installments `PAID`	`GOOD_STANDING`
Plan matures, unpaid balance	`DEFAULTED`	Remaining installments `MISSED`/`PARTIALLY_PAID`	`BAD_STANDING`

flowchart TD
    A[Create Promise to pay plan<br/>ACTIVE + GOOD_STANDING<br/>Promised Installments = SCHEDULED] --> B[Evaluate manually OR daily job]
    B --> C{Any installment due or past due?}
    C -->|Yes| D[Mark due; if past due and unpaid -> MISSED<br/>Recompute standing]
    C -->|No| E[No change]
    D --> F{Plan matured?}
    E --> F
    F -->|All installments paid| G[COMPLETED<br/>GOOD_STANDING]
    F -->|Unpaid balance| H[DEFAULTED<br/>BAD_STANDING]
    A --> I[Cancel plan]
    I --> J[CANCELLED<br/>Remaining installments CANCELLED]

API Snapshot (Public)

List: GET /v1/loans/{loanId}/promises-to-pay (filter by statuses)
Create: POST /v1/loans/{loanId}/promises-to-pay (amount, frequency or custom installments, start date)
Evaluate: POST /v1/loans/{loanId}/promises-to-pay/{promiseId}/evaluate (as-of date optional)
Cancel: POST /v1/loans/{loanId}/promises-to-pay/{promiseId}/cancel (reason required)
Get: GET /v1/loans/{loanId}/promises-to-pay/{promiseId}
(Optional) List installments: Included in plan payloads; shows per-installment status and amounts.

Permissions: READ_PROMISE_TO_PAY, CREATE_PROMISE_TO_PAY, EVALUATE_PROMISE_TO_PAY, CANCEL_PROMISE_TO_PAY.

Usage Notes

One active plan per loan: Keep promises mutually exclusive to avoid conflicting commitments.
Standing as a gate: Use BAD_STANDING to trigger follow-ups, escalations, or block new promises until caught up.
Evaluation cadence: Daily batch keeps promises current; trigger manual evaluation after significant payments to refresh standing immediately.
Payment behavior: Normal loan payments reduce promised installment balances; partial payments keep installments PARTIALLY_PAID until the next evaluation.
Custom schedules: Use bespoke installment lists for negotiated dates/amounts; frequency templates suit standard weekly/biweekly/monthly promises.
Cancellations: Require reasons to preserve audit; cancelled plans stop evaluating and mark remaining installments cancelled.
Maturity outcomes: At maturity, evaluation closes plans as COMPLETED if fully paid, otherwise DEFAULTED; use this to drive collections or account notes.
No impact on loan schedule: Promise to Pay does not alter the underlying loan amortization or due dates; it overlays a separate commitment tracker while normal loan payments continue to apply.