Skip to main content

​
Before you begin

You’ll need:
  • A Clarivo tenant account
  • OAuth2 client credentials (client_id and client_secret) from app.clarivo.co
  • The base URL for your environment: https://ledger.clarivo.co/v1 (production) or https://ledger.staging.clarivo.co/v1 (staging)

​
Step 1: Get an access token

Exchange your client credentials for a bearer token using the OAuth2 client credentials flow. 
curl -X POST https://auth.example.com/oauth2/token \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "grant_type=client_credentials" \
  -d "client_id=YOUR_CLIENT_ID" \
  -d "client_secret=YOUR_CLIENT_SECRET" \
  -d "scope=hpts:payments:write hpts:balances:read hpts:ledger:read"
Response
{
  "access_token": "eyJ...",
  "token_type": "Bearer",
  "expires_in": 3600
}
Tokens expire after 1 hour. Cache and refresh them rather than requesting a new one for every API call.

​
Step 2: Verify connectivity

Check that the service is live and your network can reach it — no authentication required. 
curl https://ledger.clarivo.co/v1/health/live
Response
{
  "status": "ok",
  "version": "1.4.2",
  "git_sha": "a3f9e12"
}

​
Step 3: Post your first payment

Record a loan payment. Every POST requires an Idempotency-Key — choose a deterministic key that is unique per event. 
curl -X POST https://ledger.clarivo.co/v1/payments \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: payment:loan_42:proc_txn_abc123" \
  -d '{
    "loan_id": "11111111-1111-1111-1111-111111111111",
    "borrower_id": "22222222-2222-2222-2222-222222222222",
    "amount_minor": "88849",
    "currency": "USD",
    "effective_at": "2026-05-01",
    "source_method": "ach",
    "external_ref": "stripe_ch_xyz123"
  }'
Response (201 Created)
{
  "payment_event_id": "aaaaaaaa-aaaa-aaaa-aaaa-aaaaaaaaaaaa",
  "journal_entry_id": "bbbbbbbb-bbbb-bbbb-bbbb-bbbbbbbbbbbb",
  "allocation": {
    "fees_minor": "500",
    "interest_minor": "10000",
    "principal_minor": "78349",
    "suspense_minor": "0"
  },
  "posted_at": "2026-05-01T12:00:00Z"
}
amount_minor is always expressed in the currency’s minor unit as a string (e.g. cents for USD) to avoid floating-point precision issues.

​
Step 4: Read the loan balance

curl "https://ledger.clarivo.co/v1/loans/11111111-1111-1111-1111-111111111111/balance" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"
Response
{
  "loan_id": "11111111-1111-1111-1111-111111111111",
  "currency": "USD",
  "as_of_date": "2026-05-01",
  "principal_outstanding_minor": "921651",
  "interest_receivable_minor": "0",
  "fees_receivable_minor": "0",
  "total_exposure_minor": "921651"
}

​
Next steps

API Reference

Full reference for all endpoints with request/response schemas.

Idempotency

Learn the idempotency contract and recommended key formats.

Error handling

All errors follow RFC 7807 Problem Details format.

Local development

Run these docs locally to contribute or preview changes.