Configuration

Zirzir supports two operating modes:

• Standalone Mode — the SDK talks directly to payment gateway APIs. No server needed. Good for getting started fast or simple integrations.
• Server Mode — the SDK talks to a Zirzir server (self-hosted or Zirzir Cloud). Unlocks webhook infrastructure, transaction ledger, dashboard, multi-project support, and RBAC.

Most production deployments use Server Mode. But Standalone Mode is the fastest way to start.

---

Standalone Mode

Configure the SDK to talk directly to a payment gateway. No server required.

TypeScript

import { Zirzir } from '@zirzir/sdk'

const zirzir = new Zirzir({
  provider: 'chapa',
  credentials: {
    secretKey: process.env.CHAPA_SECRET_KEY!
  }
})

Python

import zirzir

client = zirzir.Zirzir(
    provider="chapa",
    credentials={
        "secret_key": os.environ["CHAPA_SECRET_KEY"]
    }
)

Go

import "github.com/recite-labs/zirzir-go"

client := zirzir.New(zirzir.Config{
    Provider: "chapa",
    Credentials: map[string]string{
        "secret_key": os.Getenv("CHAPA_SECRET_KEY"),
    },
})

---

Server Mode

Point the SDK at a Zirzir server instance. The server handles provider routing, credentials, webhook normalization, and everything else.

TypeScript

import { Zirzir } from '@zirzir/sdk'

const zirzir = new Zirzir({
  baseUrl: process.env.ZIRZIR_BASE_URL!,   // e.g. https://pay.yourcompany.com
  apiKey: process.env.ZIRZIR_API_KEY!       // zz_live_... or zz_test_...
})

Python

import zirzir

client = zirzir.Zirzir(
    base_url=os.environ["ZIRZIR_BASE_URL"],
    api_key=os.environ["ZIRZIR_API_KEY"]
)

Go

client := zirzir.New(zirzir.Config{
    BaseURL: os.Getenv("ZIRZIR_BASE_URL"),
    APIKey:  os.Getenv("ZIRZIR_API_KEY"),
})

---

Environment Variables

We strongly recommend keeping credentials in environment variables, never in source code.

Variable	Description
ZIRZIR_BASE_URL	Your Zirzir server URL
ZIRZIR_API_KEY	Your project API key (zz_live_ or zz_test_)
CHAPA_SECRET_KEY	Chapa secret key (standalone mode)
TELEBIRR_APP_ID	Telebirr App ID (standalone mode)
TELEBIRR_APP_KEY	Telebirr App Key (standalone mode)
TELEBIRR_SHORT_CODE	Telebirr merchant short code
CBEBIRR_USERNAME	CBEBirr merchant username
CBEBIRR_PASSWORD	CBEBirr merchant password

---

Multiple Providers (Standalone)

In standalone mode, you can instantiate multiple clients:

import { Zirzir } from '@zirzir/sdk'

const chapa = new Zirzir({ provider: 'chapa', credentials: { secretKey: '...' } })
const telebirr = new Zirzir({ provider: 'telebirr', credentials: { appId: '...', appKey: '...', shortCode: '...' } })

// Use whichever is appropriate for the customer
const tx = await (customerPrefersMobileMoney ? telebirr : chapa).charge({
  amount: 500,
  currency: 'ETB',
  email: '[email protected]',
})

In server mode, provider selection is handled server-side — your code stays clean.

---

Test vs. Live Mode

API keys prefixed with zz_test_ route all transactions to sandbox environments automatically. No extra configuration needed.

// Test mode — hits sandbox APIs
const zirzir = new Zirzir({
  baseUrl: 'https://pay.yourcompany.com',
  apiKey: 'zz_test_abc123'
})

// Live mode
const zirzir = new Zirzir({
  baseUrl: 'https://pay.yourcompany.com',
  apiKey: 'zz_live_abc123'
})

Never use live API keys in development or CI environments. Each provider’s sandbox behaves slightly differently from production — see individual Provider Guides for known sandbox quirks.

---

Zirzir Cloud

Don’t want to manage a server? Zirzir Cloud gives you the full server experience — dashboard, webhooks, multi-project, RBAC — without running anything yourself.

const zirzir = new Zirzir({
  baseUrl: 'https://api.zirzir.dev',
  apiKey: 'zz_live_...'  // Get this from the Zirzir Cloud dashboard
})

Same SDK, same API, zero ops.