Extensibility

Most integrations only need createGoPayClient defaults. Reach for custom HttpTransport / TokenCache when you need observability, proxies, shared token storage, or non-fetch HTTP clients.

gopay-sdk is intentionally extensible through two abstractions:

HttpTransport: customize how requests are executed
TokenCache: customize where OAuth tokens are stored

Custom HTTP transport

Implement HttpTransport to plug in custom fetch behavior (logging, retries, tracing, proxying, etc.). You can import transport types from the main package or from gopay-sdk/http for narrower imports.

import type { HttpTransport, HttpTransportRequest } from 'gopay-sdk';

class ObservabilityTransport implements HttpTransport {
  async execute(request: HttpTransportRequest): Promise<Response> {
    const startedAt = Date.now();

    try {
      const response = await fetch(request.url, {
        method: request.method,
        headers: request.headers,
        body: request.body,
      });

      console.log('gopay_request', {
        method: request.method,
        url: request.url,
        status: response.status,
        durationMs: Date.now() - startedAt,
      });

      return response;
    } catch (error) {
      console.error('gopay_request_failed', {
        method: request.method,
        url: request.url,
        durationMs: Date.now() - startedAt,
        error,
      });
      throw error;
    }
  }
}

Use it in client creation:

import { 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',
  },
  {
    transport: new ObservabilityTransport(),
  },
);

Custom token cache

Implement TokenCache for Redis, Memcached, database, or distributed in-memory systems.

import type { OAuthToken, TokenCache } from 'gopay-sdk';

class MemoryTokenCache implements TokenCache {
  private readonly tokens = new Map<string, OAuthToken>();

  get(key: string): OAuthToken | undefined {
    return this.tokens.get(key);
  }

  set(key: string, value: OAuthToken): void {
    this.tokens.set(key, value);
  }

  delete(key: string): void {
    this.tokens.delete(key);
  }
}

Use it in client creation:

import { 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',
  },
  {
    tokenCache: new MemoryTokenCache(),
  },
);

Design recommendations

Keep transport retries conservative (network timeouts only).
Do not blindly retry non-idempotent payment create calls.
Centralize observability and correlation IDs at transport layer.
Use a shared token cache when many service instances share the same credentials.
Keep cache key granularity aligned with clientId + gatewayUrl + scope.

API reference

Examples

Extensibility

Extensibility

Custom HTTP transport

Custom token cache

Design recommendations

​Extensibility

​Custom HTTP transport

​Custom token cache

​Design recommendations

Extensibility

Custom HTTP transport

Custom token cache

Design recommendations