Server API Reference

The Zirzir server exposes a REST API for orchestrating payments, generating payment links, checking circuit breaker health, and collecting Prometheus metrics.

Base URL: http://localhost:8080 (or https://api.yourcompany.com).

---

Authentication

Pass your API key using either the X-API-Key or Authorization: Bearer header:

X-API-Key: zz_test_9f81a2...

• zz_test_... routes to sandbox gateway environments.
• zz_live_... routes to production gateway networks.

---

Payments API

1. Create Payment (with Idempotency Protection)

POST /api/v1/payments

curl -X POST http://localhost:8080/api/v1/payments \
  -H "X-API-Key: zz_test_..." \
  -H "Idempotency-Key: 7b9a-4f12-88ef" \
  -H "Content-Type: application/json" \
  -d '{
    "provider": "telebirr",
    "amount": 350.00,
    "currency": "ETB",
    "reference": "ORD-9912",
    "customer_phone": "0911223344"
  }'

Headers:

• Idempotency-Key (optional, recommended): Prevents accidental double-charging during mobile network drops by returning cached responses (X-Cache: HIT-IDEMPOTENCY).

---

2. Generate Low-Connectivity USSD Intent

POST /api/v1/payments/ussd-intent

Generates offline USSD quick-dial strings for Telebirr (*127#), CBE Birr (*847#), and M-Pesa (*334#).

curl -X POST http://localhost:8080/api/v1/payments/ussd-intent \
  -H "X-API-Key: zz_test_..." \
  -H "Content-Type: application/json" \
  -d '{
    "amount": 250.00,
    "currency": "ETB",
    "reference": "RETAIL-101"
  }'

---

3. Hosted Payment Links

POST /api/v1/payment-links

Create instant shareable checkout URLs for WhatsApp, SMS, or invoicing:

curl -X POST http://localhost:8080/api/v1/payment-links \
  -H "X-API-Key: zz_test_..." \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Freelance Code Review",
    "amount": 1250.00,
    "currency": "ETB",
    "reusable": true
  }'

---

Telemetry & Health

GET /health

Returns system health status:

{ "status": "ok" }

GET /metrics

Returns standard Prometheus metrics for Grafana monitoring.