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

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

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