Skip to main content

​
Authentication

The SDK authenticates against GoPay using OAuth2 client_credentials.
You do not call the token endpoint yourself for normal API usage — the SDK caches access tokens and refreshes them before expiry.

​
How it works

On first API call:
  1. The SDK sends a request to POST /oauth2/token
  2. It stores the token in cache with expiration timestamp
  3. It reuses that token until it approaches expiration
  4. It refreshes automatically before expiry (refresh margin)

​
Token endpoint request

The SDK sends:
  • grant_type=client_credentials
  • configured scope (payment-all by default)
  • Authorization: Basic <base64(clientId:clientSecret)>

​
Token cache

By default, InMemoryTokenCache is used.
A shared cache (Redis, memcached, etc.) is useful when you run multiple server instances so you don’t multiply OAuth token requests unnecessarily.
You can inject your own cache to share tokens across requests or processes: 
import { createGoPayClient, type TokenCache } from 'gopay-sdk';

class RedisLikeCache implements TokenCache {
  private readonly storage = new Map<string, any>();

  get(key: string) {
    return this.storage.get(key);
  }

  set(key: string, value: any) {
    this.storage.set(key, value);
  }

  delete(key: string) {
    this.storage.delete(key);
  }
}

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 RedisLikeCache(),
  },
);

​
Concurrency behavior

The token manager deduplicates concurrent token requests:
  • if multiple requests need a token at once, only one token HTTP call is executed
  • all callers await the same in-flight promise
This avoids token endpoint burst traffic.
  • keep tokenRefreshMarginSeconds default (30) unless your infra requires more buffer
  • keep credentials in environment variables or secret manager
  • avoid rotating credentials without coordinated deployment across all nodes