> ## 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) — typovaný TypeScript klient pro GoPay REST API.

# GoPay SDK

<Info>
  **Balíček:** [`gopay-sdk`](https://www.npmjs.com/package/gopay-sdk) na npm — TypeScript klient pro oficiální [GoPay REST API](https://doc.gopay.com/), určený pro serverové služby Node.js.
</Info>

<Tip>
  **Začínáte?** Jděte na [Instalaci](/cs/installation) → [Rychlý start](/cs/quickstart) → první sandbox platbu, pak [Platby](/cs/payments) a [Zpracování chyb](/cs/error-handling).
</Tip>

SDK řeší OAuth2 tokeny, typované požadavky a odpovědi a celý životní cyklus plateb — vy se soustředíte na logiku produktu.

## Přehled

|                 |                                                                             |
| --------------- | --------------------------------------------------------------------------- |
| **Autentizace** | OAuth2 `client_credentials`, automatické obnovení, vyměnitelná cache tokenů |
| **Typy**        | Silné modely, enumy a signatury metod napříč API                            |
| **Nasazení**    | ESM + CJS, Node 18+, funguje s vaším HTTP stackem                           |

## Co můžete stavět

* **Platby** — vytváření, dotazování a dokončení checkoutu
* **Refundace** — plné nebo částečné refundace a historie
* **Recurrence a autorizace** — opakované platby, capture, void
* **Instrumenty a výpisy** — platební metody podle měny, exporty účtu
* **Observabilita** — vlastní `HttpTransport` / `TokenCache` pro tracing a sdílenou cache

<Columns cols={3}>
  <Card title="Instalace" icon="download" href="/cs/installation">
    Přidejte `gopay-sdk` a nasměrujte sandbox nebo produkční URL brány.
  </Card>

  <Card title="Rychlý start" icon="bolt" href="/cs/quickstart">
    Sandbox přihlašovací údaje, klient a první `createPayment` v několika krocích.
  </Card>

  <Card title="Konfigurace" icon="settings" href="/cs/configuration">
    Timeouty, OAuth scope, jazyk, vlastní `User-Agent`, transport a cache.
  </Card>

  <Card title="Platby" icon="credit-card" href="/cs/payments">
    Vytváření plateb, stav, karty a embed helpery.
  </Card>

  <Card title="Chyby" icon="shield-alert" href="/cs/error-handling">
    `GoPayApiError` vs `GoPayConfigError`, opakování a bezpečné logování.
  </Card>

  <Card title="Doporučení" icon="sparkles" href="/cs/best-practices">
    Produkční vzory: tajemství, částky, idempotence a odolnost.
  </Card>
</Columns>

## Požadavky

* Node.js `>=18`
* TypeScript `>=5` (doporučeno)

## Instalace

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

## Minimální příklad

```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);
```