> ## Documentation Index > Fetch the complete documentation index at: https://docs.clarivo.co/llms.txt > Use this file to discover all available pages before exploring further. # Paginated journal history for a loan ## OpenAPI ````yaml /api-reference/openapi.yaml get /loans/{loan_id}/journal-entries openapi: 3.1.0 info: title: High-Performance Transaction System (HPTS) API version: 1.0.0 summary: Append-only ledger posting and balance retrieval API for lending. description: > HPTS is the sole programmatic interface to the lending ledger. All money-movement events — payments, disbursements, daily accruals, reversals — are posted through this API. All balance and history reads are served through this API. ## Invariants enforced by this API 1. **Append-only.** No mutation endpoints exist. Corrections are reversals. 2. **Double-entry.** Every posting produces balanced journal lines. 3. **Idempotent writes.** Every `POST` requires an `Idempotency-Key` header. 4. **Tenant-isolated.** Every request is scoped to one tenant via JWT claims. 5. **Mutual authentication for B2B.** Partner endpoints require mTLS + OAuth. ## Idempotency contract - Clients MUST send `Idempotency-Key` on every `POST`. - Keys are scoped per tenant and retained for 24 hours minimum. - Same key + same payload → returns the original result with HTTP 200. - Same key + different payload → HTTP 422 with `idempotency_mismatch`. - Concurrent requests with the same in-flight key → HTTP 409 with `idempotency_in_progress`. ## Error format All errors follow RFC 7807 Problem Details with an optional `errors[]` array for field-level validation issues. contact: name: HPTS Platform Team email: platform-hpts@example.com license: name: Proprietary x-audience: internal, b2b-partners x-api-id: hpts-core-v1 x-tagGroups: - name: Core Write (Go Lambda) tags: - payments - disbursements - accruals - reversals - name: Read / BFF (TypeScript Lambda) tags: - balances - journal - reconciliation - name: Operations tags: - health x-api-slo: p99_latency_ms: core_write_endpoints: 100 bff_read_endpoints: 300 availability_pct: 99.95 servers: - url: https://ledger.clarivo.co/v1 description: Production - url: https://ledger.staging.clarivo.co/v1 description: Staging - url: https://ledger.dev.clarivo.co/v1 description: Development - url: https://partner.hpts.example.com/v1 description: B2B partner endpoint (mTLS required) - url: http://localhost:3000/v1 description: Local (cmd/server) - url: http://localhost:4010/v1 description: Local Prism mock security: - bearerAuth: [] tags: - name: payments description: Payment lifecycle — high-throughput Go Lambda. x-stack: go - name: disbursements description: Loan disbursement postings — Go Lambda. x-stack: go - name: accruals description: Batch interest accrual — Go Lambda. x-stack: go - name: reversals description: Journal entry reversal postings — Go Lambda. x-stack: go - name: balances description: Balance queries (BFF) — Node/TypeScript Lambda. x-stack: typescript - name: journal description: Journal entry retrieval (BFF) — Node/TypeScript Lambda. x-stack: typescript - name: reconciliation description: Reconciliation status (BFF) — Node/TypeScript Lambda. x-stack: typescript - name: health description: Operational health endpoints. paths: /loans/{loan_id}/journal-entries: get: tags: - journal summary: Paginated journal history for a loan operationId: listLoanJournalEntries parameters: - $ref: '#/components/parameters/LoanIdPath' - name: from_date in: query schema: type: string format: date - name: to_date in: query schema: type: string format: date - name: event_type in: query schema: $ref: '#/components/schemas/EventKind' - $ref: '#/components/parameters/PageSize' - $ref: '#/components/parameters/PageToken' responses: '200': description: Page of journal entries content: application/json: schema: $ref: '#/components/schemas/JournalEntryPage' security: - bearerAuth: - hpts:ledger:read components: parameters: LoanIdPath: name: loan_id in: path required: true schema: $ref: '#/components/schemas/Uuid' PageSize: name: page_size in: query required: false schema: type: integer minimum: 1 maximum: 500 default: 50 PageToken: name: page_token in: query required: false schema: type: string maxLength: 512 schemas: EventKind: type: string enum: - disbursement - disbursement_settled - accrual - payment_received - payment_allocated - payment_returned - fee_assessed - fee_waived - chargeoff - recovery - refinance - restructure - reversal - manual_adjustment JournalEntryPage: type: object required: - items additionalProperties: false properties: items: type: array items: $ref: '#/components/schemas/JournalEntry' next_page_token: type: string description: Opaque cursor. Absent when no more pages. Uuid: type: string format: uuid pattern: >- ^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$ examples: - 11111111-1111-1111-1111-111111111111 JournalEntry: type: object required: - journal_entry_id - event_type - effective_at - posted_at - lines additionalProperties: false properties: journal_entry_id: $ref: '#/components/schemas/Uuid' correlation_id: $ref: '#/components/schemas/Uuid' reverses_entry_id: $ref: '#/components/schemas/Uuid' event_type: $ref: '#/components/schemas/EventKind' effective_at: type: string format: date posted_at: $ref: '#/components/schemas/Timestamp' description: type: string actor: type: string lines: type: array minItems: 2 items: $ref: '#/components/schemas/JournalLine' Timestamp: type: string format: date-time description: RFC 3339 timestamp, UTC. JournalLine: type: object required: - sequence - account_code - direction - amount_minor - currency - layer additionalProperties: false properties: sequence: type: integer minimum: 1 maximum: 32767 account_code: $ref: '#/components/schemas/AccountCode' direction: $ref: '#/components/schemas/EntryDirection' amount_minor: $ref: '#/components/schemas/AmountMinor' currency: $ref: '#/components/schemas/CurrencyCode' layer: $ref: '#/components/schemas/EntryLayer' loan_id: $ref: '#/components/schemas/Uuid' borrower_id: $ref: '#/components/schemas/Uuid' external_ref: type: string AccountCode: type: string pattern: ^[0-9]{4}$ description: Four-digit GL account code. examples: - '1000' - '1100' - '1200' EntryDirection: type: string enum: - DR - CR AmountMinor: type: string description: | Non-negative integer amount in the currency's minor unit, serialized as a string to preserve precision (JS numbers cannot safely represent values above 2^53). BIGINT on the wire, BIGINT in the database. pattern: ^(0|[1-9][0-9]{0,18})$ minLength: 1 maxLength: 19 examples: - '88849' - '10000000' CurrencyCode: type: string description: ISO 4217 three-letter currency code. pattern: ^[A-Z]{3}$ minLength: 3 maxLength: 3 examples: - USD - MXN - EUR EntryLayer: type: string enum: - SETTLED - PENDING - ENCUMBRANCE default: SETTLED securitySchemes: bearerAuth: type: oauth2 description: | OAuth2 JWT bearer tokens. Tokens are validated at API Gateway via a Lambda Authorizer that verifies signature against the issuer's JWKS, checks `iss`, `aud`, `exp`, `nbf`, and the `tenant_id` custom claim. Granular scopes are required per operation. flows: clientCredentials: tokenUrl: https://auth.example.com/oauth2/token scopes: hpts:payments:write: Post payment events hpts:disbursements:write: Post disbursement events hpts:accruals:write: Post batch accruals hpts:reversals:write: Post reversals (privileged; audited) hpts:ledger:read: Read journal entries hpts:balances:read: Read balances hpts:loans:read: Read loan metadata hpts:reconciliation:read: Read reconciliation reports hpts:admin:*: Administrative operations authorizationCode: authorizationUrl: https://auth.example.com/oauth2/authorize tokenUrl: https://auth.example.com/oauth2/token refreshUrl: https://auth.example.com/oauth2/token scopes: hpts:balances:read: Read balances hpts:ledger:read: Read journal entries ````