Quickstart

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.

Getting started

Customization

Writing content

AI tools

Before you begin

Step 1: Get an access token

Step 2: Verify connectivity

Step 3: Post your first payment

Step 4: Read the loan balance

Next steps

API Reference

Idempotency

Error handling

Local development

​Before you begin

​Step 1: Get an access token

​Step 2: Verify connectivity

​Step 3: Post your first payment

​Step 4: Read the loan balance

​Next steps

API Reference

Idempotency

Error handling

Local development

Before you begin

Step 1: Get an access token

Step 2: Verify connectivity

Step 3: Post your first payment

Step 4: Read the loan balance

Next steps