Developer Documentation
Everything you need to integrate BalancYZ into your application workflow.
Tokens API Reference
Welcome to the BalancYZ API documentation. Our platform provides a comprehensive suite of tools for balance management, multi-gateway webhooks, and secure client authentication.
Base API URL
https://api.balancyz.com/v1
Authentication
API Key Auth
Standard method for backend-to-backend communication. Use your platform secret key.
bz_live_••••••••••••
Bearer Token
Commonly used with our SDKs and mobile integrations via Authorization headers.
Bearer bz_live_••••••••
Health Check
No Auth Required/health
Verifies the operational status of the BalancYZ core infrastructure.
Response Sample
{ "status": "ok", "version": "1.4.2" }Webhook Verification
Security is paramount. Every webhook sent to your endpoint includes a cryptographic signature. We strongly recommend verifying these signatures to ensure the traffic originates from our servers.
const crypto = require('crypto');
const signature = req.headers['x-balancyz-signature'];
const hmac = crypto.createHmac('sha256', YOUR_SECRET);
Integrated Flow
1. Create Client
Initialize a new user in the BalancYZ ledger to start tracking their balance.
-d '{"id": "user_42"}'
2. Topup via Webhook
We'll automatically add balance when a successful payment is detected.
AMOUNT: +500 CC