Fintech & Strategy8 min readAugust 10, 2026

Integrating Paynow & EcoCash in Node.js: The Production Payment Architecture Guide

From SHA512 hashing and express webhooks to polling fallbacks and automated reconciliation.

Fintech Architecture Lead

Fintech Architecture Lead

Principal Digital Payments Architect, Natelad Agency

Integrating Paynow & EcoCash in Node.js: The Production Payment Architecture Guide

Executive & Architectural Key Takeaways

  • ✓EcoCash USSD push prompts can take 15-45 seconds for customers to approve on their mobile handsets; never block web server threads synchronously.
  • ✓Always verify Paynow SHA512 hash signatures on webhook callbacks before updating order statuses to PAID.
  • ✓Implement an automated background polling cron job (fallback) for orders that remain PENDING due to lost webhook packets.
  • ✓Support multi-currency pricing (USD, ZiG) with real-time exchange rate tables stored in your database.
Blueprint Table of Contents
  1. 01.The Unique Realities of Digital Payments in Southern Africa
  2. 02.Production Node.js Express Webhook Listener with SHA512 Verification
  3. 03.Automated Polling Fallback Architecture
01

The Unique Realities of Digital Payments in Southern Africa

While Western markets rely almost exclusively on credit cards via Stripe, over 80% of digital transactions in Zimbabwe and regional markets happen via mobile money (EcoCash, OneMoney) and bank transfers.

Integrating with aggregators like Paynow requires handling delayed USSD push notifications, spotty mobile data, and multi-currency transactions smoothly.

02

Production Node.js Express Webhook Listener with SHA512 Verification

Paynow communicates payment confirmations by posting form data to your result URL. Verifying the cryptographic signature ensures bad actors cannot forge payment approvals.

app/api/orders/paynow-webhook/route.ts Webhook Receiver
typescript
import { NextRequest, NextResponse } from 'next/server';
import crypto from 'crypto';

export async function POST(req: NextRequest) {
  const formData = await req.formData();
  const data: Record<string, string> = {};
  formData.forEach((value, key) => {
    data[key] = value.toString();
  });

  const { reference, paynowreference, amount, status, hash } = data;
  const integrationKey = process.env.PAYNOW_INTEGRATION_KEY!;

  // 1. Rebuild message string for SHA512 verification
  const hashString = Object.keys(data)
    .filter(k => k.toLowerCase() !== 'hash')
    .sort()
    .map(k => data[k])
    .join('') + integrationKey;

  const expectedHash = crypto
    .createHash('sha512')
    .update(hashString)
    .digest('hex')
    .toUpperCase();

  if (hash !== expectedHash) {
    return NextResponse.json({ error: 'Invalid hash signature' }, { status: 400 });
  }

  // 2. Idempotent Order State Update
  if (status.toLowerCase() === 'paid') {
    await db.orders.update({
      where: { orderNumber: reference },
      data: { status: 'PAID', gatewayReference: paynowreference }
    });
  }

  return NextResponse.json({ received: true });
}
03

Automated Polling Fallback Architecture

Mobile cellular drops mean 2-3% of webhook notifications never reach your server. A scheduled cron task running every 5 minutes queries the Paynow pollurl for any pending orders older than 10 minutes, ensuring zero dropped revenue.

ARCHITECTURAL TAGS:#Paynow#EcoCash#Payments API#Node.js#Fintech
Fintech Architecture Lead
Written By Lead Architect

Fintech Architecture Lead

Principal Digital Payments Architect at Natelad Agency. Architecting mission-critical digital systems, resilient infrastructure, and security frameworks for enterprises worldwide.

Consult Architect →
Engineering Consultation

Implement this architecture with Natelad’s dedicated engineering pods.

Book a technical discovery session with our lead architects to evaluate your infrastructure, review security posture, or scope a new platform sprint.