Upcoming API Changes

Summary

Payment-plan retrieval is proposed and is not yet available. We are tightening the required-field contract on POST /customers and POST /customers/batch so that every customer we board arrives with the data needed to contact them lawfully and verify their identity. The redundant loanId field is being removed at the same time. The proposed required-field and loanId changes remain unenforced. We will notify partners before introducing those changes. Endpoints affected by the Create a Customer required-field changes:

POST /customers
POST /customers/batch customer-create rows (same per-customer payload); scheduleMode: "enroll" rows use origination enrollment and are not affected by the required-field changes

PUT /customers/{id} and loan, call, text, and payment endpoints are not affected by the proposed required-field changes. Customer updates do participate in the validation-status migration described below.

What is changing

Field	Enforced today	After the change
`firstName`	Required	Required — no change
`lastName`	Required	Required — no change
`email` / `phoneNumber`	`phoneNumber` always required; `email` required unless `sync: true`	At least one of the two required
`birthday`	Optional; nonempty supplied values are validated	Required
`ssnLastFour`	Optional	Required
`timezone` / `zipCode`	`timezone` always required; `zipCode` required unless `sync: true`	At least one of the two required
`state`	Required unless `sync: true`	Required in all cases
`loanId`	Never selects loans to import; read as the LMS application reference on origination-boarding records, ignored otherwise	Removed — send the ID in `loanIds`

id, taskType, streetAddress1, and city are unchanged. streetAddress2, doNotCall, externalMetadata, and loanIds remain optional.

Why each change

At least one of email or phoneNumber. Every customer needs at least one channel we can reach them on — a record with neither cannot be worked. Today phoneNumber is unconditionally required, which turns away email-only accounts. Relaxing that while requiring one of the pair is both stricter in effect and more flexible in practice. At least one of timezone or zipCode. We may only place calls during hours permitted by the borrower’s local time, so TCPA compliance depends on knowing where they are. Under the proposed contract, supplying either will be sufficient: when timezone is omitted we will derive it from zipCode. If the ZIP cannot be resolved, the proposed behavior is to reject the request with 422. This stricter ZIP behavior is not live. Today, with sync: true, customer creation defaults to America/New_York when a supplied or fetched ZIP cannot be resolved; if both timezone and ZIP are absent, it returns 422 for missing timezone. Replacement schedule sync defaults to America/New_York even when the ZIP is absent. state always required. State determines which lending and collections rules apply to the account, and several states are restricted per-portfolio. We need it regardless of how the rest of the record was populated. birthday and ssnLastFour required. Both are used to verify a borrower’s identity before discussing account details on a call. Without them, an agent cannot complete verification and the conversation cannot proceed. loanId removed. On POST /customers this field is accepted and then ignored — it has never had any effect. loanIds is the field that actually controls which loans are imported, so a single loan ID belongs there as a one-element array.

Migrating your payload

A request that is valid today:

{
  "id": "12345",
  "taskType": "Collections",
  "firstName": "John",
  "lastName": "Doe",
  "email": "[email protected]",
  "phoneNumber": "+14155555555",
  "timezone": "America/Los_Angeles",
  "streetAddress1": "123 Main St",
  "city": "San Francisco",
  "state": "CA",
  "zipCode": "94102",
  "isTest": false,
  "loanId": "67890"
}

The same request under the new contract — birthday and ssnLastFour added, loanId moved into loanIds:

{
  "id": "12345",
  "taskType": "Collections",
  "firstName": "John",
  "lastName": "Doe",
  "email": "[email protected]",
  "phoneNumber": "+14155555555",
  "birthday": "1985-06-15",
  "ssnLastFour": "1234",
  "timezone": "America/Los_Angeles",
  "streetAddress1": "123 Main St",
  "city": "San Francisco",
  "state": "CA",
  "zipCode": "94102",
  "isTest": false,
  "loanIds": [67890]
}

Note that loanIds is an array of integers, not strings. After the proposed field changes take effect, email/phoneNumber and timezone/zipCode will be at-least-one pairs. The following minimal payload is not valid today:

{
  "id": "12345",
  "taskType": "Collections",
  "firstName": "John",
  "lastName": "Doe",
  "email": "[email protected]",
  "birthday": "1985-06-15",
  "ssnLastFour": "1234",
  "streetAddress1": "123 Main St",
  "city": "San Francisco",
  "state": "CA",
  "zipCode": "94102"
}

What you can do now vs. what to wait for

Read this section carefully if you plan to migrate early — some of the new fields are not yet wired up. Safe to do now:

Start sending birthday, ssnLastFour, and state on every request. All three are already accepted and stored today. Birthday and SSN remain optional; supplied nonempty birthdays are validated, and state is already required unless sync: true.
Move a single loanId value into loanIds. loanIds is already honored; loanId is already ignored on this endpoint, so there is no behavior to lose.

Only after the change takes effect:

Dropping phoneNumber (relying on email alone) or dropping timezone (relying on zipCode alone) on requests without sync: true. These requests return 422 today. LMS auto-fetch retains its existing enrichment and timezone fallback behavior.

Error behavior

Missing required fields return 422 Unprocessable Content with the offending fields named. For example, today a request missing both first name and phone after any LMS enrichment returns:

{
  "detail": "Missing required fields: firstName, phoneNumber"
}

After the proposed field changes take effect, errors for the at-least-one pairs will name the pair. Rejecting an unresolvable ZIP with 422 is also proposed; the current sync: true fallback described above still applies.

Customer validation errors moved from `400` to `422`

Customer creation, updates, replacement schedule sync, servicing cancellation and batch-job UUID validation now return 422 for invalid input. Enrollment retains its structured detail object and other validation errors use strings or framework field-error arrays. Invalid birthday, phone or timezone inputs are rejected before writes, including cases previously reported as 500. The customer upsert webhook validates phone, birthday and supplied timezone before persistence. Empty or whitespace-only webhook birthdays now return 422. Endpoint-generated string validation messages omit raw phone, birthday and timezone values. Framework schema-error arrays can include submitted values in input; this change does not redact those arrays. These changes affect clients matching status codes or text. LMS auto-fetch failures return 502; malformed optional provider birthdays are skipped without clearing an existing birthday. Unexpected internal failures remain 500. Accepted customer batches retain HTTP 202. Customer-create row validation failures use 422: message prefixes, known provider failures use 502:, and unexpected internal failures use 500:. Enrollment rows retain their structured error codes. Do not confuse those prefixes with the batch HTTP status. During rollout, accept both 400 and 422 for migrated validation and update prefix matching. Company/workflow configuration and replacement-mode Do Not Call refusals retain 400. Enrollment Do Not Call conflicts retain 409; authentication and missing-resource statuses remain unchanged. Do not retry invalid input unchanged; follow each operation’s idempotency behavior before retrying writes after server failures.

Proposed payment-plan retrieval

Proposal only — not implemented or available for integration. No release date has been announced. All fields, examples, calculations, status meanings, error responses, and polling behavior below describe the proposed contract and remain subject to implementation and review. The curl examples are illustrative and cannot be used to retrieve a payment plan today.

Overview

Two proposed read-only endpoints, both authenticated with X-API-Key and scoped to the company associated with that key:

Endpoint	Returns
`GET /loans/{id}/payment-plan`	The loan’s active payment plan: its terms, the cadence rule it was created under, and reconciliation totals. Add `includeScheduledPayments=true` and `includePayments=true` to receive the plan’s scheduled payments and the payments made against them in the same response.
`GET /loans/{id}/payment-plans/{planId}/scheduled-payments`	The scheduled payments of one specific plan, identified by `planId`.

The intended use is to board a payment plan into your servicing system and reconcile payments collected against it. The sections below describe the proposed integration behavior, not an available endpoint.

To board or reconcile a plan, make one call: GET /loans/{id}/payment-plan?includeScheduledPayments=true&includePayments=true. paidToDate and remainingAmount are computed from the scheduled payments and payments in the same response, so they always agree with them. Use the scheduled-payments endpoint when you already hold a planId, for example one stored from an earlier poll.

Proposed request: current plan

GET /loans/{id}/payment-plan

Parameter	Location	Proposed behavior
`id`	Path	Required external reference ID of the loan.
`includeScheduledPayments`	Query	Optional boolean, default `false`. Adds `scheduledPayments[]` to the plan.
`includePayments`	Query	Optional boolean, default `false`. Adds `payments[]` to the plan.
`includeRetired`	Query	Optional boolean, default `true`. Applies when `includeScheduledPayments=true`. Include `MISSED`, `SKIPPED`, `POSTPONED`, and `CANCELLED` installments. Filtering and its interaction with reconciliation totals must be finalized before release.
`If-None-Match`	Header	Optional ETag from an earlier response; see proposed polling behavior below.

This endpoint always returns the loan’s current plan. A plan that was replaced by a newer one is not returned here; fetch its scheduled payments by planId instead.

Proposed request: scheduled payments of a plan

GET /loans/{id}/payment-plans/{planId}/scheduled-payments

Parameter	Location	Proposed behavior
`id`	Path	Required external reference ID of the loan.
`planId`	Path	Required. The `planId` of any plan on this loan, including one that has since been replaced by a newer plan.
`includeRetired`	Query	Optional boolean, default `true`. Same meaning as on the current-plan endpoint.
`If-None-Match`	Header	Optional ETag from an earlier response.

The response is an ScheduledPaymentList. A 404 means the loan does not exist for your company, or the planId does not belong to that loan.

{
  "loanId": "L-88213",
  "planId": "L-88213-plan-2",
  "planVersion": "3f9a1c07",
  "scheduledPayments": [
    {
      "scheduledPaymentId": "e53c1b92-3d66-4a4c-8f20-99e1d3c4b725",
      "dueDate": "2026-07-10T07:00:00-05:00",
      "scheduledAmount": 206.67,
      "amountPaid": 0.0,
      "creditsApplied": 0.0,
      "amountRemaining": 206.67,
      "status": "PENDING"
    }
  ]
}

The example shows one scheduled payment for brevity; the response returns every scheduled payment of the plan, ordered by due date.

Reading across two calls

planVersion changes whenever anything in the plan changes: a payment posts, credit is applied, or the schedule is rebuilt. Both endpoints return it. If you fetch the plan and its scheduled payments in separate calls, first check that both responses have the same planId. A different planId means the plan you asked about has been replaced, and the current-plan endpoint is describing its successor. With the same planId, the identities below hold only when both responses also have the same planVersion. If the planVersion values differ, something changed in between; fetch again, or use the single-call form above.

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:

status	meaning
`PENDING`	Live, not yet due.
`PARTIALLY_PAID`	Live, partly covered by payments or credit.
`OVERDUE`	Live, past its due date and still owed on this scheduled payment.

Every other status means the scheduled payment is not a live obligation and must not be boarded:

status	meaning	what it tells you about the borrower
`PAID`	Fully covered.	—
`MISSED`	The installment was completely unpaid five full days after its `dueDate`, or its charge failed, and the amount was moved onto a different scheduled payment.	Adverse — the promised installment was not paid.
`SKIPPED`	The borrower asked to skip this scheduled payment and it was forgiven.	Borrower-initiated relief, not a failed payment.
`POSTPONED`	Finosu moved the scheduled payment (a schedule rebuild or an operator action).	Nothing — this is an operational change on our side.
`CANCELLED`	The scheduled payment was cancelled and is void.	—

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

The proposed contract requires these identities for a response from the current-plan endpoint with includeScheduledPayments=true, includePayments=true, and includeRetired=true. The first identity also holds across two calls when they report the same planId and planVersion: paidToDate from the current-plan endpoint, and the rows from the scheduled-payments endpoint with includeRetired=true.

paidToDate == sum of scheduledPayments[].amountPaid
paidToDate == sum of payments[].amount where status == "SUCCESSFUL" and scheduledPaymentId is present

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[].dueDate is authoritative for when a scheduled payment is actually due. It carries a UTC offset and reflects any rescheduling.
cadence describes 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 reschedule cadence can disagree with the actual due dates. Use it to understand the intended pattern; use dueDate for real dates.
transactedAt and finalizedAt are Finosu-side timestamps, not bank confirmations. transactedAt is when the payment was submitted or took effect; finalizedAt is when Finosu considers it settled. For ACH, neither is a guarantee of when funds moved at your bank. Apply your own settlement rules.

Identifiers

planId identifies the plan and is stable for the life of the plan. It stays valid after the plan is replaced, so you can still fetch that plan’s scheduled payments.
planVersion identifies the plan’s state, not the plan itself. It changes whenever the plan does, so do not store it as an identifier.
scheduledPaymentId and paymentId are stable Finosu identifiers. Store them if you want to correlate across polls.
reference on 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

A 200 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.

Do not treat paymentPlan: null as evidence that a plan was broken. A completed plan and a cancelled plan both read as null here. If your system holds an active plan for this loan, stop expecting drafts and flag it for review rather than assuming default.

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

Both endpoints return an ETag. 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.

curl -sD- 'https://api.finosu.com/loans/L-88213/payment-plan?includeScheduledPayments=true&includePayments=true' \
  -H "X-API-Key: $FINOSU_API_KEY"

curl -s -o /dev/null -w '%{http_code}\n' \
  'https://api.finosu.com/loans/L-88213/payment-plan?includeScheduledPayments=true&includePayments=true' \
  -H "X-API-Key: $FINOSU_API_KEY" \
  -H 'If-None-Match: W/"<etag from the first call>"'

Send the same query parameters on every poll. An ETag describes one response, so an ETag taken from a call without includeScheduledPayments does not match a call with it.

Example

The plan originally had four installments of $206.67, due May 15, May 29, June 12, and June 26, for a total of $826.68. When the May 29 installment was missed, a new replacement installment for the same $206.67 was added for July 10. It was not added to the amount of an existing installment. The response retains the missed row for history, so it shows five rows but only four obligations across the life of the plan. The response below is from GET /loans/L-88213/payment-plan?includeScheduledPayments=true&includePayments=true. Without the two parameters, the same call returns everything except the scheduledPayments and payments arrays. 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 historical MISSED row from May 29. Its obligation is represented by the new July 10 PENDING row, not by an increase to the June rows.discountedTotal is the authorized total, and remainingAmount the outstanding balance.

{
  "loanId": "L-88213",
  "customerId": "C-4410",
  "paymentPlan": {
    "planId": "L-88213-plan-2",
    "planVersion": "3f9a1c07",
    "type": "CUSTOM",
    "standing": "PAST_DUE",
    "startDate": "2026-05-15",
    "autopayEnabled": true,
    "createdAt": "2026-05-08T18:22:04.001Z",
    "cadence": {
      "frequency": "BIWEEKLY",
      "dayOfWeek": 5,
      "dayOfMonth": null,
      "semimonthlyDays": null
    },
    "totals": {
      "originalTotal": 1200.0,
      "discountedTotal": 826.68,
      "paidToDate": 300.0,
      "creditsApplied": 93.33,
      "remainingAmount": 526.68,
      "pendingAmount": 0.0,
      "offPlatformPaymentsTotal": 100.0
    },
    "scheduledPayments": [
      {
        "scheduledPaymentId": "1a0b7c22-9d3e-4f10-b5a6-2c8e9f41d700",
        "dueDate": "2026-05-15T07:00:00-05:00",
        "scheduledAmount": 206.67,
        "amountPaid": 300.0,
        "creditsApplied": 0.0,
        "amountRemaining": 0.0,
        "status": "PAID"
      },
      {
        "scheduledPaymentId": "2b1c8d33-ae4f-4021-c6b7-3d9f0a52e811",
        "dueDate": "2026-05-29T07:00:00-05:00",
        "scheduledAmount": 206.67,
        "amountPaid": 0.0,
        "creditsApplied": 0.0,
        "amountRemaining": 206.67,
        "status": "MISSED"
      },
      {
        "scheduledPaymentId": "3c2d9e44-bf50-4132-d7c8-4e0a1b63f922",
        "dueDate": "2026-06-12T07:00:00-05:00",
        "scheduledAmount": 206.67,
        "amountPaid": 0.0,
        "creditsApplied": 0.0,
        "amountRemaining": 206.67,
        "status": "OVERDUE"
      },
      {
        "scheduledPaymentId": "d42b0a81-2c55-4f3b-9e1f-88d0c2b3a614",
        "dueDate": "2026-06-26T07:00:00-05:00",
        "scheduledAmount": 206.67,
        "amountPaid": 0.0,
        "creditsApplied": 93.33,
        "amountRemaining": 113.34,
        "status": "PARTIALLY_PAID"
      },
      {
        "scheduledPaymentId": "e53c1b92-3d66-4a4c-8f20-99e1d3c4b725",
        "dueDate": "2026-07-10T07:00:00-05:00",
        "scheduledAmount": 206.67,
        "amountPaid": 0.0,
        "creditsApplied": 0.0,
        "amountRemaining": 206.67,
        "status": "PENDING"
      }
    ],
    "payments": [
      {
        "paymentId": "5c7e1a90-3b62-4c88-9a11-6d4f2e8b0c31",
        "scheduledPaymentId": "1a0b7c22-9d3e-4f10-b5a6-2c8e9f41d700",
        "amount": 100.0,
        "currency": "USD",
        "status": "SUCCESSFUL",
        "paymentType": "PARTIAL",
        "source": "EXTERNAL",
        "transactedAt": "2026-05-15T09:07:44-05:00",
        "finalizedAt": "2026-05-18T02:11:00Z",
        "reversedAt": null,
        "reference": "LMS-PMT-99101"
      },
      {
        "paymentId": "a71f3d05-8c92-4b1e-9d43-2e6b8f0a5c17",
        "scheduledPaymentId": "1a0b7c22-9d3e-4f10-b5a6-2c8e9f41d700",
        "amount": 200.0,
        "currency": "USD",
        "status": "SUCCESSFUL",
        "paymentType": "OVERPAYMENT",
        "source": "SYSTEM",
        "transactedAt": "2026-05-20T14:22:10-05:00",
        "finalizedAt": "2026-05-21T02:07:00Z",
        "reversedAt": null,
        "reference": null
      },
      {
        "paymentId": "6d8f2b01-4c73-4d99-8b22-7e5a3f9c1d42",
        "scheduledPaymentId": "2b1c8d33-ae4f-4021-c6b7-3d9f0a52e811",
        "amount": 206.67,
        "currency": "USD",
        "status": "FAILED",
        "paymentType": "AUTOPAY",
        "source": "SYSTEM",
        "transactedAt": "2026-05-29T09:03:12-05:00",
        "finalizedAt": null,
        "reversedAt": null,
        "reference": null
      }
    ]
  }
}

Reading the example: The first scheduled payment shows 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[]. The fifth row, due July 10 with status PENDING, is its replacement and carries the same $206.67 obligation. The June 12 and June 26 amounts are unchanged. Do not board the historical May 29 row as well, or you would collect the same obligation 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

Status Code	Description
401	Missing or invalid `X-API-Key`
404	No loan with that reference exists for your company, or (scheduled-payments endpoint) the `planId` does not belong to that loan
500	Unexpected server error

Proposed response field reference

These draft fields supplement the worked example above; they are not a published runtime schema.

PaymentPlanEnvelope

Field	Type	Required in draft	Description
`loanId`	string	Yes	The loan’s external reference, echoing the request path.
`customerId`	string	Yes	The customer’s reference id.
`paymentPlan`	PaymentPlan or null	No	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.

PaymentPlan

Field	Type	Required in draft	Description
`planId`	string	Yes	Identifies the plan. Stable for the life of the plan.
`planVersion`	string	Yes	Identifies the plan’s current state. Changes whenever a payment, credit, or schedule change affects the plan. Two responses with the same `planId` and equal `planVersion` describe the same state.
`type`	string	Yes	CUSTOM, FIXED, ONE_TIME or SETTLEMENT. Detect a discount by comparing originalTotal with discountedTotal rather than relying on this value.
`standing`	string	Yes	CURRENT if the borrower is on track, PAST_DUE if any live installment is overdue, COMPLETED if all are paid, UNKNOWN if the plan has no live installments.
`startDate`	string or null	No	The plan’s authored start date. Combined with `cadence.frequency` it reproduces the intended series.
`autopayEnabled`	boolean	Yes	Whether Finosu will automatically draft the scheduled payments. Check this before collecting independently, to avoid double-drafting.
`createdAt`	string	Yes	When the plan was created, i.e. when the borrower authorized it.
`cadence`	Cadence	Yes	See the proposed example.
`totals`	PlanTotals	Yes	See the proposed example.
`scheduledPayments`	array of ScheduledPayment	No	Present only when `includeScheduledPayments=true`. The plan’s scheduled payments, ordered by due date.
`payments`	array of Payment	No	Present only when `includePayments=true`. Payments against this plan, ordered by transaction date. Payments made against the loan but not associated with this plan are not included.

ScheduledPaymentList

Returned by GET /loans/{id}/payment-plans/{planId}/scheduled-payments.

Field	Type	Required in draft	Description
`loanId`	string	Yes	The loan’s external reference, echoing the request path.
`planId`	string	Yes	The plan these scheduled payments belong to, echoing the request path.
`planVersion`	string	Yes	The plan’s state when these scheduled payments were read. Compare with `paymentPlan.planVersion` from the current-plan endpoint only when the two `planId` values match.
`scheduledPayments`	array of ScheduledPayment	Yes	The plan’s installments, ordered by due date.

Cadence

Field	Type	Required in draft	Description
`frequency`	string or null	No	WEEKLY, BIWEEKLY, SEMIMONTHLY or MONTHLY.
`dayOfWeek`	integer or null	No	ISO day of week (Monday=1). Populated for WEEKLY and BIWEEKLY.
`dayOfMonth`	integer or null	No	Day of month, 1-31. Populated for MONTHLY.
`semimonthlyDays`	array or null	No	The two days of month, ascending. Populated for SEMIMONTHLY. Always either both days or `null` — a partially recorded rule is reported as `null` rather than a one-element list.

PlanTotals

Field	Type	Required in draft	Description
`originalTotal`	number or string or null	No	What was owed when the plan was created. `null` means no baseline was recorded — it does not mean there was no discount.
`discountedTotal`	number or string	Yes	What the borrower agreed to pay under this plan.
`paidToDate`	number or string	Yes	Cash attributed to scheduled payments, any source. Equals the sum of `scheduledPayments[].amountPaid`, and the sum of successful `payments[]` that have an `scheduledPaymentId`.
`creditsApplied`	number or string	Yes	Total credit applied across the plan’s scheduled payments. Not cash.
`remainingAmount`	number or string	Yes	What is still owed: the sum of `amountRemaining` across scheduled payments whose status is PENDING, PARTIALLY_PAID or OVERDUE. Do not compute this as discountedTotal - paidToDate - creditsApplied; that double-counts credit that originated from an overpayment.
`pendingAmount`	number or string	Yes	Payments in flight (status PENDING) against this plan.
`offPlatformPaymentsTotal`	number or string	Yes	The portion of `paidToDate` that was collected outside Finosu (payments with source EXTERNAL). A subset of paidToDate, never an addition to it.

ScheduledPayment

Field	Type	Required in draft	Description
`scheduledPaymentId`	string	Yes	Finosu identifier for this scheduled payment. Join target for `payments[].scheduledPaymentId`.
`dueDate`	string	Yes	When this installment is due, with UTC offset. Authoritative for actual timing — unlike `cadence`, it reflects any rescheduling.
`scheduledAmount`	number or string	Yes	The authorized amount for this installment.
`amountPaid`	number or string	Yes	Cash applied to this installment. Excludes returned/refunded.
`creditsApplied`	number or string	Yes	Credit applied to this installment from the loan’s credit balance. Kept separate from cash because a credit satisfies an obligation with no money movement.
`amountRemaining`	number or string	Yes	max(0, scheduledAmount - amountPaid - creditsApplied). Only meaningful when `status` is PENDING, PARTIALLY_PAID or OVERDUE. A MISSED or POSTPONED row reports a non-zero value whose obligation has moved elsewhere, so summing across all rows overstates the balance.
`status`	string	Yes	PENDING, PARTIALLY_PAID, OVERDUE, PAID, CANCELLED, MISSED, SKIPPED or POSTPONED. Board only rows whose status is PENDING, PARTIALLY_PAID or OVERDUE.

Payment

Field	Type	Required in draft	Description
`paymentId`	string	Yes	Finosu identifier for this payment.
`scheduledPaymentId`	string	Yes	The scheduled payment this was applied to.
`amount`	number or string	Yes	Payment amount.
`currency`	string	Yes	ISO currency code.
`status`	string	Yes	One of PENDING, SUCCESSFUL, FAILED, REFUNDED, RETURNED. RETURNED/REFUNDED mean the money came back and does not count toward amounts paid.
`paymentType`	string	Yes	One of REGULAR, AUTOPAY, PARTIAL, OVERPAYMENT, PAYOFF, PAY_IN_FULL.
`source`	string	Yes	SYSTEM if collected through Finosu, EXTERNAL if collected outside it. EXTERNAL is what identifies an off-platform payment.
`transactedAt`	string	Yes	Effective/submission date. A Finosu-side timestamp, not a bank confirmation.
`finalizedAt`	string or null	No	When Finosu considers the payment settled. A Finosu-side timestamp, not a bank confirmation.
`reversedAt`	string or null	No	Set when the payment was returned or refunded.
`reference`	string or null	No	The external reference supplied with the payment, for payments the lender recorded themselves. The join key back into their ledger.

The final contract and availability will be published in the API reference when released. No integration changes are required now.

Questions

If any of these fields are not available in your system, or you need more time to adjust, contact your Finosu account manager so we can plan around it.

API Documentation

Core Resources

Origination

Collections

Upcoming API Changes

Summary

What is changing

Why each change

Migrating your payload

What you can do now vs. what to wait for

Error behavior

Customer validation errors moved from `400` to `422`

Proposed payment-plan retrieval

Overview

Proposed request: current plan

Proposed request: scheduled payments of a plan

Reading across two calls

Which scheduled payments to board

Reading the money

`remainingAmount` is a sum over scheduled payments

`amountRemaining` is only meaningful on live scheduled payments

`offPlatformPaymentsTotal` is a portion of `paidToDate`

Totals you can verify against the scheduled payments

Credits

Dates and timing

Identifiers

When there is no plan

Polling efficiently

Example

Error Responses

Proposed response field reference

PaymentPlanEnvelope

PaymentPlan

ScheduledPaymentList

Cadence

PlanTotals

ScheduledPayment

Payment

Questions

Summary

What is changing

Why each change

Migrating your payload

What you can do now vs. what to wait for

Error behavior

Customer validation errors moved from 400 to 422

Proposed payment-plan retrieval

Overview

Proposed request: current plan

Proposed request: scheduled payments of a plan

Reading across two calls

Which scheduled payments to board

Reading the money

remainingAmount is a sum over scheduled payments

amountRemaining is only meaningful on live scheduled payments

offPlatformPaymentsTotal is a portion of paidToDate

Totals you can verify against the scheduled payments

Credits

Dates and timing

Identifiers

When there is no plan

Polling efficiently

Example

Error Responses

Proposed response field reference

PaymentPlanEnvelope

PaymentPlan

ScheduledPaymentList

Cadence

PlanTotals

ScheduledPayment

Payment

Questions

Customer validation errors moved from `400` to `422`

`remainingAmount` is a sum over scheduled payments

`amountRemaining` is only meaningful on live scheduled payments

`offPlatformPaymentsTotal` is a portion of `paidToDate`