Integrating BMATROR API into Your Application
A developer-focused walkthrough of the BMATROR REST API — authentication, purchasing data programmatically, handling webhooks, and best practices for production deployments.
The BMATROR API enables businesses to embed mobile data, airtime, and utility payment capabilities directly into their applications. This guide covers everything you need for a production-ready integration.
Authentication
All API requests require an API key passed in the `X-API-Key` header. Generate keys from your dashboard under Settings → API Keys. Keys are scoped to your account and inherit your pricing tier.
GET /api/v1/wallet/balance
X-API-Key: bm_live_xxxxxxxxxxxx
Rate Limits
| Tier | Requests/Hour |
|---|---|
| Free | 100 |
| Pro | 1,000 |
| Enterprise | 5,000 |
Rate limit headers are included in every response: `X-RateLimit-Limit`, `X-RateLimit-Remaining`, `X-RateLimit-Reset`.
Purchasing Data
POST /api/v1/data/purchase
{
"network": "mtn",
"phone": "0241234567",
"bundle_id": "mtn_1gb_7day",
"reference": "your-unique-ref-001"
}
The `reference` field must be unique per request — use it for idempotency. Duplicate references return the original transaction status rather than creating a new purchase.
Webhooks
Configure webhook URLs in your dashboard to receive real-time transaction events:
- `transaction.completed` — successful delivery
- `transaction.failed` — failed with reason code
- `wallet.funded` — wallet top-up confirmed
Webhook payloads are signed with HMAC-SHA256. Verify the `X-BMATROR-Signature` header before processing.
Error Handling
Always implement retry logic with exponential backoff for 5xx errors. Do not retry 4xx errors except `429 Too Many Requests` (respect the `Retry-After` header). Failed transactions automatically refund to your wallet.
Sandbox Environment
Use `bm_test_` prefixed keys against `https://sandbox.bmatror.com` for development. Sandbox transactions do not deduct real wallet balance or deliver to actual phone numbers.
Support
For API support, email bisatro2016@gmail.com with your account ID and request/response logs (redact API keys). Enterprise customers receive a dedicated Slack channel.