npm package: @lukasbryla/gopay-client
Description: Strongly typed client and thin wrapper around the GoPay REST API for Node.js
Author: Lukas Bryla
Latest version: 1.0.1

# @lukasbryla/gopay-client

**Strongly typed client and thin wrapper around the GoPay REST API for modern JavaScript runtimes.**

A lightweight, zero-dependency library that uses only TypeScript and the native `fetch` API.  
No runtime bloat and no dependencies, just a safe and predictable way to integrate gopay.com payment rest API.

[![npm version](https://img.shields.io/npm/v/@lukasbryla/gopay-client.svg)](https://www.npmjs.com/package/@lukasbryla/gopay-client) [![License](https://img.shields.io/github/license/lukas-bryla/gopay-client.svg)](LICENSE)
![npm bundle size](https://img.shields.io/bundlephobia/minzip/@lukasbryla/gopay-client) ![Contributions welcome](https://img.shields.io/badge/contributions-welcome-brightgreen.svg)

---

## 📌Why does this package exist?

This client was designed with clear priorities: zero dependencies and keeping the code small.

Payment integrations are often wrapped in layers of third-party libraries, which introduces security risks
and maintenance overheads.  
Here we take the opposite approach — TypeScript for type safety, the native
`fetch` API for HTTP, and nothing else.

Another intentional decision is to omit runtime validation. Instead, request and response shapes are
expressed through TypeScript interfaces . This keeps the library small and predictable, while still catching
mistakes during development. If you need stricter runtime checks, they can easily be added on top by the
consumer without forcing overhead on everyone else.

---

## ✨ Features

- Full TypeScript support with strict typings for requests and responses.
- Dependency-free: built only on the native `fetch` API.
- Supports payments, refunds, preauthorizations, and recurrences.
- Sandbox-ready for testing and development.
- Works in Node.js, Bun, and Deno.
- Avoids runtime shims and is shipped as a clean dual build (CJS + ESM)

## ⚡ Compatibility

This package is shipped as dual build (CJS + ESM):

- CommonJS:
  ```js
  const { GoPayClient } = require("@lukasbryla/gopay-client");
  ```
- ES Modules:

  ```js
  import { GoPayClient } from "@lukasbryla/gopay-client";
  ```

  Both environments are supported out of the box — no transpilers, no shims.

## 📦 Bundle Size & Tree-Shaking

This library is designed to stay small and efficient:

JavaScript users only get the compiled .js output. No TypeScript files are included at runtime.

TypeScript users benefit from full .d.ts type declarations, but those are used only at compile time and never inflate your production build.

Supports modern bundlers (Vite, Webpack, Rollup, esbuild) with tree-shaking, so unused exports are stripped out automatically.

---

## 📦 Installation

```bash
npm install @lukasbryla/gopay-client
```

---

## 🚀 Usage

Using the client is intentionally simple.  
No factories, no boilerplate, no “magical” wrappers — just create an instance and call the API.

```ts
import { GoPayClient } from "@lukasbryla/gopay-client";
import type { PaymentRequest } from "@lukasbryla/gopay-client/types";

// Initialize with your credentials
const gopay = new GoPayClient(
  process.env.GOPAY_CLIENT_ID!,
  process.env.GOPAY_CLIENT_SECRET!,
  true, // sandbox mode
);

// Create a new payment
const payment: PaymentRequest = {
  amount: 1000,
  currency: "CZK",
  order_number: "ORDER-123",
  target: { type: "ACCOUNT", goid: 1234567890 },
  order_description: "Test order",
  callback: {
    return_url: "https://example.com/return",
    notification_url: "https://example.com/notify",
  },
};

const res = await gopay.createPayment(payment);

console.log("Redirect the customer to:", res.gw_url);

// Later, check the status
const status = await gopay.getPaymentStatus(res.id);
console.log("Payment state:", status.state);
```

That’s it. No transitive dependencies, no runtime interference.  
Just a strongly typed, predictable API that does exactly what you expect.

---

## 📚 API

**IMPLEMENTS THE FOLLOWING ROUTES FROM GOPAY REST API:**  
[![CZ](https://flagcdn.com/w20/cz.png) Czech documentation](https://doc.gopay.cz)  
[![EN](https://flagcdn.com/w20/gb.png) English documentation](https://doc.gopay.com)

- **createPayment(data: PaymentRequest): Promise<PaymentResponse>**  
  Creates a new payment. Supports one-time, preauthorized, and recurring payments.

- **getPaymentStatus(id: string): Promise<PaymentResponse>**  
  Retrieves the current status of a payment by its ID.

- **refundPayment(id: string, data: RefundRequest): Promise<RefundResponse>**  
  Refunds a payment in full or partially.

- **listRefunds(id: string): Promise<RefundHistoryResponse[]>**  
  Lists the refund history of a payment.

- **captureAuthorization(id: string): Promise<ActionResponse>**  
  Captures a preauthorized payment in full.

- **partialAuthorization(id: string, data: { amount: number; items?: Item[] }): Promise<ActionResponse>**  
  Captures part of a preauthorized payment.

- **voidAuthorization(id: string): Promise<ActionResponse>**  
  Voids a preauthorization.

- **createRecurrence(id: string, data: RecurrenceRequest): Promise<PaymentResponse>**  
  Creates a new payment from an existing recurring payment.

- **voidRecurrence(id: string): Promise<ActionResponse>**  
  Voids a recurring payment.

---

## 🧪 Testing

The project uses two test suites:

- **Unit tests**: Run without hitting GoPay, mock fetch to verify headers, bodies, and error handling.
- **Integration tests**: Run against GoPay’s sandbox API with real credentials. Requires the tester to handle the gw_url (Gateway URL where the customer should be redirected) to simulate the customer using [testing payment cards](https://help.gopay.com/en/knowledge-base/integration-of-payment-gateway/integration-of-payment-gateway-1/testing-payments-in-the-sandbox?pure= "Testing payment cards").

### Running tests

```bash
# Unit tests
npm run test:unit

# Integration tests (requires sandbox keys)
GOPAY_CLIENT_ID=xxx GOPAY_CLIENT_SECRET=yyy npm run test:integration
```

For real-world testing, see [`src/examples/integration.ts`](https://github.com/lukas-bryla/gopay-client/blob/main/src/examples/integration.ts).  
It demonstrates:

- Creating a payment in the **GoPay sandbox**
- Printing the `gw_url` where the customer will be redirected
- Querying the payment status

```bash
# Set sandbox credentials
export GOPAY_CLIENT_ID=your-client-id
export GOPAY_CLIENT_SECRET=your-secre

# Run the script
ts-node examples/integration.ts
```

⚠️ Note: This is a manual test. The customer must complete the payment in the sandbox flow for the status to change.

---

## 🛡 Security

Keep your Client ID and Secret safe, do not expose them in frontend code.

Running your application in a Node.js environment means your API keys will live in process memory. If a malicious or compromised dependency gains access, it could potentially read them. To reduce this risk, consider isolating payment handling into a dedicated worker or service, so sensitive credentials are kept separate from the rest of your codebase.

---

## 📖 License

MIT © 2025

---

## ⚠️ Disclaimer

This project is an independent, community-maintained client.  
It is **not affiliated with or endorsed by GoPay**.  
For official GoPay resources, see the [documentation](https://doc.gopay.com).