Принимайте платежи через ZainCash (Payment Gateway v2) на сайте на Node.js, не изучая сначала весь API. Клиент из набора делает следующее:

• Получает токен доступа.

• Создает каждый платеж с новым externalReferenceId.

• Перенаправляет покупателя на redirectUrl, который возвращает ZainCash.

• Проверяет токены редиректа и вебхуков с помощью вашего API-ключа. Принимается только HS256, поэтому токены с alg "none", другим алгоритмом или измененной полезной нагрузкой отклоняются.

• Находит транзакцию.

• Отправляет запросы на полный или частичный reverse (возвраты ZainCash вашим покупателям).

Он защищает от ошибок, которые стоят денег:

• Каждое событие вебхука обрабатывается один раз для каждого eventId.

• Заказ становится оплаченным, только когда сумма, валюта и референс совпадают с ним.

• Если ZainCash отвечает на запрос reverse кодом HTTP 200 и статусом FAILED, клиент выбрасывает ошибку.

• Причины длиннее 44 символов и дробные суммы в динарах отклоняются еще до отправки.

• Сообщения об ошибках никогда не содержат ваших секретов.

Инструмент возвратов прямо сообщает, когда результат неизвестен, например после тайм-аута. Затем он направляет вас к npm run reversals, а не позволяет отправить запрос дважды. Ожидающий запрос reverse резервирует свою сумму.

Попробуйте за одну минуту с помощью npm run demo. Команда запускает локальный мок ZainCash (не сам ZainCash) и пример магазина на Express, так что вы можете пройти платеж, редирект и вебхук еще до получения учетных данных. Когда у вас появятся тестовые учетные данные, npm run uat проверит их в тестовой среде ZainCash и создаст тестовый платеж.

Все описанное выше покрыто тестами, которые запускаются командой npm test без сети и без учетных данных. Они охватывают проверку токенов, клиент, обработку событий, хранилища, пример магазина от начала до конца и инструменты командной строки. Протестировано на Node.js 24 (требуется Node.js 22 или новее). У библиотеки нет зависимостей; пример магазина использует Express 5.3.0. Статический анализ на типичные ошибки интеграции ZainCash не выявил замечаний.

Не входит в набор: выплаты наличными (массовые выплаты). Запрос статуса и список возвратов возвращаются в том виде, в каком их отправляет ZainCash. Названия полей соответствуют публичной документации для разработчиков ZainCash по состоянию на ноябрь 2026 года. Этот набор независимый, он не создан и не поддерживается ZainCash.

Как использовать:

1. Распакуйте набор.

2. Выполните npm install, затем npm run demo и откройте http://localhost:3000.

3. Чтобы использовать его в своем приложении, скопируйте lib/zaincash.js и lib/events.js в свой проект.

4. Следуйте README.md (на английском) или README.ar.md (на арабском): там описаны тестовая среда, чек-лист запуска в продакшн и примеры для Express и Next.js.

Что в ZIP-архиве (29 файлов):

• lib/ (3 файла): клиент и проверка токенов, обработка событий, хранилища

• mock/ (1 файл): локальный мок ZainCash

• example/ (5 файлов): магазин на Express

• scripts/ (5 файлов): демо, проверка UAT, возврат, список возвратов, поиск транзакции

• test/ (8 файлов): тесты и вспомогательные модули

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