> ## 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.

# Configuration

> Understand every createGoPayClient configuration option, defaults, and production recommendations.

# Configuration

<Warning>
  Never commit `clientSecret` or live credentials to source control. Use environment variables or a secrets manager in every environment.
</Warning>

Use `createGoPayClient` to initialize the SDK.

```ts theme={null}
import { Language, TokenScope, 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',
  scope: TokenScope.ALL,
  language: Language.EN,
  timeoutMs: 30_000,
  customUserAgent: 'my-service/1.0.0',
  tokenRefreshMarginSeconds: 30,
});
```

## Config fields

### `goid: number | string`

Your merchant GoPay account ID. Values are normalized to `number`.

### `clientId: string`

OAuth2 client identifier from GoPay.

### `clientSecret: string`

OAuth2 client secret from GoPay.

### `gatewayUrl: string`

GoPay API gateway base URL.

Common values:

* Sandbox: `https://gw.sandbox.gopay.com/api`
* Production: `https://gate.gopay.cz/api`

The SDK normalizes the value and ensures it ends with `/api`.

### `scope?: TokenScope`

OAuth scope for access token requests.

* `TokenScope.ALL` (`payment-all`) — default
* `TokenScope.CREATE_PAYMENT` (`payment-create`)

### `language?: Language`

Default SDK language used in request headers and payment defaults.
Default: `Language.EN`.

### `timeoutMs?: number`

HTTP timeout for each request in milliseconds.
Default: `30000`.

### `customUserAgent?: string`

Custom `User-Agent` header value.
Default: `gopay-sdk-ts/1.0.0`.

### `tokenRefreshMarginSeconds?: number`

How early token refresh should happen before actual expiry.
Default: `30`.

## Second argument: options

<Tip>
  Provide a custom **`TokenCache`** to share tokens across workers, or a custom **`HttpTransport`** to plug in proxies, tracing, or non-`fetch` HTTP stacks — see [Extensibility](/api-reference/extensibility).
</Tip>

```ts theme={null}
import { createGoPayClient, type HttpTransport, type TokenCache } from 'gopay-sdk';

const tokenCache: TokenCache = {
  get: (key) => undefined,
  set: (key, value) => {},
  delete: (key) => {},
};

const transport: HttpTransport = {
  execute: async (request) => fetch(request.url, request),
};

const client = createGoPayClient(config, {
  tokenCache,
  transport,
});
```

## Validation behavior

The SDK throws `GoPayConfigError` when:

* `clientId` is missing
* `clientSecret` is missing
* `goid` is not numeric
* `gatewayUrl` is empty or invalid
* `timeoutMs <= 0`
* `tokenRefreshMarginSeconds < 0`