> ## 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.

# Record a loan disbursement

> Debits Principal Receivable, credits the disbursement clearing account.
Requires `hpts:disbursements:write` scope.




## OpenAPI

````yaml /api-reference/openapi.yaml post /disbursements
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:
  /disbursements:
    post:
      tags:
        - disbursements
      summary: Record a loan disbursement
      description: |
        Debits Principal Receivable, credits the disbursement clearing account.
        Requires `hpts:disbursements:write` scope.
      operationId: postDisbursement
      parameters:
        - $ref: '#/components/parameters/IdempotencyKey'
        - $ref: '#/components/parameters/TraceId'
        - $ref: '#/components/parameters/Traceparent'
        - $ref: '#/components/parameters/Tracestate'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/DisbursementPostRequest'
      responses:
        '200':
          description: Idempotency replay.
          headers:
            Idempotency-Key:
              $ref: '#/components/headers/IdempotencyKeyEcho'
            Idempotency-Replay:
              schema:
                type: string
                enum:
                  - true
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DisbursementPostResponse'
        '201':
          description: Disbursement posted.
          headers:
            Idempotency-Key:
              $ref: '#/components/headers/IdempotencyKeyEcho'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DisbursementPostResponse'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '409':
          $ref: '#/components/responses/IdempotencyInProgress'
        '422':
          $ref: '#/components/responses/UnprocessableEntity'
        '500':
          $ref: '#/components/responses/InternalError'
      security:
        - bearerAuth:
            - hpts:disbursements:write
components:
  parameters:
    IdempotencyKey:
      name: Idempotency-Key
      in: header
      required: true
      description: |
        Required on every POST. Must be a deterministic, client-chosen
        identifier unique per tenant. Recommended format:
        `<event_type>:<resource_id>:<natural_key>`.
        Retained for 24h minimum.
      schema:
        type: string
        minLength: 8
        maxLength: 255
        pattern: ^[A-Za-z0-9][A-Za-z0-9._:\-]{7,254}$
        examples:
          - payment:loan_42:proc_txn_abc123
    TraceId:
      name: X-Trace-Id
      in: header
      required: false
      deprecated: true
      description: |
        **Deprecated — use `traceparent` instead (ADR-0011).**
        Client-supplied correlation ID. Accepted until 2026-10-01 for
        backward compatibility; will be removed after that date.
      schema:
        type: string
        pattern: ^[A-Za-z0-9\-]{8,128}$
    Traceparent:
      name: traceparent
      in: header
      required: false
      description: >
        W3C Trace Context `traceparent` header for distributed tracing (RFC
        7230).

        When present, the service extracts the parent span context and creates

        child spans under it, enabling end-to-end trace correlation across

        API Gateway, the service, and the database.

        Format: `00-<trace-id>-<parent-id>-<flags>`
      schema:
        type: string
        pattern: ^00-[0-9a-f]{32}-[0-9a-f]{16}-[0-9a-f]{2}$
        example: 00-4bf92f3577b34da6a3ce929d0e0e4736-00f067aa0ba902b7-01
    Tracestate:
      name: tracestate
      in: header
      required: false
      description: |
        W3C Trace Context `tracestate` header. Carries vendor-specific trace
        metadata (e.g. AWS X-Ray sampling decision). Passed through unchanged.
      schema:
        type: string
  schemas:
    DisbursementPostRequest:
      type: object
      additionalProperties: false
      required:
        - loan_id
        - borrower_id
        - amount_minor
        - currency
        - effective_at
        - method
      properties:
        loan_id:
          $ref: '#/components/schemas/Uuid'
        borrower_id:
          $ref: '#/components/schemas/Uuid'
        amount_minor:
          $ref: '#/components/schemas/AmountMinor'
        currency:
          $ref: '#/components/schemas/CurrencyCode'
        effective_at:
          type: string
          format: date
        method:
          type: string
          enum:
            - ach
            - wire
            - card_push
            - internal_transfer
        destination_ref:
          type: string
          minLength: 1
          maxLength: 255
        metadata:
          $ref: '#/components/schemas/Metadata'
    DisbursementPostResponse:
      type: object
      additionalProperties: false
      required:
        - disbursement_event_id
        - journal_entry_id
        - posted_at
      properties:
        disbursement_event_id:
          $ref: '#/components/schemas/Uuid'
        journal_entry_id:
          $ref: '#/components/schemas/Uuid'
        posted_at:
          $ref: '#/components/schemas/Timestamp'
    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
    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
    Metadata:
      type: object
      description: |
        Free-form key-value metadata. Never used for financial logic.
        Size limit 2 KB serialized. Keys must match `^[a-zA-Z][a-zA-Z0-9_]*$`.
      maxProperties: 20
      additionalProperties:
        oneOf:
          - type: string
            maxLength: 500
          - type: number
          - type: boolean
    Timestamp:
      type: string
      format: date-time
      description: RFC 3339 timestamp, UTC.
    Problem:
      type: object
      required:
        - type
        - title
        - status
      additionalProperties: true
      properties:
        type:
          type: string
          format: uri
          description: URI identifying the problem type.
          examples:
            - https://errors.hpts.example.com/bad_request
        title:
          type: string
          description: Human-readable summary, same across occurrences.
        status:
          type: integer
          minimum: 400
          maximum: 599
        detail:
          type: string
          description: Human-readable explanation specific to this occurrence.
        instance:
          type: string
          format: uri
          description: URI identifying this specific occurrence.
        trace_id:
          type: string
          description: Distributed-trace ID for cross-system correlation.
    IdempotencyConflictProblem:
      allOf:
        - $ref: '#/components/schemas/Problem'
        - type: object
          required:
            - conflict_kind
          properties:
            conflict_kind:
              type: string
              enum:
                - idempotency_in_progress
                - idempotency_mismatch
              description: |
                - `idempotency_in_progress`: another request with this key is
                  currently executing. Retry after Retry-After seconds.
                - `idempotency_mismatch`: this key was previously used with a
                  different payload. The key may not be reused with a new
                  payload within its retention window.
            original_request_fingerprint:
              type: string
              description: SHA-256 hex of the original request body.
              pattern: ^[0-9a-f]{64}$
            received_request_fingerprint:
              type: string
              description: SHA-256 hex of the current request body.
              pattern: ^[0-9a-f]{64}$
            original_journal_entry_id:
              $ref: '#/components/schemas/Uuid'
    ValidationProblem:
      allOf:
        - $ref: '#/components/schemas/Problem'
        - type: object
          properties:
            errors:
              type: array
              items:
                type: object
                required:
                  - field
                  - code
                  - message
                properties:
                  field:
                    type: string
                    description: JSON pointer to the offending field.
                    examples:
                      - /amount_minor
                      - /loans/3/interest_minor
                  code:
                    type: string
                    pattern: ^[a-z_]+$
                    examples:
                      - required
                      - pattern_mismatch
                      - out_of_range
                  message:
                    type: string
  headers:
    IdempotencyKeyEcho:
      schema:
        type: string
      description: Echo of the Idempotency-Key that produced this response.
  responses:
    BadRequest:
      description: Malformed request
      content:
        application/problem+json:
          schema:
            $ref: '#/components/schemas/Problem'
    Unauthorized:
      description: Missing or invalid credentials
      content:
        application/problem+json:
          schema:
            $ref: '#/components/schemas/Problem'
    Forbidden:
      description: Authenticated but not authorized for this scope/tenant
      content:
        application/problem+json:
          schema:
            $ref: '#/components/schemas/Problem'
    IdempotencyInProgress:
      description: |
        A request with this Idempotency-Key is currently in flight.
        The client must back off and retry; do not change the payload.
      headers:
        Retry-After:
          schema:
            type: integer
            minimum: 1
            maximum: 30
          description: Seconds to wait before retry
      content:
        application/problem+json:
          schema:
            $ref: '#/components/schemas/IdempotencyConflictProblem'
    UnprocessableEntity:
      description: |
        Semantic validation failure. For idempotency, a replay with a
        *different payload* than the original returns this with type
        `idempotency_mismatch`.
      content:
        application/problem+json:
          schema:
            $ref: '#/components/schemas/ValidationProblem'
    InternalError:
      description: Unexpected server error
      content:
        application/problem+json:
          schema:
            $ref: '#/components/schemas/Problem'
  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

````