API Documentation Overview

For external funnels, the usual flow is: Hoplink redirect -> landing page captures tracking -> smart links forward the tracking into Kinu checkout -> your server sends a signed postback to confirm the conversion.

1. Get Account Details

Endpoint: GET https://kinu.africa/api/account/details

Description: Retrieves details of the account associated with the provided API key.

2. Get All Items

Endpoint: GET https://kinu.africa/api/items/all

Description: Retrieves all items associated with the provided API key.

3. Get An Item Details

Endpoint: GET https://kinu.africa/api/items/item

Description: Retrieves details of a specific item based on the provided item ID and API key.

4. Checkout Smart Links

Pattern: Hosted checkout links + client-side JavaScript snippet

Description: Preserves Kinu-issued affiliate tracking parameters such as kinu_aff, aff_sig, tid, and kc when a buyer moves from an external landing page into the hosted Kinu checkout.

5. Affiliate Conversion Postback

Endpoint: POST https://kinu.africa/api/v1/postback

Description: Lets an author-owned funnel or checkout server confirm a conversion back to Kinu using the hoplink click ID and a signed HMAC request.

6. Purchase Validation

Endpoint: POST https://kinu.africa/api/purchases/validation

Description: Validate a purchase code and returns details about the purchase if valid.

Authentication

Navigate to Workspace Settings

The user should first log in to their account on the platform. Then, they can navigate to the "Settings" section of their workspace.

Locate API Key Section

Within the workspace settings, the user should look for a section specifically labeled "API Key" or "API Access."

Generate or Retrieve API Key

In this section, the user can either generate a new API key or retrieve an existing one if it has been previously generated. If there is an option to generate a new key, the user can click on it to create a fresh API key.

Copy the API Key

Once the API key is generated or retrieved, the user should be able to see it displayed on the screen. They can simply click on a button or icon next to the key to copy it to their clipboard.

Use the API Key

With the API key copied, the user can now use it to authenticate their requests when accessing the platform API endpoints. They typically need to include the API key as part of the request headers or parameters, depending on the API authentication mechanism.

Secure the API Key

Its essential to remind users to keep their API keys secure and not share them publicly. They should avoid hardcoding API keys in client-side code or sharing them in publicly accessible repositories. Instead, they should consider storing the API key securely on their server-side applications and using appropriate access controls.

Get Account Details

Retrieves details of the account associated with the provided API key

Endpoint


            GET
https://kinu.africa/api/account/details

Parameters

api_key: Your API key (Required)

Responses

Success Response:


            {
    "status": "success",
    "data": {
        "name": {
            "firstname": "John",
            "lastname": "Doe",
            "full_name": "John Doe"
        },
        "username": "johndoe",
        "email": "john.doe@example.com",
        "balance": 100.00,
        "currency": "TZS",
        "profile": {
            "heading": "Profile Heading",
            "description": "Profile Description",
            "contact": {
                "email": "contact@example.com"
            },
            "social_links": [
                "facebook": "/",
                "x": "/",
                // etc...
            ],
            "media": {
                "avatar": "https://example.com/avatar.jpg",
                "cover": "https://example.com/cover.jpg"
            }
        },
        "registered_at": "2024-04-27T12:00:00Z"
    }
}

Error Response:


            {
    "status": "error",
    "msg": "Invalid request"
}

Get All Items

Retrieves all items associated with the provided API key

This only works for authors and will not work for regular users.

Endpoint


            GET
https://kinu.africa/api/items/all

Parameters

api_key: Your API key (Required)

Responses

Success Response:


            {
    "status": "success",
    "items": [
        {
            "id": 1,
            "name": "Sample Item",
            "description": "This is a sample item",
            "category": "Category Name",
            "sub_category": "Subcategory Name",
            "options": ["option1", "option2"],
            "version": 1.0.0,
            "demo_link": "https://example.com/demo",
            "tags": ["tag1", "tag2"],
            "media": {
                "thumbnail": "https://example.com/thumbnail.png",
                "preview_image": "https://example.com/preview.jpg", // This is not included for audio items
                "preview_video": "https://example.com/video.mp4", // This is only included for video items
                "preview_audio": "https://example.com/audio.mp3", // This is only included for audio items
                "screenshots": [ // This is only included if item has screenshots
                    "https://example.com/screenshot1.jpg",
                    "https://example.com/screenshot2.jpg"
                ],
            },
            "price": {
                "regular": 19.99,
                "extended": 29.99
            },
            "currency": "TZS",
            "published_at": "2024-04-27T12:00:00Z"
        },
        {
            // Next item...
        }
    ]
}

Error Response:


            {
    "status": "error",
    "msg": "No items found"
}

Get An Item Details

Retrieves details of a specific item based on the provided item ID and API key.

This only works for authors and will not work for regular users.

Endpoint


            GET
https://kinu.africa/api/items/item

Parameters

api_key: Your API key (Required)
item_id: The ID of the item to retrieve (Required)

Responses

Success Response:


            {
    "status": "success",
    "item": {
        "id": 1,
        "name": "Sample Item",
        "description": "This is a sample item",
        "category": "Category Name",
        "sub_category": "Subcategory Name",
        "options": ["option1", "option2"],
        "version": 1.0.0,
        "demo_link": "https://example.com/demo",
        "tags": ["tag1", "tag2"],
        "media": {
            "thumbnail": "https://example.com/thumbnail.png",
            "preview_image": "https://example.com/preview.jpg", // This is not included for audio items
            "preview_video": "https://example.com/video.mp4", // This is only included for video items
            "preview_audio": "https://example.com/audio.mp3", // This is only included for audio items
            "screenshots": [ // This is only included if item has screenshots
                "https://example.com/screenshot1.jpg",
                "https://example.com/screenshot2.jpg"
            ],
        },
        "price": {
            "regular": 19.99,
            "extended": 29.99
        },
        "currency": "TZS",
        "published_at": "2024-04-27T12:00:00Z"
    }
}

Error Response:


            {
    "status": "error",
    "msg": "Item Not Found"
}

Checkout Smart Links

Use this pattern when your landing page lives outside Kinu and you want affiliate tags to survive the click into the hosted item checkout.

This example is safe to publish because it contains no secrets, API keys, or private credentials. It only forwards Kinu-issued tracking parameters such as kinu_aff, aff_sig, tid, and kc.

Base Checkout Pattern


            GET
https://kinu.africa/checkout/item/123

Smart Link JavaScript Snippet

Paste this on your external landing page to automatically append affiliate tracking parameters to Kinu checkout links on the page.


            <script>
document.addEventListener("DOMContentLoaded", function () {
    const storageKey = "kinu_affiliate_tracking";
    const trackedKeys = ["kinu_aff", "aff_sig", "tid", "kc"];

    function normalizeValue(key, value) {
        const raw = String(value || "").trim();
        if (!raw) {
            return "";
        }

        if (key === "tid") {
            return raw
                .replace(/[^A-Za-z0-9._-]+/g, "_")
                .replace(/^[._-]+|[._-]+$/g, "")
                .slice(0, 50);
        }

        return raw.slice(0, 255);
    }

    function parseParams(input) {
        const source = String(input || "").replace(/^#/, "");
        const params = new URLSearchParams(source);
        const payload = {};

        trackedKeys.forEach(function (key) {
            const normalized = normalizeValue(key, params.get(key));
            if (normalized) {
                payload[key] = normalized;
            }
        });

        return payload;
    }

    function loadStoredPayload() {
        try {
            const stored = window.localStorage.getItem(storageKey);
            return stored ? JSON.parse(stored) : {};
        } catch (error) {
            return {};
        }
    }

    function storePayload(payload) {
        try {
            if (Object.keys(payload).length === 0) {
                return;
            }

            window.localStorage.setItem(storageKey, JSON.stringify(payload));
        } catch (error) {
            // Ignore storage failures in locked-down browsers.
        }
    }

    const storedPayload = loadStoredPayload();
    const searchPayload = parseParams(window.location.search);
    const hashPayload = parseParams(window.location.hash);
    const payload = Object.assign({}, storedPayload, searchPayload, hashPayload);

    if ((payload.kinu_aff && payload.aff_sig) || payload.kc) {
        storePayload(payload);

        const links = document.querySelectorAll('a[href*="https://kinu.africa/checkout/item/"]');
        links.forEach(function (link) {
            const checkoutUrl = new URL(link.href);

            trackedKeys.forEach(function (key) {
                if (payload[key]) {
                    checkoutUrl.searchParams.set(key, payload[key]);
                }
            });

            link.href = checkoutUrl.toString();
        });
    }
});
</script>

How It Works

kinu_aff: The affiliate ID to preserve from the current landing page URL.
aff_sig: A Kinu-issued signature that proves the affiliate attribution came from a real hoplink.
tid: An optional sub-tracking identifier used for campaign or ad-set attribution.
kc: An opaque Kinu click identifier that lets checkout and postback flows recover attribution even when cookies fail.
Target matching: Only links pointing to https://kinu.africa/checkout/item/ are rewritten.
Fallbacks: The snippet also reads fragment values and localStorage so attribution can survive stripped query parameters on stricter browsers.
Use case: Ideal for external pages, advertorials, funnel builders, and custom thank-you flows that hand the visitor back into Kinu checkout.

Affiliate Conversion Postback

Use this endpoint when your funnel needs to confirm a conversion back to Kinu server-to-server using the opaque click ID from the hoplink redirect.

Authenticate with your author API key and sign the raw JSON request body using HMAC-SHA256.

After a real signed postback succeeds, authors can verify the connection in Workspace -> Item -> Integration, where Kinu records successful and failed attempts and marks the integration green only after a valid success.

Endpoint


            POST
https://kinu.africa/api/v1/postback

Required Headers

Authorization: Bearer YOUR_AUTHOR_API_KEY
X-KINU-TIMESTAMP: Unix timestamp for replay protection
X-KINU-SIGNATURE: HMAC_SHA256(timestamp + "." + raw_body, api_key)

Example Payload


            {
  "click_id": "kc_example_click_id",
  "order_id": "vendor-order-1001",
  "item_id": 123,
  "amount": 49000.00,
  "currency": "TZS",
  "customer_email": "buyer@example.com",
  "customer_name": "Buyer Example",
  "license_type": 1
}

How It Works

click_id: The opaque Kinu click identifier appended to the hoplink redirect as kc.
order_id: Your idempotency key for this conversion. Reusing the same value returns the same recorded postback for that author.
item_id: Must belong to the authenticated author and still be approved.
amount / currency: Used to create the attributed conversion record and downstream affiliate earning.
customer_email / customer_name: Used to provision or match the buyer record for the conversion.
Replay window: The timestamped signature expires quickly, so your server should sign and send the request immediately.
Audit trail: Kinu records both successful and failed postback attempts so authors can verify whether the external server is healthy.

Success Response


            {
    "status": "success",
    "data": {
        "postback_id": 15,
        "transaction_id": 4021,
        "transaction_token": "trx_public_token",
        "affiliate_id": 2,
        "click_id": "kc_example_click_id",
        "order_id": "vendor-order-1001",
        "currency": "TZS",
        "amount": 49000,
        "attribution_type": "affiliate"
    }
}

Common Error Responses

Invalid API credentials


            {
    "status": "error",
    "msg": "Invalid API credentials"
}

Invalid or expired postback signature


            {
    "status": "error",
    "msg": "Invalid or expired postback signature"
}

Validation failure example


            {
    "message": "The selected click id is invalid.",
    "errors": {
        "click_id": [
            "The selected click id is invalid."
        ]
    }
}

Purchase Validation

Validate a purchase code and returns details about the purchase if valid.

This only works for authors and will not work for regular users.

Endpoint


            POST
https://kinu.africa/api/purchases/validation

Parameters

api_key: Your API key (Required).
purchase_code: The purchase code to validate (Required).

Responses

Success Response:


            {
    "status": "success",
    "data": {
        "purchase": {
            "purchase_code": "abcdefghijklmnopqrstuvwxyz123456789",
            "license_type": "Standard",
            "price": 19.99,
            "currency": "TZS",
            "item": {
                "id": 1,
                "name": "Sample Item",
                "description": "This is a sample item",
                "category": "Category Name",
                "sub_category": "Subcategory Name",
                "options": ["option1", "option2"],
                "version": 1.0.0,
                "demo_link": "https://example.com/demo",
                "tags": ["tag1", "tag2"],
                "media": {
                    "thumbnail": "https://example.com/thumbnail.png",
                    "preview_image": "https://example.com/preview.jpg", // This is not included for audio items
                    "preview_video": "https://example.com/video.mp4", // This is only included for video items
                    "preview_audio": "https://example.com/audio.mp3", // This is only included for audio items
                    "screenshots": [ This is only included if item has screenshots
                        "https://example.com/screenshot1.jpg",
                        "https://example.com/screenshot2.jpg"
                    ],
                },
                "price": {
                    "regular": 19.99,
                    "extended": 29.99
                },
                "currency": "TZS",
                "published_at": "2024-04-27T12:00:00Z"
            },
            "supported_until": "2024-04-27T12:00:00Z", // This will not exist if support is disabled or its not supported
            "downloaded": false,
            "date": "2024-04-27T12:00:00Z"
        }
    }
}

Error Response:


            {
    "status": "error",
    "msg": "Invalid purchase code"
}