Configuration

All SDK functions accept CheckoutClientOptions.

CheckoutClientOptions

interface CheckoutClientOptions {
  apiBaseUrl: string;
  checkoutBaseUrl?: string;
  apiKey?: string;
  fetcher?: typeof fetch;
  preselectedMethod?: PaymentPlatform;
}

Fields

apiBaseUrl (required)

Base URL for API requests.

{
  apiBaseUrl: 'https://api.pay.peer.xyz'
}

apiKey (required for authenticated endpoints)

Used as X-API-Key when creating orders and reading merchant data.

{
  apiKey: process.env.ZKPAY_API_KEY
}

checkoutBaseUrl (optional)

Overrides checkout URL generation. Defaults to apiBaseUrl.

{
  apiBaseUrl: 'https://api.pay.peer.xyz',
  checkoutBaseUrl: 'https://pay.peer.xyz'
}

fetcher (optional)

Custom fetch implementation for tests or custom transport.

{
  fetcher: customFetch
}

preselectedMethod (optional)

Pre-select a payment method on the hosted checkout. The value must be one of the PaymentPlatform enum values (venmo, cashapp, zelle, paypal, revolut, wise, monzo, n26, chime).

When set, the SDK appends ?method=<rail> to the returned checkoutUrl. The hosted checkout reads the param on landing and auto-selects the rail if it is available. If the rail is unavailable (no liquidity, currency-incompatible, or not supported on the customer's device), the checkout shows an inline notice and lets the customer pick another rail.

Validation: invalid values reject the Promise returned by createCheckout with a TypeError before any network request is made. getCheckoutUrl throws synchronously.

const { checkoutUrl } = await createCheckout(
  { requestedUsdcAmount: '10' },
  { apiKey, apiBaseUrl, preselectedMethod: 'venmo' },
);
// checkoutUrl: https://pay.peer.xyz/?order=...&token=...&method=venmo

note

preselectedMethod is SDK-only. It is not sent to the API in the create-order request body.

Example

import { createCheckout, type CheckoutClientOptions } from '@zkp2p/pay-sdk';

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

await createCheckout(
  {
    requestedUsdcAmount: '20.00',
    destinationChainId: 8453,
    destinationToken: 'USDC',
  },
  config,
);

Endpoint Mapping

Function	Endpoint
createCheckout	POST {apiBaseUrl}/api/v1/orders
getMerchant	GET {apiBaseUrl}/api/v1/merchants/me

getCheckoutUrl builds {checkoutBaseUrl}/?order={orderId}&token={orderToken}.