Inkoom

API Documentation

All endpoints are authenticated with your reseller API key (shown once on the API Keys page). Keys start with ink_live_.

Authentication

Send your API key on every request as a Bearer token in the Authorization header, or via the x-api-key header. Keys are shown only once — store them like a password.

Authorization: Bearer ink_live_xxxxxxxxxxxx

Missing or invalid keys return 401 { success: false, error: "Invalid or missing API key" }.

Endpoints

GET/v1/balance
Your wallet and commission balances, plus your reseller role.
curl https://api.inkoom.com/v1/balance \
  -H "Authorization: Bearer ink_live_..."

Response: { success: true, data: { currency, wallet_balance, commission_balance, role } }

GET/v1/networks
Active networks (MTN, Telecel, AT, iShare, BigTime).
curl https://api.inkoom.com/v1/networks \
  -H "Authorization: Bearer ink_live_..."

Response: { success: true, data: [{ id, code, name }] }

GET/v1/products?network=mtn
Bundles for a network, priced at your tier.

Query params: network (required), service (data | airtime).

curl "https://api.inkoom.com/v1/products?network=mtn" \
  -H "Authorization: Bearer ink_live_..."

Response: { success: true, data: [{ id, name, service, volume_mb, validity_days, price }] }

POST/v1/purchase
Buy a bundle for a recipient.

The reference field makes the call idempotent — retrying with the same reference never charges twice.

curl https://api.inkoom.com/v1/purchase \
  -H "Authorization: Bearer ink_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "product_id": "0000-...-0000",
    "recipient": "0241234567",
    "reference": "my-order-00123"
  }'

Response: { success: true, data: { order_id, reference, recipient, amount, status, reason } }

  • status: "success" — delivered immediately.
  • status: "processing" — accepted upstream, waiting for confirmation.
  • status: "failed" — reason explains why.
GET/v1/orders/{id_or_reference}
Check an order's status.
curl https://api.inkoom.com/v1/orders/my-order-00123 \
  -H "Authorization: Bearer ink_live_..."

Response: { success: true, data: { order_id, reference, recipient, amount, status, refunded, reason } }

Webhooks

Subscribe an HTTPS endpoint in your Reseller dashboard and we'll POST signed events for every purchase and status change. Headers include X-Inkoom-Signature with an HMAC-SHA256 signature of the body.

{
  "event": "order.completed",
  "data": {
    "order_id": "...",
    "reference": "my-order-00123",
    "status": "success",
    "amount": 15.00,
    "recipient": "0241234567"
  }
}

Events: order.completed, order.failed, order.processing, balance.debited.

Errors

Every error returns JSON with success: false, an error string and a code for programmatic handling.

{
  "success": false,
  "error": "Insufficient wallet balance",
  "code": "insufficient_funds"
}

Base URL: https://api.inkoom.com · All amounts in GHS · Rate limit: 120 requests/min per key · Need help? Email support@inkoom.com