Billing API Quickstart

Server overview

Base URL: https://api.kirha.com/billing/v1
Requests and responses use application/json

Authentication

All Billing API calls must include an Authorization: Bearer <token> header. Two credential flows are supported:

API keys

API keys are project-scoped and require no extra headers:

Authorization: Bearer kirha_api_key

User JWTs

User session tokens let you act on behalf of an organization. Add the X-Organization-ID header to select the active organization:

Authorization: Bearer user_session_jwt
X-Organization-ID: org_123

Missing headers yield 401 Unauthorized.

Error model

Failures return a normalized payload:

{
  "error": {
    "code": "ERROR_CODE",
    "message": "Human readable summary",
    "details": {
      "optional": "context"
    }
  }
}

Common error codes include INVALID_REQUEST, UNAUTHORIZED, ACCOUNT_NOT_FOUND, CURRENCY_NOT_SUPPORTED, PAYMENT_NOT_COMPLETED, PAYMENT_ALREADY_USED, and INTERNAL_ERROR.

Use GET /account/balance to get current balance.

POST /account/topup initiates a purchase and quotes the exact on-chain payment expected. The flow completes once the on-chain transfer is mined and confirmed with POST /account/topup/{id}/complete.

Initiate the top-up

{
  "type": "crypto",
  "currency_id": "eth",
  "credits": 1000
}

The response includes the quoted amount, currency_id, and destination_address.

Send the blockchain transfer Transfer the quoted amount to the Kirha treasury address out-of-band. The invoice stays in requested status until the transaction is mined.

Confirm completion Call POST /account/topup/{id}/complete with the payment hash:

{ "transaction_hash": "0xpaymenthash" }

Successful validation moves the purchased credits into your top-up balance.

Refer to the API Reference for full schemas and status codes.