REST API Overview

Base URL

Every endpoint in these docs is relative to your environment's base URL:

Production   https://api.infinityafrica.net
Sandbox      https://sandbox.infinityafrica.net
Local dev    http://localhost:8000

The response envelope

Every response — success or error, single object or paginated list — has the same top-level shape, so you only need to write one response parser:

{
  "success": true,
  "data": { "...": "..." },
  "meta": null
}

{
  "success": true,
  "data": [ { "...": "..." } ],
  "meta": { "page": 1, "page_size": 20, "total": 42, "total_pages": 3 }
}

{
  "success": false,
  "error": {
    "code": "insufficient_balance",
    "message": "Insufficient balance: available TZS 100,000, requested TZS 5,000,000",
    "details": null
  }
}

List endpoints accept ?page=1&page_size=20 (page_size caps at 100). See Error Codes for the full list of error.code values.

Authentication

Server-to-server requests — from your backend, not a browser — authenticate with an API key generated in the Merchant Portal, sent as an Authorization: Bearer header (or the equivalent X-API-Key header). Full detail, including scopes, sandbox vs. live keys, and key rotation, is in API Key Authentication.

Authorization: Bearer inf_live_51HbXxxxxxxxxxxxxxxxxxxxxxxx

Idempotency

Every endpoint that moves money — creating a payment link, initiating a collection, requesting a disbursement, or a customer completing a checkout — requires an Idempotency-Key header (any unique string, e.g. a UUID you generate per attempt). Retrying the same key with the same request body replays the original response instead of double-processing; reusing the key with a different body is rejected with 409 idempotency_key_reused.

API resources

Rate limits

Each merchant API key is limited to 120 requests per minute by default. Responses include no special rate-limit headers yet — if you need a higher limit for a high-volume integration, contact us.