Configuration
Never commit clientSecret or live credentials to source control. Use environment variables or a secrets manager in every environment.
Use createGoPayClient to initialize the SDK.
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
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.
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