Skip to main content

​
Overview

HPTS is the sole programmatic interface to the Clarivo 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. Base URL: https://ledger.clarivo.co/v1

​
Core invariants

#InvariantDetail
1Append-onlyNo mutation endpoints exist. Corrections are reversals.
2Double-entryEvery posting produces balanced journal lines.
3Idempotent writesEvery POST requires an Idempotency-Key header.
4Tenant-isolatedEvery request is scoped to one tenant via JWT claims.
5Mutual auth for B2BPartner endpoints require mTLS + OAuth.

​
Authentication

All endpoints are secured with OAuth 2.0 bearer tokens. Tokens are validated at the API Gateway via a Lambda Authorizer that checks signature, iss, aud, exp, nbf, and the tenant_id custom claim. Each operation requires a specific scope. 
Authorization: Bearer <access_token>
B2B partner endpoints additionally require mutual TLS — present a client certificate issued by AWS Private CA alongside your bearer token.

​
Idempotency

Every POST request must include an Idempotency-Key header.
  • Keys are scoped per tenant and retained for 24 hours minimum.
  • Same key + same payload → returns the original result (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.
Recommended key format: <event_type>:<resource_id>:<natural_key> 
payment:loan_42:proc_txn_abc123
accrual:prog_7:2026-04-15

​
Errors

All errors follow RFC 7807 Problem Details with Content-Type: application/problem+json. Field-level validation failures include an optional errors[] array with field, code, and message.