REST endpoints, signed webhooks, native idempotency.
3 isolated environments (production, staging, sandbox). HMAC-SHA256 on all webhooks. Rate limiting per API key. Official Node/Python/Ruby SDKs in development.
Feature
643
REST endpoints
3
isolated environments
HMAC-SHA256
signed webhooks
Idempotency-Key
native
Environments for safe integration flow
Production
Real environment. Real charges. Audited logs.
- https://api.billing.kobana.com.br
- Real charges
- Audited logs
Staging
Persistent data, gateways in sandbox. For pre-production validation.
- https://api-staging.billing.kobana.com.br
- Persistent data
- Gateways in sandbox
Sandbox
Periodic reset. Mocked gateways. Pre-defined test cards.
- https://api-sandbox.billing.kobana.com.br
- Periodic reset
- Test cards
What is available to integrate
Complete REST API
643 endpoints covering all resources: subscriptions, invoices, payments, customers, plans, NFe, proposals, events.
- Standardized JSON request/response
- Semantic HTTP status codes
- Cursor + offset pagination
- URL versioning (/v1)
Signed Webhooks
WebhookEndpoint per organization. Events selected via events array. Each delivery in WebhookDelivery with retry and backoff.
- HMAC-SHA256 via X-Kobana-Signature header
- Secret encrypted at rest (AES-256-GCM)
- 40+ event types
- Exponential retry up to 5 attempts
Native Idempotency
Idempotency-Key header accepted in all mutations. Server-side store guarantees same response for same key.
- UUID or ULID recommended
- Unique column in mutations
- Returns cached response
- Configurable TTL
Scoped API Keys
ApiKey per organization with permissions array. RateLimitConfig per key (req/s + burst).
- Read-only vs write
- Restriction by resource
- Immediate revocation
- Last used tracked
Rate Limiting
Limits per API key, IP and endpoint. X-RateLimit-* headers on all responses.
- Default 100 req/s per org
- Configurable per enterprise
- 429 with Retry-After
Internal Events
Event model records every state change. Useful for audit, replay and debug. EventDispatch worker fires webhooks.
- Type + resource + JSON data
- Filters by type and period
- Manual retry API
Sandbox with Test Cards
Isolated environment with mock gateway. Standard cards simulate approval, rejection, 3DS, expired.
- Reset on demand
- Webhooks delivered to configured endpoint (ngrok recommended)
- Same API as production
OpenAPI Spec
OpenAPI 3.x specification for SDK generation and interactive documentation.
- Hosted Swagger UI
- Postman collection
- Auto-generated SDKs
Gateway Callbacks
Public endpoints /api/callbacks/{provider} receive webhooks from Pagar.me, Kobana Banking Gateway, NFe.io. Processed via worker with dedicated handlers.
- Idempotency by payload
- Signature validation
- Logs in Callback model
Verify HMAC webhook signature
javascript
const crypto = require('crypto');
app.post('/webhooks/kobana', express.raw({ type: 'application/json' }), (req, res) => {
const signature = req.headers['x-kobana-signature'];
const secret = process.env.KOBANA_WEBHOOK_SECRET;
const expected = crypto
.createHmac('sha256', secret)
.update(req.body)
.digest('hex');
if (!crypto.timingSafeEqual(Buffer.from(signature), Buffer.from(expected))) {
return res.status(401).send('Invalid signature');
}
const event = JSON.parse(req.body);
switch (event.type) {
case 'invoice.paid':
// mark order as paid
break;
case 'subscription.canceled':
// remove access
break;
}
res.json({ received: true });
});