Skip to main content

​
GoPay SDK

Package: gopay-sdk on npm — a TypeScript client for the official GoPay REST API, built for server-side Node.js services.
New here? Follow Installation → Quickstart → your first sandbox payment, then dive into Payments and Error handling.
The SDK handles OAuth2 tokens, typed requests and responses, and the full payment lifecycle so you can focus on your product logic.

​
Highlights

AuthOAuth2 client_credentials, automatic refresh, pluggable token cache
TypesStrong models, enums, and method signatures across the API
DeployESM + CJS, Node 18+, works with your existing HTTP stack

​
What you can build

  • Payments — create, query, and complete checkout flows
  • Refunds — full or partial refunds and refund history
  • Recurrence & auth — recurring charges, captures, voids
  • Instruments & statements — payment methods per currency, account exports
  • Observability — inject HttpTransport / TokenCache for tracing and shared caches

Installation

Add gopay-sdk and point at sandbox or production gateway URLs.

Quickstart

Sandbox credentials, client setup, and first createPayment in a few steps.

Configuration

Timeouts, OAuth scope, language, custom User-Agent, transport, and cache.

Payments

Create payments, query state, cards, and embed helpers.

Error handling

GoPayApiError vs GoPayConfigError, retries, and logging safely.

Best practices

Production patterns: secrets, amounts, idempotency, and resilience.

​
Requirements

  • Node.js >=18
  • TypeScript >=5 (recommended)

​
Install

npm install gopay-sdk

​
Minimal example

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-123',
    payer: {
        contact: {
            email: 'john.doe@example.com',
        },
    },
    callback: {
        return_url: 'https://example.com/return',
        notification_url: 'https://example.com/notify',
    },
});

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