> ## Documentation Index
> Fetch the complete documentation index at: https://docs.zabcik.me/llms.txt
> Use this file to discover all available pages before exploring further.

# GoPay SDK

> GoPay SDK (npm: gopay-sdk) — strongly typed TypeScript client for the GoPay REST API.

# GoPay SDK

<Info>
  **Package:** [`gopay-sdk`](https://www.npmjs.com/package/gopay-sdk) on npm —
  a TypeScript client for the official [GoPay REST
  API](https://doc.gopay.com/), built for server-side Node.js services.
</Info>

<Tip>
  **New here?** Follow [Installation](/installation) →
  [Quickstart](/quickstart) → your first sandbox payment, then dive into
  [Payments](/payments) and [Error handling](/error-handling).
</Tip>

The SDK handles OAuth2 tokens, typed requests and responses, and the full payment lifecycle so you can focus on your product logic.

## Highlights

|            |                                                                       |
| ---------- | --------------------------------------------------------------------- |
| **Auth**   | OAuth2 `client_credentials`, automatic refresh, pluggable token cache |
| **Types**  | Strong models, enums, and method signatures across the API            |
| **Deploy** | ESM + 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

<Columns cols={3}>
  <Card title="Installation" icon="download" href="/installation">
    Add `gopay-sdk` and point at sandbox or production gateway URLs.
  </Card>

  <Card title="Quickstart" icon="bolt" href="/quickstart">
    Sandbox credentials, client setup, and first `createPayment` in a few
    steps.
  </Card>

  <Card title="Configuration" icon="settings" href="/configuration">
    Timeouts, OAuth scope, language, custom `User-Agent`, transport, and
    cache.
  </Card>

  <Card title="Payments" icon="credit-card" href="/payments">
    Create payments, query state, cards, and embed helpers.
  </Card>

  <Card title="Error handling" icon="shield-alert" href="/error-handling">
    `GoPayApiError` vs `GoPayConfigError`, retries, and logging safely.
  </Card>

  <Card title="Best practices" icon="sparkles" href="/best-practices">
    Production patterns: secrets, amounts, idempotency, and resilience.
  </Card>
</Columns>

## Requirements

* Node.js `>=18`
* TypeScript `>=5` (recommended)

## Install

```bash theme={null}
npm install gopay-sdk
```

## Minimal example

```ts theme={null}
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);
```