Zirzir offers two fundamentally different ways to integrate: standalone mode (SDK talks directly to payment providers) and server mode (SDK talks to the Zirzir server, which talks to providers). Choosing the right one depends on your team size, operational needs, and growth trajectory.
Standalone mode
In standalone mode, the SDK communicates directly with payment provider APIs. You pass provider credentials to the SDK, and it handles the request formatting, response parsing, and error normalization internally.
const zirzir = new Zirzir({ mode: 'standalone', providers: { chapa: { secretKey: process.env.CHAPA_SECRET_KEY }, telebirr: { appId: process.env.TELEBIRR_APP_ID, appKey: process.env.TELEBIRR_APP_KEY, publicKey: process.env.TELEBIRR_PUBLIC_KEY, }, }, }); ```
Best for: - Early-stage startups with a single application - Projects that only need 1-2 providers - Teams that want minimal infrastructure overhead - Serverless deployments (Lambda, Vercel Functions)
Trade-offs: - No dashboard or transaction history (unless you build it) - No webhook retry engine — you handle callbacks yourself - Credentials live in your application environment - No multi-project isolation
Server mode
In server mode, the SDK communicates with a running Zirzir server instance. The server handles provider communication, credential storage, webhook management, and provides a dashboard.
const zirzir = new Zirzir({ mode: 'server', baseUrl: 'https://payments.yourcompany.com', apiKey: process.env.ZIRZIR_API_KEY, }); ```
Best for: - Teams with multiple applications sharing payment infrastructure - Companies needing audit trails and transaction reconciliation - Operations teams that want a dashboard without building one - Multi-environment setups (test/live credential isolation)
Trade-offs: - Requires running and maintaining the Zirzir server - Adds a network hop between your app and the payment provider - More infrastructure to monitor and secure
The migration path
The beauty of Zirzir's design is that your application code stays identical regardless of mode. The same charge(), verify(), and refund() calls work in both modes. Switching from standalone to server mode is a configuration change, not a rewrite.
Start with standalone mode to move fast. When you need operational infrastructure — dashboard, webhook retries, multi-project isolation — deploy the server and update your config. Your payment logic doesn't change.
Our recommendation
Start standalone if you're a small team shipping quickly and only need one or two providers. You can always add the server later.
Start with the server if you're building a platform, have multiple teams or projects, or know you'll need operational visibility from day one. The server is a single Go binary — deployment isn't complicated.
Either way, you're building on the same normalized payment interface. The architecture decision is about operations, not code.