Statements

Loan statements give borrowers a month-by-month snapshot of balances, payments, fees, and interest.
Embarc generates statements automatically at month-end or on demand, stores the rendered PDF, and exposes the history through loan-level APIs.

Statement Lifecycle

flowchart TD
    A[Generation Requested status: IN_PROGRESS] -->|PDF stored successfully| B[Available status: COMPLETED]
    A -->|Rendering/storage issue| C[Failed status: FAILED]
    C -->|Retry request| A

Lifecycle in Words

Request a statement for a loan and billing period (POST /v1/loans/{loanId}/loanstatements). If dates are omitted, Embarc uses the last fully closed calendar month.
Validation ensures the loan is active or overpaid (or closed within the previous cycle), the period is unique, and the caller has statement permissions.
Generation renders the PDF for that period, then uploads it to Embarc’s statement storage.
Completion marks the record COMPLETED with file size, checksum, and a secure download link. If anything fails, the status becomes FAILED and you can try again.

Scheduled batch jobs run this flow automatically after month-end so new statements appear without manual intervention.

Stored Metadata

Field	Description
Period start/end	Inclusive month of activity (unique per loan).
Status	IN_PROGRESS, COMPLETED, or FAILED.
Storage details	File size, checksum, storage location, and a presigned download URL (if enabled).
Generated timestamp	When the PDF became available.
Error message	Populated only when the last attempt failed.
Audit info	Who triggered the run and when the record was created/updated (UTC).

If a statement is marked FAILED, the next POST for that period resets it to IN_PROGRESS and re-runs the pipeline.

Core APIs

Description	Method	Endpoint
List statements for a loan	GET	`/loans/{loanId}/loanstatements?from=yyyy-MM-dd&to=yyyy-MM-dd`
Fetch a specific statement	GET	`/loans/{loanId}/loanstatements/{statementId}`
Generate or retry	POST	`/loans/{loanId}/loanstatements`

Responses include the statement ID, period, status, storage metadata, and (when available) a time-limited download URL.

Create Example

POST /v1/loans/410/loanstatements
{
  "periodStart": "2025-08-01",
  "periodEnd": "2025-08-31"
}

Successful response (abridged):

{
  "statementId": 812,
  "loanId": 410,
  "periodStart": "2025-08-01",
  "periodEnd": "2025-08-31",
  "status": "COMPLETED",
  "fileSize": 184327,
  "checksum": "6c9a...e3d1",
  "generatedOn": "2025-09-02T04:15:09Z",
  "downloadUrl": "https://..."
}

If the period already exists in COMPLETED, Embarc returns the existing record without regenerating the same

Access

Download URLs are short-lived (default 5 minutes). Request a fresh URL through the GET endpoint if the previous link expires.
Permissions:
- READ_LOAN_STATEMENTS to list or fetch statements.
- GENERATE_LOAN_STATEMENTS to create or retry statements (granted automatically to the scheduled job).
Office hierarchy is enforced: users must have access to the loan’s branch to view or generate statements.

Operational Tips

Retry a failure: Call POST for the same period again; the service clears the error state and regenerates the PDF.
Customer delivery: Surface the download URL in your portal or automated email. Regenerate the link if the customer opens the page after the TTL expires.
Audit trail: Statement records capture who generated each period, when it was produced, and a checksum so you can prove the PDF hasn’t been altered.