Base URL versioning
Use versioned paths under /api/v1. Breaking API changes move to a new version while compatible additions remain in the active v1 contract.
Developer readiness
Billie API docs
Public integration foundations for Billie API consumers, including versioned URLs, key prefixes, idempotent writes, request tracing, errors, limits, and contract downloads.
Foundation
API key authentication
Send API keys in the Authorization header as Bearer tokens. Sandbox keys start with sk_test_ and live keys start with sk_live_; never expose either key in browser code.
Sandbox vs live
Use sandbox keys for test traffic and live keys only after operational approval. Sandbox responses are isolated from live settlement, payout, and customer access workflows.
Operational contract
Idempotency-Key
Send Idempotency-Key on every write that can create money movement or external side effects. Reuse the same key only for the same logical retry.
X-Request-Id
Send X-Request-Id for caller-side tracing. Billie returns a request identifier on responses so support can correlate logs, metrics, retries, and audit records.
Error model
Errors use a consistent JSON body with code, message, requestId, and optional field details. Clients should branch on code rather than parsing human text.
Rate-limit headers
Rate-limited responses include X-RateLimit-Limit, X-RateLimit-Remaining, X-RateLimit-Reset, and Retry-After when a retry window is known.
Example request and contracts
Start with the contract links, then use this cURL shape for sandbox write calls that need authentication, idempotency, and request tracing.
curl --request POST https://api.billie.co.zw/api/v1/developer/sandbox/checkout-sessions \
--header 'Authorization: Bearer sk_test_1234567890abcdef' \
--header 'Content-Type: application/json' \
--header 'Idempotency-Key: checkout-demo-0001' \
--header 'X-Request-Id: req-demo-0001' \
--data '{"merchantReference":"INV-1001","title":"School fees","amount":25.50,"currency":"USD"}'