Our API uses dual authentication with API keys and shortcode tracking codes for secure, granular access control.

Every registered user gets a permanent API key, and each onboarded shortcode gets a unique tracking code. Both are required for API authentication.

API Key

  1. Getting Your API Key

    Upon registration, you'll automatically receive a unique API key displayed on your dashboard. This key authenticates all API requests and should be kept secure.

    Example API Key:
    pk_1a2b3c4d5e6f7g8h9i0j1k2l3m4n5o6p7q8r9s0t

  2. API Key Properties

    Your API key is permanent, unique, and tied to your account. It's automatically generated and cannot be changed for security reasons.

    Properties:
    • Permanent (never expires)
    • Unique per user account
    • Cannot be regenerated
    • Visible on your dashboard
    • Required for all API calls
  3. Get API Key

Shortcode Tracking Codes

  1. What is a Tracking Code?

    Each shortcode you onboard for C2B collections gets a unique tracking code. This identifies which shortcode receives payments in API calls.

    Example Tracking Code:
    sc_a1b2c3d4e5f6g7h8i9j0k1l2m3n4

  2. How Tracking Codes Work

    When you onboard a shortcode, our system automatically generates a tracking code. This maps to your shortcode and ensures payments go to the correct paybill.

    Mapping Example:
    Tracking Code: sc_a1b2c3d4e5f6g7h8i9j0k1l2m3n4
    → Shortcode: 880100
    → Business: Your Business Name
    → Account: ACC001

  3. Multiple Shortcodes

    You can onboard multiple shortcodes, each with its own tracking code. Use different tracking codes to route payments to different paybills.

    Multi-Shortcode Setup:
    Business A: sc_abc123... → 880100
    Business B: sc_def456... → 880200
    Business C: sc_ghi789... → 880300
  4. Manage Shortcodes

Request Headers

  1. Required Headers

    All API requests must include both authentication headers. Missing or invalid headers will result in 401 Unauthorized response.

    Required Headers:
    apikey: your_api_key_here
    linkid: your_shortcode_tracking_code
    Content-Type: application/json

  2. Header Validation

    Our system validates both headers on every request. The API key must belong to an active user, and the tracking code must belong to an active shortcode owned by that user.

    Validation Process:
    1. Validate API key exists and is active
    2. Find user associated with API key
    3. Validate tracking code belongs to user
    4. Ensure shortcode is active
    5. Process payment request

  3. Error Responses

    Invalid or missing authentication headers return specific error codes to help you troubleshoot integration issues.

    Authentication Errors:
    MISSING_HEADERS - Headers not provided
    INVALID_API_KEY - API key not found
    INVALID_LINK_ID - Tracking code invalid
    INACTIVE_SHORTCODE - Shortcode deactivated
  4. Payment API