Nimm Zahlungen mit ZainCash (Payment Gateway v2) auf einer Node.js-Website entgegen, ohne vorher die komplette API durchzulesen. Der Client des Kits erledigt Folgendes:

• Er holt das Access Token.

• Er erstellt jede Zahlung mit einer neuen externalReferenceId.

• Er leitet den Kunden an die redirectUrl weiter, die ZainCash zurückgibt.

• Er prüft die Redirect- und Webhook-Tokens mit deinem API-Schlüssel. Nur HS256 wird akzeptiert, daher werden Tokens mit alg "none", einem anderen Algorithmus oder verändertem Payload abgelehnt.

• Er ruft eine Transaktion ab.

• Er sendet vollständige oder teilweise Reverse-Anfragen (ZainCash-Rückerstattungen an deine Kunden).

Er schützt dich vor den Fehlern, die Geld kosten:

• Jedes Webhook-Event wird pro eventId nur einmal verarbeitet.

• Eine Bestellung gilt erst als bezahlt, wenn Betrag, Währung und Referenz übereinstimmen.

• Wenn ZainCash eine Reverse-Anfrage mit HTTP 200 und Status FAILED beantwortet, löst der Client einen Fehler aus.

• Begründungen mit mehr als 44 Zeichen und Dinar-Beträge mit Nachkommastellen werden abgelehnt, bevor überhaupt etwas gesendet wird.

• Fehlermeldungen enthalten niemals deine Geheimnisse.

Das Reverse-Tool sagt dir klar, wenn das Ergebnis unbekannt ist, etwa nach einem Timeout. Dann verweist es dich auf npm run reversals, statt dich die Anfrage doppelt senden zu lassen. Eine ausstehende Reverse-Anfrage hält ihren Betrag zurück.

Probiere es in einer Minute mit npm run demo aus. Damit startest du einen lokalen Mock von ZainCash (nicht ZainCash selbst) und den Beispiel-Shop mit Express, sodass du Zahlung, Redirect und Webhook durchklicken kannst, bevor du Zugangsdaten hast. Sobald du Test-Zugangsdaten hast, prüft npm run uat sie gegen die Testumgebung von ZainCash und erstellt eine Testzahlung.

Alles oben Genannte ist durch Tests abgedeckt, die mit npm test laufen, ganz ohne Netzwerk und ohne Zugangsdaten. Sie decken die Token-Prüfungen, den Client, die Event-Verarbeitung, die Stores, den Beispiel-Shop von Anfang bis Ende und die Kommandozeilen-Tools ab. Getestet mit Node.js 24 (erfordert Node.js 22 oder neuer). Die Bibliothek hat keine Abhängigkeiten, der Beispiel-Shop nutzt Express 5.3.0. Ein statischer Scan auf typische Fehler bei der ZainCash-Integration meldet keine Befunde.

Nicht enthalten: Bargeldauszahlung (Sammelauszahlungen). Abfrage und Liste der Reversals werden so zurückgegeben, wie ZainCash sie sendet. Die Feldnamen folgen der öffentlichen Entwicklerdokumentation von ZainCash mit Stand November 2026. Dieses Kit ist unabhängig und wird weder von ZainCash erstellt noch unterstützt.

So verwendest du es:

1. Entpacke das Kit.

2. Führe npm install aus, dann npm run demo, und öffne http://localhost:3000.

3. Um es in deiner eigenen App zu nutzen, kopiere lib/zaincash.js und lib/events.js in dein Projekt.

4. Folge README.md (Englisch) oder README.ar.md (Arabisch) für die Testumgebung, die Go-live-Checkliste sowie Beispiele für Express und Next.js.

Was im ZIP steckt (29 Dateien):

• lib/ (3 Dateien): Client und Token-Prüfungen, Event-Verarbeitung, Stores

• mock/ (1 Datei): der lokale ZainCash-Mock

• example/ (5 Dateien): der Express-Shop

• scripts/ (5 Dateien): Demo, UAT-Prüfung, Rückerstattung, Reversals, Abfrage

• test/ (8 Dateien): Tests und Hilfsfunktionen

• README.md, README.ar.md, LICENSE.txt, .env.example, .gitignore, package.json, package-lock.json