API Reference

API overview

Base URL, authentication, errors, and conventions for the Onzo API.

BASEhttps://api.onzo.la/v1Production

BASEhttps://api.test.onzo.la/v1Test mode

All requests are HTTPS, authenticated with a bearer key, and return JSON.

curl https://api.onzo.la/v1/capabilities \
  -H "Authorization: Bearer oz_sk_live_..." \
  -H "Onzo-Version: 2026-09-01"

Conventions

Convention	Behavior
Identifiers	Prefixed and stable: `oz_pay_`, `oz_acct_`, `oz_scr_`, `oz_quote_`, `oz_exp_`, `oz_ret_`
Amounts	Decimal strings with explicit currency: `{ "value": "48500.00", "currency": "USD" }`
Idempotency	`Idempotency-Key` header on every write; keys retained 24 hours
Pagination	Cursor-based: `limit`, `cursor`, response `has_more` / `next_cursor`
Versioning	Date-based via `Onzo-Version` header, pinned per account
Timestamps	RFC 3339, UTC

Errors

Errors return a consistent envelope with a documented code (see Failure reasons):

{
  "error": {
    "type": "screening_declined",
    "code": "sanctions_match",
    "message": "Counterparty matched a sanctions list.",
    "payment": "oz_pay_8f2c41"
  }
}

HTTP	Meaning
`400`	Invalid request — fix the payload
`401`	Missing or invalid API key
`403`	Key lacks the required capability scope
`404`	Object does not exist in this environment
`409`	Idempotency conflict — same key, different payload
`422`	Valid request refused: screening or limits (see `code`)
`429`	Rate limited — respect `Retry-After`

Payments