Configuration

Checkout and merchant functions accept CheckoutClientOptions. This page is the canonical reference for its fields. Payout functions accept PayoutClientOptions: apiBaseUrl, a required apiKey, and optional fetcher and signal. See Payouts.

CheckoutClientOptions

interface CheckoutClientOptions {
  apiBaseUrl: string;
  checkoutBaseUrl?: string;
  apiKey?: string;
  fetcher?: typeof fetch;
  signal?: AbortSignal;
  preselectedMethod?: PaymentPlatformType;
}

PaymentPlatformType is not exported from @zkp2p/pay-sdk. Import it from @zkp2p/pay-shared when you need to annotate the value.

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, reading merchant data, and checking quote availability.

{
  apiKey: process.env.ZKPAY_API_KEY
}

checkoutBaseUrl (optional, set it anyway)

Host the returned checkoutUrl is built on. It defaults to apiBaseUrl, so omitting it sends the customer to the API host. Set it on every call that produces a checkout URL.

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

fetcher (optional)

Custom fetch implementation for tests or custom transport.

{
  fetcher: customFetch
}

signal (optional)

An AbortSignal that cancels the in-flight request. Honored by every fetch-based SDK function. Bound server-side calls with a timeout so a slow upstream cannot block your own request handler:

{
  signal: AbortSignal.timeout(8_000)
}

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: 'https://api.pay.peer.xyz',
    checkoutBaseUrl: 'https://pay.peer.xyz',
    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
checkQuoteAvailability	POST {apiBaseUrl}/api/v1/merchants/me/quotes/availability

getCheckoutUrl builds {checkoutBaseUrl}/?order={orderId}&token={orderToken}. Only the origin of checkoutBaseUrl is used; any path or query string on it is replaced.

Endpoints with no SDK helper, such as listing orders and payments, are in the API reference.