Introducing `whish-pay`: A Better Developer Experience for Whish Money Payments

Integrating a payment gateway should not mean filling your application with repetitive HTTP requests, loosely typed payloads, duplicated validation logic, and payment-specific code spread across multiple parts of your backend.

That is the problem `whish-pay` was created to solve.

`whish-pay` is an open-source TypeScript SDK that provides developers with a simple and structured way to integrate the Whish Money payment gateway into Node.js applications.

It is lightweight, type-safe, framework-agnostic, and built with zero runtime dependencies.

Instead of making every development team build its Whish Money integration from scratch, `whish-pay` provides a reusable foundation around the most important parts of the payment lifecycle.

Why `whish-pay`?

Payment integrations often begin simply.

Send a request.
Receive a payment URL.
Redirect the customer.
Wait for the payment result.

But production systems quickly become more complicated.

Developers need to think about credentials, validation, payment identifiers, callback handling, failed requests, network errors, payment verification, currency validation, duplicate callbacks, and different application frameworks.

`whish-pay` brings these responsibilities together behind a clean TypeScript API.

> The goal is simple:
> Make integrating Whish Money feel like using a modern Node.js SDK rather than manually building and maintaining a payment integration every time.

Built for Modern TypeScript Applications

TypeScript is at the center of the package.

Developers get strongly typed:

configuration, payment requests, responses, currencies, payment statuses, and errors.

This makes the integration easier to understand while also helping catch mistakes during development instead of discovering them after deployment.

The SDK can be used with different Node.js backend architectures, including applications built with Next.js, Express, Fastify, Hono, and other server-side Node.js environments.

It also ships with both ESM and CommonJS support, making it easier to integrate into modern as well as existing Node.js projects.

Zero Runtime Dependencies

One of the most interesting decisions behind `whish-pay` is its zero-runtime-dependency architecture.

The package takes advantage of capabilities already available in modern versions of Node.js instead of adding unnecessary third-party libraries.

That keeps the SDK focused and lightweight while reducing the number of external packages that become part of the application's payment path.

For developers, this means a smaller and more predictable integration surface.

A Simple Payment API

At the center of the SDK is `WhishClient`.

Through a single client, applications can handle the essential operations required by a Whish Money integration.

Developers can create payments, check payment status, retrieve applicable rates, inspect the available balance, generate external payment identifiers, validate received payment amounts, and parse callback information.

The library currently supports payments using USD, LBP, and AED.

The result is an API that stays small enough to understand quickly while still covering the major pieces of a real payment workflow.

Payment Security Is More Than a Success Page

One of the most important principles in `whish-pay` is that a redirect is not proof of payment.

A customer reaching a success URL should never be enough for an application to mark an order as paid.

Instead, `whish-pay` encourages a server-side verification flow.

After receiving a payment callback, the backend retrieves the authoritative payment status, confirms that the transaction succeeded, verifies the amount and currency against the application's own order data, and only then completes the order.

Applications should also process payment confirmation idempotently so that receiving the same callback more than once cannot accidentally process an order twice.

This distinction is extremely important when building payment systems.

> Callbacks are signals.
> Verified server-side payment status is the source of truth.

A Clean Payment Flow

A typical integration using `whish-pay` looks like this:

1. The application creates an order in its own database.
2. A unique external payment ID is associated with that order.
3. The backend asks Whish Money to create the payment through `whish-pay`.
4. Whish returns a collection URL.
5. The customer is redirected to the payment page.
6. After the customer completes or cancels the payment, the backend receives the appropriate callback.
7. The application independently checks the payment status through the SDK.
8. The amount, currency, and order information are verified.
9. Only after successful verification is the order marked as paid.

This keeps the application's own database at the center of the business workflow while Whish handles the payment transaction.

Designed for the Backend

`whish-pay` is intentionally designed as a server-side library.

Sensitive credentials such as the Whish channel and secret should remain inside the backend environment and must never be exposed to browser code.

That means payment creation and verification belong inside server routes, API endpoints, server actions, or backend services.

The repository also provides integration examples for popular Node.js environments, helping developers understand not only how to call the SDK but where payment logic should live inside a real application.

Errors Developers Can Actually Handle

Payment APIs can fail for very different reasons.

An invalid request is not the same as a network timeout.

A network problem is not the same as an API error.

And an API error is not necessarily the same as a payment request being rejected.

`whish-pay` provides dedicated error types so applications can respond appropriately to configuration, validation, network, API, and parsing problems.

That gives developers much more control over logging, retries, API responses, and the experience shown to users.

Open Source and Built to Be Extended

`whish-pay` is more than a wrapper around an HTTP endpoint.

It represents an attempt to create a reusable developer layer around Whish Money integration for the Node.js and TypeScript ecosystem.

Because the project is open source, developers can inspect the implementation, study the examples, report issues, suggest improvements, and contribute as the package evolves.

For developers building e-commerce platforms, SaaS products, booking systems, delivery applications, marketplaces, or other applications that need Whish Money payments, the SDK can provide a cleaner starting point than rebuilding the same infrastructure from the ground up.

Getting Started

Installing the package is intentionally straightforward:

```bash
npm install whish-pay
```

From there, configure `WhishClient` using your server-side Whish credentials and website URL, create payments from your backend, and verify their final status before updating your application's order state.

The project includes documentation covering installation, configuration, payment creation, status verification, callbacks, error handling, framework examples, TypeScript types, testing, and production security considerations.

An Important Note

`whish-pay` is an unofficial community-created package.

It is not affiliated with, endorsed by, or maintained by Whish Money.

Developers planning to use the package in production should always verify API endpoints, authentication requirements, payload formats, and other integration details against the official merchant documentation provided to them by Whish Money.

Building Better Local Developer Tools

Good developer tools remove repeated work.

They turn low-level integration details into clear interfaces, establish safer implementation patterns, and allow developers to spend more time building their actual product.

That is the idea behind `whish-pay`.

A focused TypeScript SDK.
Zero runtime dependencies.
A framework-agnostic architecture.
A security-conscious payment flow.
And a simpler way to bring Whish Money payments into Node.js applications.

`whish-pay` is now available as an open-source project on GitHub.

Explore the project, try it in your next Node.js application, and contribute to its future development.

[Explore `whish-pay` on GitHub](https://github.com/Mohammad-AlBaker-Zaytoun/whish-pay)