@zkp2p/pay-sdk

TypeScript SDK for creating ZKP2P Pay checkout sessions and redirecting customers to checkout.

• Package: @zkp2p/pay-sdk
• Module format: ESM
• Runtime: Browser or Node.js (with fetch available)

Install

npm install @zkp2p/pay-sdk

Quick Start

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

const client: CheckoutClientOptions = {
  apiBaseUrl: 'https://api.zkp2p.xyz',
  checkoutBaseUrl: 'https://pay.zkp2p.xyz',
  apiKey: '<merchant-api-key>',
};

const result = await createCheckoutSession(
  {
    merchantId: '<merchant-id>',
    checkoutMode: 'exact-token',
    amountUsdc: '25.00',
    destinationChainId: 8453,
    destinationToken: 'USDC',
    recipientAddress: '0xYourRecipientAddress',
    successUrl: 'https://merchant.example/success',
    cancelUrl: 'https://merchant.example/cancel',
  },
  client
);

// Browser-only helper.
redirectToCheckout(result.session.id, result.sessionToken, client);

Exact-Fiat Session Example

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

const result = await createCheckoutSession(
  {
    merchantId: '<merchant-id>',
    checkoutMode: 'exact-fiat',
    fiatAmount: '39.99',
    fiatCurrency: 'USD',
    maxFeePercentage: 1.5,
    destinationChainId: 8453,
    destinationToken: 'USDC',
    recipientAddress: '0xYourRecipientAddress',
  },
  {
    apiBaseUrl: 'https://api.zkp2p.xyz',
    apiKey: '<merchant-api-key>',
  }
);

console.log(result.session.netAmountUsdc);

session.netAmountUsdc is returned for exact-token and exact-fiat sessions. If fee-recipient configuration or fee calculation is unavailable, the API falls back to amountUsdc.

API

createCheckoutSession(params, options)

Creates a checkout session via POST /api/checkout/sessions.

• Requires options.apiKey (sent as X-API-Key).
• Returns CreateSessionResponse with session, sessionToken, checkoutUrl, and optional bridge.

getMerchant(merchantId, options)

Fetches merchant profile data via GET /api/merchants/:merchantId.

Returns MerchantInfo, including checkout defaults and enabled platforms.

getCheckoutUrl(sessionId, options, sessionToken)

Builds a checkout URL:

• Uses options.checkoutBaseUrl when provided.
• Falls back to options.apiBaseUrl.

redirectToCheckout(sessionId, sessionToken, options)

Browser helper that calls window.location.assign(getCheckoutUrl(...)).

createSessionAndRedirect(params, options)

Convenience helper that:

1. Creates a session
2. Redirects to checkout
3. Returns the same CreateSessionResponse

Client Options

type CheckoutClientOptions = {
  apiBaseUrl: string;
  checkoutBaseUrl?: string;
  apiKey: string;
  fetcher?: typeof fetch;
};

Exported Types

The SDK re-exports shared types from @zkp2p/pay-shared:

• CreateSessionRequest
• CreateSessionResponse
• BridgeInfo
• Merchant

SDK-specific types:

• CheckoutClientOptions
• MerchantInfo

Embedded Checkout Helpers

Subpath export:

import {
  EMBED_EVENT_CHANNEL,
  isEmbeddedCheckout,
  ensureEmbedModeUrl,
  buildEmbedCheckoutEvent,
  postEmbedCheckoutEvent,
} from '@zkp2p/pay-sdk/embedded';

Helpers:

• isEmbeddedCheckout(search, selfWindow?)
• ensureEmbedModeUrl(url, baseOrigin?)
• buildEmbedCheckoutEvent(type, payload)
• postEmbedCheckoutEvent(type, payload, parentWindow?)

Supported event types:

• checkout.success
• checkout.failed

Error Handling

createCheckoutSession and getMerchant throw an Error when:

• the HTTP response is not OK
• the API returns { success: false }
• required auth options are missing

Handle failures with try/catch around SDK calls.