GoPay SDK

npm: gopay-sdk

Modern, strongly typed TypeScript client for the GoPay REST API.

✨ Why this SDK

• Full typed API client for GoPay payment operations
• OAuth2 client-credentials token management with caching
• Pluggable HttpTransport and TokenCache abstractions
• ESM + CJS builds with TypeScript declarations

📦 Installation

npm install gopay-sdk

Targets Node.js 18+ (engines in package.json). Pin a stricter range in your app if you need to.

🧩 Optional subpath imports

For narrower imports (e.g. custom HttpTransport without the full barrel):

| Subpath | Exports | |---------|---------| | gopay-sdk/errors | GoPayApiError, GoPayConfigError | | gopay-sdk/http | HttpTransport and HTTP-related types | | gopay-sdk/auth | TokenCache, InMemoryTokenCache | | gopay-sdk/config | Client config types |

import type { HttpTransport } from 'gopay-sdk/http';
import { GoPayApiError } from 'gopay-sdk/errors';

🚀 Quick start

import { Currency, createGoPayClient } from 'gopay-sdk';

const client = createGoPayClient({
  goid: 8123456789,
  clientId: process.env.GOPAY_CLIENT_ID!,
  clientSecret: process.env.GOPAY_CLIENT_SECRET!,
  gatewayUrl: 'https://gw.sandbox.gopay.com/api',
});

const payment = await client.createPayment({
  amount: 10000,
  currency: Currency.CZK,
  order_number: `ORDER-${Date.now()}`,
  payer: {
    contact: {
      email: '[email protected]',
    },
  },
  callback: {
    return_url: 'https://example.com/return',
    notification_url: 'https://example.com/notify',
  },
});

console.log(payment.id, payment.gw_url);

🌍 Environment URLs

| Environment | gatewayUrl | |-------------|----------------| | Sandbox | https://gw.sandbox.gopay.com/api | | Production | https://gate.gopay.cz/api |

gatewayUrl is normalized and enforced to end with /api.

📋 Core client methods

| SDK method | HTTP endpoint | | ---------- | --------------- | | createPayment(payment) | POST /payments/payment | | getPayment(id) | GET /payments/payment/{id} | | refundPayment(id, { amount }) | POST /payments/payment/{id}/refund | | getPaymentRefunds(id) | GET /payments/payment/{id}/refunds | | createRecurrence(id, payload) | POST /payments/payment/{id}/create-recurrence | | voidRecurrence(id) | POST /payments/payment/{id}/void-recurrence | | captureAuthorization(id) | POST /payments/payment/{id}/capture | | captureAuthorizationPartial(id, payload) | POST /payments/payment/{id}/capture | | voidAuthorization(id) | POST /payments/payment/{id}/void-authorization | | getCardDetails(cardId) | GET /payments/cards/{card_id} | | deleteCard(cardId) | DELETE /payments/cards/{card_id} | | getPaymentInstruments(goid, currency) | GET /eshops/eshop/{goid}/payment-instruments/{currency} | | getPaymentInstrumentsAll(goid) | GET /eshops/eshop/{goid}/payment-instruments | | getAccountStatement(payload) | POST /accounts/account-statement | | getEmbedJsUrl() | Embed JS URL helper |

⚠️ Error handling

All non-2xx API responses throw GoPayApiError.

import { GoPayApiError } from 'gopay-sdk';

try {
  await client.getPayment(12345);
} catch (error) {
  if (error instanceof GoPayApiError) {
    console.error(error.status, error.endpoint, error.errors);
  }
}

📚 Documentation

Guides and API reference: docs.zabcik.me

📄 License

MIT