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

# Extensibility

> Customize HTTP transport and token caching for advanced deployments.

# Extensibility

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

`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`](/api-reference/subpath-imports) for narrower imports.

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

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

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

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