Configuration

All SDK functions accept a CheckoutClientOptions object for configuration.

CheckoutClientOptions

interface CheckoutClientOptions {
  /** Base URL for the API server (e.g., https://api.zkp2p-pay.xyz) */
  apiBaseUrl: string;

  /** Your merchant API key for authentication */
  apiKey: string;

  /** Base URL for the checkout UI (defaults to apiBaseUrl) */
  checkoutBaseUrl?: string;

  /** Custom fetch implementation (defaults to global fetch) */
  fetcher?: typeof fetch;
}

Properties

apiBaseUrl (required)

The base URL of the ZKP2P Pay API server.

{
  apiBaseUrl: 'https://api.zkp2p-pay.xyz'
}

apiKey (required)

Your merchant API key for authentication. This is included in the X-API-Key header on all requests.

{
  apiKey: process.env.ZKPAY_API_KEY
}

caution

Never expose your API key in client-side code. Create sessions on your backend.

checkoutBaseUrl (optional)

The base URL for the checkout UI. If not specified, it defaults to the apiBaseUrl.

{
  apiBaseUrl: 'https://api.zkp2p-pay.xyz',
  checkoutBaseUrl: 'https://checkout.zkp2p-pay.xyz'
}

fetcher (optional)

A custom fetch implementation. Useful for testing or when you need to customize request behavior.

{
  fetcher: customFetch
}

Environment-Based Configuration

Here's a pattern for managing configuration across environments:

const config: CheckoutClientOptions = {
  apiBaseUrl: process.env.ZKPAY_API_URL || 'https://api.zkp2p-pay.xyz',
  apiKey: process.env.ZKPAY_API_KEY!,
  checkoutBaseUrl: process.env.ZKPAY_CHECKOUT_URL || 'https://checkout.zkp2p-pay.xyz',
};

// Use throughout your application
const session = await createCheckoutSession(params, config);

Example: Testing with Custom Fetcher

import { createCheckoutSession } from '@zkp2p-pay/sdk';

// Mock fetcher for testing
const mockFetcher = async (url: string, init?: RequestInit) => {
  console.log('Request:', url, init);
  return new Response(JSON.stringify({
    responseObject: {
      session: { id: 'test_session' },
      checkoutUrl: 'https://checkout.example.com/test',
    }
  }));
};

const session = await createCheckoutSession(params, {
  apiBaseUrl: 'https://api.zkp2p-pay.xyz',
  apiKey: 'test_key',
  fetcher: mockFetcher,
});

API Endpoints

The SDK constructs the following endpoints from apiBaseUrl:

Function	Endpoint
createCheckoutSession	POST {apiBaseUrl}/api/checkout/sessions

The checkout URL is constructed from checkoutBaseUrl:

Function	URL Pattern
getCheckoutUrl	{checkoutBaseUrl}/checkout?session={sessionId}