Take payments with ZainCash (Payment Gateway v2) from a Node.js site without reading the whole API first. The kit's client does the following:

• Gets the access token.

• Creates each payment with a new externalReferenceId.

• Sends the customer to the redirectUrl that ZainCash returns.

• Verifies the redirect and webhook tokens with your API key. Only HS256 is accepted, so tokens with alg "none", another algorithm or a changed payload are refused.

• Looks up a transaction.

• Sends full or partial reverse requests (ZainCash refunds to your customers).

It guards against the mistakes that cost money:

• Each webhook event is processed once per eventId.

• An order becomes paid only when the amount, currency and reference match it.

• When ZainCash answers a reverse request with HTTP 200 and status FAILED, the client raises an error.

• Reasons longer than 44 characters and decimal dinar amounts are refused before anything is sent.

• Error messages never contain your secrets.

The reverse tool tells you plainly when the outcome is unknown, for example after a timeout. It then points you to npm run reversals instead of letting you send it twice. A pending reverse request holds back its amount.

Try it in one minute with npm run demo. It starts a local mock of ZainCash (not ZainCash) and the example Express shop, so you can click through the payment, the redirect and the webhook before you have credentials. When you have test credentials, npm run uat checks them against ZainCash's test environment and creates a test payment.

Everything above is covered by tests that run with npm test, with no network and no credentials. They cover the token checks, the client, event handling, the stores, the example shop end to end, and the command-line tools. Tested on Node.js 24 (requires Node.js 22 or newer). The library has no dependencies; the example shop uses Express 5.3.0. A static scan for common ZainCash integration mistakes reports no findings.

Not included: cash disbursement (bulk payouts). Inquiry and the list of reversals are returned as ZainCash sends them. Field names follow ZainCash's public developer docs as read in November 2026. This kit is independent and is not made or supported by ZainCash.

How to use:

1. Unzip the kit.

2. Run npm install, then npm run demo, and open http://localhost:3000.

3. To use it in your own app, copy lib/zaincash.js and lib/events.js into your project.

4. Follow README.md (English) or README.ar.md (Arabic) for the test environment, the go-live checklist, and Express and Next.js examples.

What's in the ZIP (29 files):

• lib/ (3 files): the client and token checks, event handling, stores

• mock/ (1 file): the local ZainCash mock

• example/ (5 files): the Express shop

• scripts/ (5 files): demo, UAT check, refund, reversals, lookup

• test/ (8 files): tests and helpers

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