Developer hub
Hostra is payment settlement infrastructure exposed as a REST API described by OpenAPI 3.0 — no gRPC and no published SDK. This page is the map: conventions first, then the specific documentation, live status and architecture references you will need during an integration.
API conventions
- Base URL
- https://api.hostracore.com — resources live under /v1/…
- Auth
- Session cookie for user identity; Authorization: Bearer hstra_… or X-API-Key for merchant-scoped M2M access.
- Idempotency-Key
- UUID v4 required on settlement and transfer mutations; a repeat with the same key returns the original result.
- X-Request-ID
- Sent on every request and echoed through logs and settlement records for correlation.
- Errors
- RFC 7807 problem documents with type, title, status and a human-readable detail.
- Events
- Outbound webhooks signed with HMAC-SHA256, retried and dead-lettered.
A typical money-movement integration
- POST /v1/quotes — obtain a server-side quote; it is valid for 60 seconds and a stale quote is rejected with HTTP 410.
- POST /v1/transfers — create the transfer with a UUID v4 Idempotency-Key; the intent is durable before any provider call.
- GET /v1/transfers/{id} — read the authoritative status; never derive status client-side.
- Consume the signed webhook for the terminal state instead of polling indefinitely.
- Read receipts for succeeded operations where the API exposes them.
Keys and scopes
Machine-to-machine keys are merchant-scoped and carry RBAC scopes: transfers:read/write, quotes:read/write, settlements:read/write/reverse, audit:read, webhooks:read/write and devices:read/write. A full key is shown once at creation and only its prefix is stored afterwards. Keys must never be embedded in browser code.
References
- API documentation — endpoint reference and per-context OpenAPI specs.
- Live API — health, version and the aggregated OpenAPI document, fetched at request time.
- API status — component health for the bounded contexts.
- Architecture — services, state machines and message flow.
- Settlement engine — the durability and exactly-once guarantees the endpoints rely on.
- Audit trail — the hash-chain and its verification endpoint.
API documentationLive APIAPI statusArchitectureSettlement engineLedgerAudit trail
Machine-readable sources
Agents and tooling should prefer the generated sources over marketing pages: openapi.json, Swagger UI, health and llms.txt.