Authentication

Understanding authentication methods in the PayNow SDK

Overview

The PayNow SDK supports two distinct authentication methods, each designed for different use cases:

• Customer Tokens: For storefront operations (browsing products, creating orders)
• API Keys: For management operations (creating products, managing orders)

Authentication Methods

Customer Token

Customer tokens are used with the Storefront Client to authenticate end-users browsing your store or making purchases.

import { createStorefrontClient } from '@paynow-gg/typescript-sdk';

const storefront = createStorefrontClient(
  'your-store-id',
  'customer-token-here' // Optional customer token
);

How it works

When you provide a customer token, the SDK automatically sets the appropriate authentication header:

// From src/storefront.ts:18
Authorization: customerToken ? `Customer ${customerToken}` : ""

The customer token is prefixed with Customer and sent in the Authorization header with every request.

Customer tokens are optional for the Storefront Client. You can browse public store information without authentication.

API Key

API keys are used with the Management Client to perform administrative operations on your store.

import { createManagementClient } from '@paynow-gg/typescript-sdk';

const management = createManagementClient(
  'your-store-id',
  'your-api-key' // Required API key
);

How it works

The API key is automatically formatted and included in the authorization header:

// From src/management.ts:17
Authorization: `APIKey ${apiKey}`

The API key is prefixed with APIKey and sent in the Authorization header with every request.

API keys grant full access to your store’s management operations. Never expose them in client-side code or public repositories.

Store ID Header

Both client types automatically include your store ID in request headers:

// From src/storefront.ts:17
"x-paynow-store-id": storeId

This header is set once during client initialization and included with every request.

Authentication Flow

Here’s how authentication headers are constructed internally:

Storefront Client

// From src/storefront.ts:9-24
export function createStorefrontClient(
  storeId: string,
  customerToken?: string,
  options?: CreateAxiosDefaults,
): StorefrontClient {
  const client = createClient<StorefrontOperation>(
    operationMappings,
    {
      "x-paynow-store-id": storeId,
      Authorization: customerToken ? `Customer ${customerToken}` : "",
    },
    { storeId },
    options,
  );

  return client;
}

Custom Headers

You can provide additional headers or override defaults using the options parameter:

const storefront = createStorefrontClient(
  'your-store-id',
  'customer-token',
  {
    headers: {
      'X-Custom-Header': 'value',
    },
  }
);

Custom headers are merged with the default headers. The SDK automatically sets Content-Type: application/json and Accept: application/json for all requests.

Base URL

All clients connect to the PayNow API at:

baseURL: "https://api.paynow.gg"

You can override this in the options if needed for testing:

const client = createStorefrontClient('store-id', undefined, {
  baseURL: 'https://staging-api.paynow.gg',
});

Next Steps

Client Architecture

Learn how the SDK organizes operations and methods

Error Handling

Understand how to handle API errors gracefully