@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.

📌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:

  const { GoPayClient } = require("@lukasbryla/gopay-client");

• ES Modules:

  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

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.

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:
Czech documentation
English documentation

• createPayment(data: PaymentRequest): Promise
  Creates a new payment. Supports one-time, preauthorized, and recurring payments.

• getPaymentStatus(id: string): Promise
  Retrieves the current status of a payment by its ID.

• refundPayment(id: string, data: RefundRequest): Promise
  Refunds a payment in full or partially.

• listRefunds(id: string): Promise<RefundHistoryResponse[]>
  Lists the refund history of a payment.

• captureAuthorization(id: string): Promise
  Captures a preauthorized payment in full.

• partialAuthorization(id: string, data: { amount: number; items?: Item[] }): Promise
  Captures part of a preauthorized payment.

• voidAuthorization(id: string): Promise
  Voids a preauthorization.

• createRecurrence(id: string, data: RecurrenceRequest): Promise
  Creates a new payment from an existing recurring payment.

• voidRecurrence(id: string): Promise
  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.

Running tests

# 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.
It demonstrates:

• Creating a payment in the GoPay sandbox
• Printing the gw_url where the customer will be redirected
• Querying the payment status

# 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.