cURL
Loans
Get Loan Payment Plan
Returns the loan’s active payment plan: its terms, the cadence rule it was created under, reconciliation totals, every scheduled payment, and the payments made against them.
Responds 200 with paymentPlan: null when the loan has no active plan — a normal state (never enrolled, or the plan completed or was cancelled), and deliberately distinct from 404, which means the loan itself was not found.
Supports If-None-Match: an unchanged plan responds 304, so polling a whole portfolio stays cheap.
GET
cURL
Overview
Returns the loan’s active payment plan — its terms, the cadence rule it was created under, reconciliation totals, every scheduled payment, and the payments made against them. Use it to board the payment plan into your own servicing system and to reconcile the payments you have collected against it. When a plan is agreed with a borrower through the borrower portal, an agent, or an automated call, it exists only on the Finosu side until you pull it. The plan identified is always the current one. Superseded plans are not returned.Which scheduled payments to board
scheduledPayments[].status is the single field that answers this. Board a scheduled payment only when its status is one of:
Every other status means the scheduled payment is not a live obligation and must not be boarded:
OVERDUE and MISSED both describe non-payment, and the difference matters.
With OVERDUE the money is still owed on that scheduled payment, so keep
collecting against it. With MISSED the amount has already been carried onto a
later scheduled payment, so collecting against the MISSED one would count the
same money twice.Reading the money
remainingAmount is a sum over scheduled payments
totals.remainingAmount is the sum of amountRemaining across scheduled payments whose status is PENDING, PARTIALLY_PAID or OVERDUE.
remainingAmount is the balance, already computed from the scheduled payments.creditsApplied is money that paidToDate has already counted. It comes from
overpayments, where the excess on one scheduled payment is applied to another, so
subtracting it from discountedTotal alongside paidToDate would deduct the same
money twice.remainingAmount is summed from the scheduled payments, so it stays correct
however credit arises.amountRemaining is only meaningful on live scheduled payments
Every scheduled payment reports max(0, scheduledAmount - amountPaid - creditsApplied), including ones that are no longer obligations. A MISSED or POSTPONED scheduled payment therefore shows a non-zero amountRemaining even though that amount has moved elsewhere.
Sum amountRemaining only across scheduled payments whose status is PENDING, PARTIALLY_PAID or OVERDUE, or use totals.remainingAmount, which does this for you.
offPlatformPaymentsTotal is a portion of paidToDate
It reports how much of what paidToDate already counts was collected outside Finosu (payments with source: "EXTERNAL").
This is a portion of
paidToDate, not a separate amount to add to it. The
off-platform payments it reports are already counted there, so adding the two
together would count each of them twice.Totals you can verify against the scheduled payments
These identities always hold, so you can check our totals against the detail we give you:Credits
creditsApplied is credit applied to a scheduled payment from the loan’s credit balance.
That balance comes from overpayments. When a payment covers more than the scheduled payment it was applied to, the excess is held as credit and later applied to another scheduled payment.
Credit is reported separately from amountPaid because the money was already counted once, as a payment against the scheduled payment the overpayment landed on. Counting it again would double it.
Dates and timing
scheduledPayments[].dueDateis authoritative for when a scheduled payment is actually due. It carries a UTC offset and reflects any rescheduling.cadencedescribes the rule the plan was created under, not the current scheduled payments. Its anchor days derive from the plan’s original start date, which does not change when a schedule is rebuilt — so after a reschedulecadencecan disagree with the actual due dates. Use it to understand the intended pattern; usedueDatefor real dates.transactedAtandfinalizedAtare Finosu-side timestamps, not bank confirmations.transactedAtis when the payment was submitted or took effect;finalizedAtis when Finosu considers it settled. For ACH, neither is a guarantee of when funds moved at your bank. Apply your own settlement rules.
Identifiers
planIdidentifies the plan and is stable for the life of the plan.scheduledPaymentIdandpaymentIdare stable Finosu identifiers. Store them if you want to correlate across polls.referenceon a payment echoes the external reference you supplied when recording it, so you can join back to your own ledger.
When there is no plan
A200 response with paymentPlan: null means the loan exists but has no active plan. This is normal — the borrower may never have enrolled, or the plan may have completed or been cancelled.
A 404 is different: it means no loan with that reference exists for your company. Treat it as an integration error, not a business state.
Polling efficiently
The response carries anETag. Send it back as If-None-Match and an unchanged plan responds 304 Not Modified with no body, which keeps a nightly sweep across a portfolio cheap.
Example
A biweekly plan viewed in late June, showing five of the eight possible statuses:PAID (by two payments, the second of which overpaid it), MISSED, OVERDUE, PARTIALLY_PAID (from the resulting credit), and PENDING. SKIPPED, POSTPONED and CANCELLED are not shown here — see the status tables above for all eight.
scheduledAmount values may not sum to discountedTotal. scheduledPayments
includes scheduled payments that are no longer obligations, whose amounts were
moved onto others or forgiven, so they can total more than the plan itself. In
this example the five come to 1033.35 against a discountedTotal of 826.68.
The difference is the MISSED scheduled payment, whose amount now sits on a
later one.discountedTotal is the authorized total, and remainingAmount the
outstanding balance.amountPaid: 300.00 against a scheduledAmount of 206.67. It reports only the outcome (PAID) — that it took two payments, and that the borrower was five days late completing it, is visible only in payments[]. Note the first of those payments has source: "EXTERNAL", which is why offPlatformPaymentsTotal is 100.00: money the lender collected and uploaded, already counted inside paidToDate.
The 93.33 excess (300.00 - 206.67) appears as creditsApplied on the fourth scheduled payment, which is why it is PARTIALLY_PAID with amountRemaining: 113.34 despite amountPaid: 0.00.
The second scheduled payment is MISSED. Its FAILED payment is in payments[], and its amount was carried onto a later scheduled payment. Do not board it, or you would collect the same money twice.
Checking the balance: remainingAmount (526.68) is the sum of amountRemaining across the three boardable scheduled payments (206.67 + 113.34 + 206.67), and equals discountedTotal - paidToDate (826.68 - 300.00). It is not discountedTotal - paidToDate - creditsApplied (433.35). That would deduct the 93.33 twice: once as the payment that created it, and again as the credit it became.
Error Responses
Authorizations
Path Parameters
External reference ID of the loan
Query Parameters
Include scheduled payments that are no longer live obligations (MISSED, SKIPPED, POSTPONED, CANCELLED). Defaults to true so the schedule's history stays explicable.
Response
The loan's active payment plan, or null if it has none
Response for GET /loans/{id}/payment-plan.
The loan's external reference, echoing the request path.
The customer's reference id.
The active payment plan, or null if the loan has none. A null plan is a normal state (never enrolled, or the plan completed or was cancelled) and is distinct from a 404, which means the loan itself was not found.