v3.0.0 · Unified Gateway

Developer Documentation

Universal Callback Ingestion, Real-Time Reconciliation, and Event Replay Infrastructure for African Payment Systems.

Certified

ParsePesa V3 Certification Suite Passed Successfully

ParsePesa V3 passed 33 automated gateway, reconciliation, billing, sandbox, and chaos tests across 9 provider adapters and Custom JSON mapping.

Unified Callback & Event Normalization Flow

1. Payment ProvidersM-Pesa / Pesapal / Card

➔

2. ParsePesa IngestionUnified Event Normalization

➔

3. Your Outbox APINormalized JSON Webhooks

01.Getting Started

Create Account

Get API Key

Test or Live key.

Start Parsing

One SDK. JSON.

02.Authentication

Include your API key as a Bearer token in every request.

Authorization: Bearer pp_live_your_key

03.API Reference: Single Parse

POST

https://api.parsepesa.nexoracreatives.co.ke/v1/parse

Request Body

{
  "raw_text": "Confirmed. Ksh500...",
  "sender_id": "MPESA"
}

Response

{
  "success": true,
  "parser_version": "v2.0.0",
  "rule_source": "deterministic",
  "confidence": 1.0,
  "processing_time_ms": 2,
  "data": {
    "event_id": "evt_QDF56RTYU1",
    "source": "mpesa",
    "channel": "sms",
    "event_type": "money.sent",
    "event_name": "Money Sent",
    "amount": 500.0,
    "currency": "KES",
    "counterparty": "NEWTON MWANGI",
    "timestamp": "2026-06-12T17:45:32.000Z",
    "metadata": {
      "transaction_id": "QDF56RTYU1",
      "balance": 12450.5,
      "fee": 0.0,
      "status": "completed"
    }
  }
}

// npm install parsepesa
const ParsePesa = require('parsepesa');
const client = new ParsePesa('YOUR_API_KEY');

const res = await client.parse('Confirmed. Ksh500.00 sent to...');
console.log(res.data.amount); // 500

04.Batch Parsing

Process up to 50 messages in a single HTTP request.

POST

https://api.parsepesa.nexoracreatives.co.ke/v1/parse/batch

curl -X POST https://api.parsepesa.nexoracreatives.co.ke/v1/parse/batch \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '[
    {"raw_text": "Confirmed. Ksh500.00 sent to..."},
    {"raw_text": "LKN987ZXC Confirmed. Ksh1200.00..."}
  ]'

05.Supported Transaction Types

Send Money

Till Payments

Paybill

Card Transactions

Bank-to-Mpesa

Merchant Transfers

Loan Receipts

Loan Repayments

Withdrawals

Airtime Purchase

Airtime Transfers

Incoming Money

Agent Deposits

Balance Info

Fuliza / M-Shwari

Reversals

06.Engine Robustness

Flexible IDs

Supports M-Pesa transaction IDs from 8 to 12 characters automatically.

AI Smart Fallback

Messages that don't match standard regex patterns are processed by our Gemini-powered engine.

07.Webhooks (Outbound)

Verify requests using the X-ParsePesa-Signature and X-ParsePesa-Timestamp headers to protect against replay attacks. Signature is computed using HMAC-SHA256 on the concatenated string timestamp + '.' + body.

Node.js / JavaScript

const timestamp = headers['x-parsepesa-timestamp'];
const signature = headers['x-parsepesa-signature'];
const signedPayload = `${timestamp}.${JSON.stringify(payload)}`;

const hmac = crypto
  .createHmac('sha256', secret)
  .update(signedPayload)
  .digest('hex');
const isValid = hmac === signature;

Python

import hmac, hashlib
timestamp = headers.get('X-ParsePesa-Timestamp')
signature = headers.get('X-ParsePesa-Signature')
signed_payload = f"{timestamp}.{payload_body}"

digest = hmac.new(
  secret.encode(), 
  signed_payload.encode(), 
  hashlib.sha256
).hexdigest()
is_valid = digest == signature

07b.Daraja Secure Proxy (Inbound)

Point Safaricom to ParsePesa. We handle the 1-second timeout and forward structured JSON to you.

Forwarded Payload Format

{
  "event": "daraja.transaction",
  "timestamp": "2026-06-12T17:45:32.000Z",
  "data": {
    "transactionId": "RKA123XYZ",
    "type": "stk_push",
    "amount": 1500.0,
    "currency": "KES",
    "counterparty": "254712345678",
    "phoneNumber": "254712345678",
    "timestamp": "2026-06-12T17:45:32.000Z"
  }
}

PHP Verification

$sig = $_SERVER['HTTP_X_PARSEPESA_SIGNATURE'];
$computed = hash_hmac('sha256', $body, $secret);
if ($sig === $computed) { ... }

Auto-Validation

ParsePesa sends the ResultCode: 0 response to Safaricom immediately.

08.Merchant Support

ParsePesa handles the Confirmed.on merchant format automatically — extracting customer name and phone from incoming payment notifications.

09.Pricing Plans

Every user starts on the Developer plan for free. Staging and development sandboxes are always free of charge.

Developer (Free)

500 parses included · 25 AI fallbacks included · KES 0.50 overage

KES 0/mo

Startup

10,000 parses included · 1,000 AI fallbacks included · KES 0.35 overage

KES 2,500/mo

Growth

75,000 parses included · 10,000 AI fallbacks included · KES 0.20 overage

KES 15,000/mo

Business

300,000 parses included · 50,000 AI fallbacks included · KES 0.12 overage

KES 45,000/mo

Enterprise

Custom parses · Custom bounds · From KES 0.05

Custom

10.Official SDKs

Flutter

flutter pub add parsepesa

Node.js

npm install parsepesa

Python

pip install parsepesa

PHP

composer require parsepesa/php