GoPay Wrapper

A modern TypeScript wrapper for the GoPay payment gateway API. This lightweight client makes it easy to integrate GoPay payment processing into your Node.js applications.

Features

• 🚀 Simple, promise-based API
• 📦 TypeScript support with full type definitions
• 🔒 Automatic OAuth2 authentication handling
• ♻️ Automatic token refresh
• 🧩 Modular architecture for easy extension
• ✅ Complete GoPay API coverage

Installation

npm install @glydebyte/gopay-wrapper

Or using yarn:

yarn add @glydebyte/gopay-wrapper

Quick Start

import { GoPay, Currency } from '@glydebyte/gopay-wrapper';

// Initialize the client
const gopay = new GoPay('your-client-id', 'your-client-secret', false); // false for sandbox
await gopay.authenticate();

// Create a payment
const payment = await gopay.payments.createPayment({
  amount: 10000,  // Amount in cents (100.00)
  currency: Currency.CZK,
  order_number: "123456",
  payer: {
    contact: { email: "[email protected]" }
  },
  target: {
    type: "ACCOUNT",
    goid: 1234567890
  },
  callback: {
    return_url: "https://your-shop.com/return",
    notification_url: "https://your-shop.com/notify"
  }
});

console.log(`Payment created with ID: ${payment.id}`);
console.log(`Payment URL: ${payment.gw_url}`);

Environment

The library supports both sandbox and production environments:

// Sandbox environment
const sandboxGoPay = new GoPay('client-id', 'client-secret', false);

// Production environment
const productionGoPay = new GoPay('client-id', 'client-secret', true);

API Documentation

The wrapper provides access to GoPay API operations through the PaymentsModule:

Payments

Create Payment

Creates a new payment. Can be a standard payment, recurring payment, or preauthorized payment.

const payment = await gopay.payments.createPayment({
  amount: 10000,
  currency: Currency.CZK,
  order_number: "ORDER123",
  payer: {
    contact: {
      email: "[email protected]",
      first_name: "John",
      last_name: "Doe"
    },
    allowed_payment_instruments: [PaymentInstrument.PAYMENT_CARD],
    default_payment_instrument: PaymentInstrument.PAYMENT_CARD
  },
  target: {
    type: "ACCOUNT",
    goid: 1234567890
  },
  callback: {
    return_url: "https://example.com/return",
    notification_url: "https://example.com/notify"
  },
  // Optional: for recurring payment
  recurrence: {
    recurrence_cycle: RecurrenceCycle.MONTH,
    recurrence_period: 1,
    recurrence_date_to: "2025-12-31"
  },
  // Optional: for preauthorized payment
  preauthorization: true
});

Inquire Payment

Gets the current status of a payment.

const paymentStatus = await gopay.payments.inquirePayment({
  id: "123456789"
});

console.log(`Payment state: ${paymentStatus.state}`);

Refund Payment

Refunds a payment (full or partial).

// Full refund
const refund = await gopay.payments.refundPayment({
  id: "123456789",
  amount: 10000
});

// Partial refund
const partialRefund = await gopay.payments.refundPayment({
  id: "123456789",
  amount: 5000
});

Get Refunds History

Retrieves the refund history for a payment.

const refundsHistory = await gopay.payments.getRefundsHistory({
  id: "123456789"
});

refundsHistory.forEach(refund => {
  console.log(`Refund ${refund.id}: ${refund.state}, Amount: ${refund.amount}`);
});

Recurring Payments

Create On-Demand Recurring Payment

Creates a new payment based on an existing recurring payment.

const recurringPayment = await gopay.payments.requestPayment({
  id: "123456789", // ID of the parent recurring payment
  amount: 10000,
  currency: Currency.CZK,
  order_number: "ORDER124"
});

Void Recurrence

Cancels a recurring payment.

const voidResult = await gopay.payments.voidRecurrence({
  id: "123456789"
});

Refund and Void

Combines refunding a payment and voiding its recurrence in one operation.

const [refund, voidResult] = await gopay.payments.refundAndVoidPayment({
  id: "123456789",
  amount: 10000
});

Preauthorized Payments

Capture Authorization

Captures the full amount of a preauthorized payment.

const capture = await gopay.payments.captureAuthorization({
  id: "123456789"
});

Capture Authorization Partial

Captures a partial amount of a preauthorized payment.

const partialCapture = await gopay.payments.captureAuthorizationPartial({
  id: "123456789",
  amount: 5000,
  items: [{
    type: "ITEM",
    name: "Test item",
    amount: 5000
  }]
});

Void Authorization

Releases the funds blocked during preauthorization.

const voidAuth = await gopay.payments.voidAuthorization({
  id: "123456789"
});

Payment Cards

Get Card Details

Retrieves details of a stored payment card.

const cardDetails = await gopay.payments.getCardDetails({
  card_id: "9876543210"
});

if (cardDetails.status === "ACTIVE") {
  console.log(`Card: ${cardDetails.card_number}`);
  console.log(`Token: ${cardDetails.card_token}`);
}

Delete Card

Deletes a stored payment card.

await gopay.payments.deleteCard({
  card_id: "9876543210"
});

Payment Instruments

Get Payment Instruments

Retrieves allowed payment instruments for a specific currency.

const instruments = await gopay.payments.getPaymentInstruments({
  goid: 8123456789,
  currency: Currency.CZK,
  lang: Lang.CS
});

instruments.enabledPaymentInstruments.forEach(instrument => {
  console.log(`${instrument.paymentInstrument}: ${instrument.label.cs}`);
});

Get All Payment Instruments

Retrieves all allowed payment instruments for an eshop.

const allInstruments = await gopay.payments.getAllPaymentInstruments({
  goid: 8123456789,
  lang: Lang.CS
});

Account Statement

Get Account Statement

Retrieves an account statement for a specific date range and currency.

const statement = await gopay.payments.getAccountStatement({
  date_from: "2022-12-01",
  date_to: "2022-12-02",
  goid: 8123456789,
  currency: Currency.CZK,
  format: "CSV_A"
});

// Save to file
require('fs').writeFileSync('statement.csv', statement);

Error Handling

The library provides specific error types for different error scenarios:

import { GoPayError, GoPayAuthenticationError, GoPayNetworkError } from '@glydebyte/gopay-wrapper';

try {
  const payment = await gopay.payments.createPayment({
    // payment data
  });
} catch (error) {
  if (error instanceof GoPayAuthenticationError) {
    console.error('Authentication failed:', error.message);
  } else if (error instanceof GoPayNetworkError) {
    console.error('Network error:', error.message);
  } else if (error instanceof GoPayError) {
    console.error('GoPay error:', error.message);
    console.error('Error code:', error.errorCode);
  } else {
    console.error('Unknown error:', error);
  }
}

Types

The library exports all necessary TypeScript types:

import {
  PaymentCreateRequest,
  PaymentCreateResponse,
  PaymentInquireResponse,
  PaymentRefundRequest,
  PaymentRefundResponse,
  Currency,
  PaymentInstrument,
  State,
  Lang,
  RecurrenceCycle,
  RecurrenceState,
  Result,
  // ... and more
} from '@glydebyte/gopay-wrapper';

Payment States

The library includes all GoPay payment states:

• CREATED - Payment created
• PAID - Payment paid
• CANCELED - Payment canceled
• PAYMENT_METHOD_CHOSEN - Payment method chosen
• TIMEOUTED - Payment timeouted
• AUTHORIZED - Payment authorized (preauthorized)
• REFUNDED - Payment refunded
• PARTIALLY_REFUNDED - Payment partially refunded

Supported Payment Instruments

• PAYMENT_CARD - Payment card
• BANK_ACCOUNT - Bank transfer
• GPAY - Google Pay
• APPLE_PAY - Apple Pay
• PAYPAL - PayPal
• MPAYMENT - mPlatba
• PRSMS - Premium SMS
• PAYSAFECARD - PaySafeCard
• BITCOIN - Bitcoin
• CLICK_TO_PAY - Click To Pay
• TWISTO - Twisto (developer preview)
• SKIPPAY - Skip Pay (developer preview)

Supported Currencies

• CZK - Czech Crown
• EUR - Euro
• PLN - Polish Zloty
• USD - US Dollar
• GBP - British Pound
• HUF - Hungarian Forint
• RON - Romanian Leu
• BGN - Bulgarian Lev
• HRK - Croatian Kuna

License

GPL-3.0

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

References

• GoPay Technical Documentation
• GoPay API Reference