CironetPay

What is CironetPay?

CironetPay is a centrally hosted payment gateway developed and operated by Cironet Technologies Limited. It sits between the applications that need to accept payments (Nodes) and the payment service providers that process them. It is the single, unified layer through which all payment activity in the Cironet ecosystem flows.

Nodes know CironetPay. CironetPay knows the payment provider. The provider knows Cironet Technologies as the merchant. No node ever interacts with a payment provider directly.

The Problem

Accepting digital payments in Uganda is complex. Every provider has its own API, authentication mechanism, and webhook format. For a company operating multiple products and building platforms for various clients, this creates significant overhead:

• Integration Duplication: Rebuilding the same mobile money integration in every product.
• Credential Sprawl: Managing separate API keys across many products is a security risk.
• Onboarding Friction: Clients find PSP registration processes slow and inaccessible.
• Fragmented Records: Payment data lives in separate silos with no unified overview.

The Solution

How It Works

Merchant Identity Model

CironetPay operates on a single-merchant, multi-source model. Payment providers see only Cironet Technologies Limited as the merchant.

Who It Serves

Core Capabilities

Checkout Flow (Node Integration)

Nodes integrate via a redirect checkout. The Node builds a form with the required fields, signs it with a HMAC hash, and POSTs the user to CironetPay.

Step 1 — Build and POST the form

// PHP example — Node side (e.g. messaging.cironetug.com)
$app_key    = 'cp_live_msg_...';   // Your node's API key
$app_secret = 'cp_sec_msg_...';   // Your node's secret (kept private)
$reference  = 'CTR' . bin2hex(random_bytes(6));  // Unique per transaction
$amount     = 10000;               // UGX

$hash = hash('sha256', $app_key . $reference . $amount . $app_secret);

// POST these fields to https://pay.cironetug.com/checkout.php
$payload = [
    'app_key'        => $app_key,
    'reference'      => $reference,
    'amount'         => $amount,
    'currency'       => 'UGX',
    'customer_email' => $user_email,
    'callback_url'   => 'https://yourapp.com/api/payment_callback.php',
    'return_url'     => 'https://yourapp.com/user/history.php',
    'hash'           => $hash,
];

Step 2 — CironetPay handles the rest

The user is shown a phone number input on the CironetPay checkout page, enters their Mobile Money number, and authorizes the payment on their phone. The Node does not handle any of this.

Authentication

Nodes are authenticated via two values that must both be correct for a checkout to proceed:

Request Fields

Webhook Callback

When a payment completes, CironetPay sends a POST request to the Node's callback_url with a JSON body and a signature header.

Webhook Payload

{
  "reference":      "CTR3f8a92b1c4d5",
  "amount":         10000,
  "status":         "completed",
  "transaction_id": "a4b2c8d1e6f0..."
}

Webhook Headers

Content-Type: application/json
X-CironetPay-Signature: <hmac-sha256-hex>

Node-side handling

// PHP — verify the webhook before processing
$raw_body      = file_get_contents('php://input');
$provided_sig  = $_SERVER['HTTP_X_CIRONETPAY_SIGNATURE'] ?? '';
$webhook_secret = 'whs_...'; // your cironetpay_webhook_secret

$expected_sig = hash_hmac('sha256', $raw_body, $webhook_secret);

if (!hash_equals($expected_sig, $provided_sig)) {
    http_response_code(401);
    exit('Invalid signature');
}

$data = json_decode($raw_body, true);
if ($data['status'] === 'completed') {
    // Credit wallet, activate service, fulfill order...
}

http_response_code(200);
echo json_encode(['status' => 'success']);

Signature Security

CironetPay uses two separate secrets — do not confuse them:

Technical Architecture

Built with PHP 8.1+ on a standard LAMP stack. Hosted at pay.cironetug.com.

Component Overview

Database Schema

transactions

The central ledger. Every payment attempt is recorded here.

CREATE TABLE transactions (
    id               INT AUTO_INCREMENT PRIMARY KEY,
    transaction_ref  VARCHAR(100) UNIQUE NOT NULL,
    external_id      VARCHAR(100),       -- the Node's reference
    node_source      VARCHAR(50),        -- e.g. 'messaging_node'
    merchant_id      INT,
    provider         VARCHAR(50),        -- internal only
    amount           DECIMAL(20,2),
    currency         VARCHAR(10),
    payer_phone      VARCHAR(30),
    payer_email      VARCHAR(150),
    callback_url     VARCHAR(500),       -- Node's callback endpoint
    status           ENUM('Pending','Completed','Failed','Cancelled'),
    provider_reference VARCHAR(255),
    raw_log          JSON,
    created_at       TIMESTAMP DEFAULT CURRENT_TIMESTAMP
);

merchant_webhooks

Registered webhook URLs for merchant portal accounts.

CREATE TABLE merchant_webhooks (
    id          INT AUTO_INCREMENT PRIMARY KEY,
    merchant_id INT NOT NULL,
    url         VARCHAR(500) NOT NULL,
    secret      VARCHAR(255),
    status      ENUM('active','inactive') DEFAULT 'active'
);

Configuration

All credentials live in .env. Never commit this file to version control.

Node Onboarding

Troubleshooting

Roadmap

• Admin Dashboard: Visual interface for cross-node transaction management and reporting.
• Per-Node Billing: Automated commission statements for client nodes.
• Refunds API: Unified endpoint for initiating refunds.
• Card Payments: Visa/Mastercard acceptance for international payers.
• Bank Direct: Direct Stanbic and Equity bank transfer integrations.