Server API Reference

The Zirzir server exposes a REST API for initiating payments, managing merchants, and configuring providers. All responses are JSON.

Base URL: https://your-zirzir-server.com (or http://localhost:8080 in development).

---

Authentication

The API uses two authentication methods:

Method	Header	Used by
Merchant API key	Authorization: Bearer zz_test_...	SDK / your backend
Admin API key	Authorization: Bearer <admin-key>	Server administration

API keys prefixed with zz_test_ route to sandbox environments. Keys prefixed with zz_live_ route to production.

---

Health

GET /health

No authentication required.

curl http://localhost:8080/health

{ "status": "ok" }

---

Payments

These endpoints require a merchant API key.

Create Payment

POST /api/v1/payments

curl -X POST http://localhost:8080/api/v1/payments \
  -H "Authorization: Bearer zz_test_..." \
  -H "Content-Type: application/json" \
  -d '{
    "provider": "chapa",
    "amount": 500,
    "currency": "ETB",
    "reference": "order-123",
    "customer_email": "[email protected]",
    "customer_name": "Abebe Bikila",
    "return_url": "https://yoursite.com/thank-you",
    "callback_url": "https://yoursite.com/webhooks"
  }'

Request body:

Field	Type	Required	Description
provider	string	yes	Provider code (chapa, telebirr, etc.)
amount	number	yes	Payment amount (> 0)
currency	string	no	ISO 4217 code. Defaults to ETB
reference	string	yes	Your unique transaction reference
customer_email	string	no	Customer email
customer_name	string	no	Customer name
customer_phone	string	no	Customer phone (required for USSD providers)
return_url	string	no	Redirect URL after payment
callback_url	string	no	Webhook URL for this transaction
metadata	object	no	Arbitrary key-value pairs

Response 201 Created:

{
  "id": "txn_01HX...",
  "merchant_id": "mrc_...",
  "provider": "chapa",
  "provider_txn_id": "chapa_abc123",
  "reference": "order-123",
  "amount": 500,
  "currency": "ETB",
  "status": "pending",
  "payment_url": "https://checkout.chapa.co/...",
  "customer_email": "[email protected]",
  "customer_name": "Abebe Bikila",
  "environment": "test",
  "created_at": "2025-01-15T10:30:00Z",
  "updated_at": "2025-01-15T10:30:00Z"
}

---

Get Payment

GET /api/v1/payments/:id

curl http://localhost:8080/api/v1/payments/txn_01HX... \
  -H "Authorization: Bearer zz_test_..."

Add ?refresh=true to query the provider for the latest status instead of returning the cached value.

---

List Payments

GET /api/v1/payments

curl "http://localhost:8080/api/v1/payments?status=completed&provider=chapa&limit=10&offset=0" \
  -H "Authorization: Bearer zz_test_..."

Query parameters:

Param	Type	Default	Description
status	string	—	Filter by status (pending, completed, failed, cancelled)
provider	string	—	Filter by provider code
start_date	string	—	Filter from date (YYYY-MM-DD)
end_date	string	—	Filter to date (YYYY-MM-DD)
limit	int	20	Results per page (max 100)
offset	int	0	Pagination offset

Response:

{
  "transactions": [ ... ],
  "total": 42,
  "limit": 20,
  "offset": 0
}

---

Providers

Public endpoints — no authentication required.

List Providers

GET /api/v1/providers

Returns all registered providers (built-in and plugins).

[
  {
    "code": "chapa",
    "name": "Chapa",
    "version": "1.0.0",
    "description": "Ethiopian online payment gateway",
    "countries": ["ET"],
    "currencies": ["ETB", "USD"],
    "payment_types": ["web_checkout"],
    "config_fields": [
      { "name": "secret_key", "label": "Secret Key", "type": "password", "required": true }
    ]
  }
]

Get Provider

GET /api/v1/providers/:code

Returns metadata for a single provider.

---

Webhooks

Provider Webhook

POST /api/v1/webhooks/:provider

No authentication — called by payment providers (Chapa, Telebirr, etc.) to notify Zirzir of payment status changes.

Zirzir parses the provider-specific payload, updates the transaction status, and forwards a normalized webhook to your callback_url.

---

Admin API

All admin endpoints require the admin API key set in security.admin_api_key.

Merchants

Method	Endpoint	Description
POST	/admin/merchants	Create a merchant
GET	/admin/merchants	List all merchants
GET	/admin/merchants/:id	Get a merchant
PUT	/admin/merchants/:id	Update a merchant
DELETE	/admin/merchants/:id	Delete a merchant

Create merchant:

curl -X POST http://localhost:8080/admin/merchants \
  -H "Authorization: Bearer $ADMIN_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "My App",
    "webhook_url": "https://yoursite.com/webhooks/zirzir"
  }'

---

Merchant Providers

Method	Endpoint	Description
POST	/admin/merchants/:id/providers	Configure a provider
GET	/admin/merchants/:id/providers	List configured providers
DELETE	/admin/merchants/:id/providers/:provider	Remove a provider

Configure provider:

curl -X POST http://localhost:8080/admin/merchants/$MERCHANT_ID/providers \
  -H "Authorization: Bearer $ADMIN_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "provider": "chapa",
    "environment": "test",
    "config": {
      "secret_key": "CHASECK_TEST-..."
    }
  }'

The config object is provider-specific. See the config_fields in each provider’s metadata (GET /api/v1/providers/:code) for the required fields.

---

Merchant API Keys

Method	Endpoint	Description
POST	/admin/merchants/:id/api-keys	Create an API key
GET	/admin/merchants/:id/api-keys	List API keys
DELETE	/admin/merchants/:id/api-keys/:keyId	Revoke an API key

Create API key:

curl -X POST http://localhost:8080/admin/merchants/$MERCHANT_ID/api-keys \
  -H "Authorization: Bearer $ADMIN_KEY" \
  -H "Content-Type: application/json" \
  -d '{"environment": "test", "label": "Backend service"}'

Response:

{
  "id": "key_...",
  "key": "zz_test_abc123...",
  "environment": "test",
  "label": "Backend service",
  "created_at": "2025-01-15T10:30:00Z"
}

The key value is only returned once at creation time. Store it securely.

---

Dashboard API

These endpoints are used by the built-in React dashboard and require a user auth token (cookie-based, set after login).

Auth

Method	Endpoint	Description
GET	/api/auth/setup	Check if initial setup is needed
POST	/api/auth/signup	Create a user account
POST	/api/auth/login	Log in
GET	/api/auth/me	Get current user
POST	/api/auth/logout	Log out

Projects

Method	Endpoint	Description
GET	/api/projects	List user’s projects
POST	/api/projects	Create a project
GET	/api/projects/:id	Get project details
GET	/api/projects/:id/api-keys	List project API keys
POST	/api/projects/:id/api-keys	Create a project API key
GET	/api/projects/:id/providers	List project providers
POST	/api/projects/:id/providers	Configure a provider for the project

---

Error Responses

All errors follow this format:

{
  "message": "provider is required"
}

Common HTTP status codes:

Code	Meaning
400	Bad request (missing fields, invalid data)
401	Unauthorized (missing or invalid API key)
404	Resource not found
500	Internal server error

---

Transaction Statuses

Status	Description
pending	Payment initiated, awaiting customer action
completed	Payment confirmed by the provider
failed	Payment failed or was declined
cancelled	Customer cancelled the payment

---

Next Steps

• Self-Hosting — deploy and configure the server
• Adding Providers — build a plugin for a new payment gateway
• Webhooks — webhook structure and signature verification