README

Lightweight PHP SDK for the iKhokha iK Pay API using file_get_contents, with an optional helper for the Fat-Free Framework.

• Framework-agnostic core client (Ikhokha\Client)
• No cURL; uses file_get_contents + stream_context_create
• Simple exception types
• Optional F3 helper (Ikhokha\F3\Service)

Installation

Via Composer (once published on Packagist):

composer require rrcatto/ikhokha-php-sdk

For local development, clone this repository and run:

composer install

Quick Start (Vanilla PHP)

<?php

require __DIR__ . '/vendor/autoload.php';

use Ikhokha\Client;
use Ikhokha\Exception\HttpException;
use Ikhokha\Exception\IkhokhaException;

$client = new Client(
    'YourAppIDHere',      // IK-APPID
    'YourAppSecretHere',  // AppSecret
    'APPID123'            // entityID / Application key ID
);

$payload = [
    'amount'                => 10000, // R100.00
    'currency'              => 'ZAR',
    'requesterUrl'          => 'https://example.com/requester',
    'mode'                  => 'live',
    'description'           => 'Cape Motorcycle Adventures – Suzuki DS250 rental',
    'externalTransactionID' => 'CMA-2025-0001',
    'urls' => [
        'callbackUrl'    => 'https://yourdomain/api/ikhokha/webhook',
        'successPageUrl' => 'https://yourdomain/payment/success',
        'failurePageUrl' => 'https://yourdomain/payment/failure',
        'cancelUrl'      => 'https://yourdomain/payment/cancel',
    ],
];

try {
    $response   = $client->createPaymentLink($payload);
    $paylinkUrl = $response['paylinkUrl'] ?? null;

    // Redirect or show link/button to $paylinkUrl
} catch (HttpException $e) {
    // Handle HTTP errors from Ikhokha
} catch (IkhokhaException $e) {
    // Handle client-side errors
}

Fat-Free Framework Helper

Configure your credentials in your F3 bootstrap (e.g. index.php):

$f3->set('IKHOKHA.APP_ID',     'YourAppIDHere');
$f3->set('IKHOKHA.APP_SECRET', 'YourAppSecretHere');
$f3->set('IKHOKHA.ENTITY_ID',  'APPID123');
$f3->set('IKHOKHA.BASE_URL',   'https://api.ikhokha.com'); // optional

Route example:

$f3->route('POST /api/paylink', function($f3) {
    $svc     = \Ikhokha\F3\Service::instance();
    $payload = json_decode($f3->get('BODY'), true) ?: [];
    $result  = $svc->createPaymentLink($payload);

    header('Content-Type: application/json');
    echo json_encode($result);
});

A simple webhook handler example:

$f3->route('POST /api/ikhokha/webhook', function($f3) {
    $rawBody = $f3->get('BODY');
    $headers = getallheaders();

    // Here you could verify ik-sign if you want, reusing the same signing logic.
    $payload = json_decode($rawBody, true) ?: [];

    // TODO: store $payload['status'], $payload['paylinkID'], $payload['externalTransactionID'], etc.
    http_response_code(200);
    echo 'OK';
});

Examples

See the examples/ directory for:

• quickstart.php – minimal CLI example
• create_payment_link.php – creating a paylink
• transaction_history.php – listing payments
• status_lookup.php – checking payment status
• f3_config.php – sample F3 configuration
• f3_route_create_payment_link.php – F3 route for creating paylinks
• f3_route_webhook.php – F3 route for handling webhooks

Requirements

• PHP 7.4+
• allow_url_fopen enabled (for HTTP via file_get_contents)

License

MIT – see LICENSE.