The Payment Engine for African Commerce

Connekt Pay is a payment orchestration API built by Kufrashe Technologies. It wraps Paynow Zimbabwe so developers and Connekt platforms can accept EcoCash, OneMoney, or hosted Paynow checkout without integrating Paynow directly in every app.

Each merchant gets an API key, transaction ledger, signed webhooks (RACP), and settlement tracking for a transparent revenue split: 98% merchant share / 2% platform fee (default; set via PLATFORM_FEE_PERCENT).

What Connekt Pay is NOT

Connekt Pay is not a bank, e-money issuer, or licensed payment institution. We do not hold customer deposits as a bank would. Funds from payers are collected through Paynow into the platform's Paynow merchant account operated by Kufrashe Technologies.

• We provide API + ledger + webhooks, not a stored-value wallet for end users.
• Merchant payouts (your share, e.g. 98%) are manual disbursements to the EcoCash/OneMoney number on your dashboard after KYC and the T+7 settlement window.
• The platform fee (default 2%) is a toll for infrastructure (API, compliance tracking, support)—not interest or banking revenue.

Why use Connekt Pay instead of Paynow directly?

You still need Paynow-capable flows on the payer side. Connekt Pay removes repeated boilerplate for Connekt ecosystem apps and third-party developers.

Money flow: who pays whom

1. Payer (customer) approves EcoCash/OneMoney on their phone (or pays on Paynow web).
2. Paynow settles to the platform Paynow merchant account (Kufrashe).
3. Connekt Pay records: merchant (you), external_id, amount, fees, status.
4. On PAID, your webhook receives merchant_share and platform_fee (e.g. 98% / 2% at default settings).
5. After KYC + T+7, operations pays your share to payout_phone on your dashboard (EcoCash/OneMoney).

Register payout details under Dashboard → Payout profile. Set REQUIRE_KYC_FOR_PAYMENTS=true in production to block API payments until KYC is verified.

Who is Connekt Pay for?

Connekt Pay is designed to serve three primary "Actors" in the digital economy:

Architecture: The Store Bridge

Connekt Pay operates as a "Settlement Layer" or "Bridge". It doesn't just transfer money; it orchestrates value based on the **RACP (Robust Agent Communication Protocol)** — originally designed for AI & ML Agents that communicate with Connekt Social and its related entities.

• Decoupled Logic: Your app handles the UX; we handle the rails.
• Asynchronous Events: We notify you of status changes via cryptographically signed webhooks.
• Automated Split: Revenue is split per transaction (default 98/2) — developer earnings are calculated and held for settlement.

Precision Authentication

Identity is core to multi-tenancy. Every request must be identified by a platform "Actor" key.

Usage

Include your primary SECRET_KEY in the X-Connekt-Pay-Key header.

Keys are generated automatically upon Merchant Registration.

Authentication States

Initiating Payments

Initiate a transaction for any "external_id" (like an Order ID) on your platform.

Request Schema

POST /v1/payments
{
  "amount": 10.00,
  "currency": "USD",
  "payment_method": "ecocash",
  "phone": "0771234567",
  "payer_email": "[email protected]",
  "external_id": "AD_UNIT_001",
  "callback_url": "https://yourapp.com/webhooks/connekt-pay"
}

Mobile response (ecocash / onemoney)

{
  "success": true,
  "reference": "a1b2c3d4e5f6",
  "status": "PENDING",
  "poll_url": "https://www.paynow.co.zw/Interface/CheckPayment/?guid=...",
  "instructions": "Check your phone for the mobile money PIN prompt."
}

No redirect_url for mobile methods—the customer approves on their phone.

Poll for status

GET /v1/payments/<reference>?refresh=true or POST /v1/payments/<reference>/poll while waiting for PIN approval.

Transaction statuses

• CREATED — Record created.
• PENDING — Sent to Paynow; awaiting customer action.
• PAID — Confirmed. Webhook sent with merchant_share / platform_fee.
• FAILED — Cancelled or declined.

Common mistakes

• Using payment_method: "web" when you want a phone PIN prompt.
• Omitting phone for EcoCash/OneMoney.
• Expecting Connekt Pay to read the SIM—pass phone from your app.
• Confusing phone (payer) with payout_phone (merchant settlement wallet on dashboard).

Webhook Orchestration (RACP)

Payment events follow the **Robust Agent Communication Protocol (RACP)** standard, ensuring secure, verifiable event delivery between autonomous agents, platforms, and our settlement layer.

Standard Payload

{
  "event": "payment.completed",
  "data": {
    "reference": "tx_abc123",
    "status": "PAID",
    "external_id": "AD_UNIT_001"
  }
}

Platform Agnostic Deployment

Connekt Pay is built for maximum portability across Linux, Docker, or any Python 3.10+ environment.

Signature Security (Precision)

Integrity is maintained via HMAC-SHA256. Every webhook includes an X-Connekt-Signature header.

Python Implementation

import hmac, hashlib

def verify_webhook(payload, secret_key, received_sig):
    # payload is the raw request body bytes
    computed_sig = hmac.new(
        secret_key.encode(), 
        payload, 
        hashlib.sha256
    ).hexdigest()
            

Signature Verification (RACP)

To ensure notifications are authentic, Connekt Pay signs every webhook payload using your RACP Secret. You should verify this signature in your callback handler.

import hmac
import hashlib

def verify_signature(data, signature, racp_secret):
    # Secret from your Dashboard
    key = racp_secret.encode('utf-8')
    payload = data.encode('utf-8')
    
    expected = hmac.new(key, payload, hashlib.sha256).hexdigest()
    return hmac.compare_digest(expected, signature)

const crypto = require('crypto');

function verifySignature(payload, signature, racpSecret) {
  const hmac = crypto.createHmac('sha256', racpSecret);
  const digest = hmac.update(payload).digest('hex');
  return crypto.timingSafeEqual(Buffer.from(digest), Buffer.from(signature));
}

Always verify signatures before processing any state changes in your database.

Mock Mode

For development, set PAYNOW_MODE=MOCK. This creates a simulator environment where you can trigger success events manually to test your business logic transitions.

Settlement & KYC

When a payment is PAID, Connekt Pay computes:

• merchant_share — e.g. 98% of gross (100 − PLATFORM_FEE_PERCENT)
• platform_fee — default 2% platform toll
• settlement_status — UNSETTLED until operations pays your dashboard payout_phone

KYC: Submit legal name + payout wallet in the dashboard. Status: unverified → submitted → verified. Production can require verification before accepting payments.

Payout cycle: T+7 (default) manual disbursement to EcoCash/OneMoney—not instant automatic transfer.