@zkp2p/pay-sdk

TypeScript SDK for creating checkout orders against the canonical orders API.

• Package: @zkp2p/pay-sdk
• Runtime: browser or Node.js with fetch
• Module format: ESM

Install

npm install @zkp2p/[email protected]

Published artifacts

• Includes compiled ESM JavaScript and .d.ts type declarations.
• Does not publish declaration maps (.d.ts.map) or JavaScript source maps (.js.map).

Recommended flow

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

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

const checkout = await createCheckout(
  {
    requestedFiatAmount: '25.00',
    requestedFiatCurrency: 'EUR',
    destinationAddress: '0xYourRecipientAddress',
    destinationToken: 'USDC',
    destinationChainId: 8453,
    successUrl: 'https://merchant.example/success',
    cancelUrl: 'https://merchant.example/cancel',
    notes: { cartId: 'cart_123' },
  },
  client,
);

redirectToCheckout(checkout.order.id, checkout.orderToken, client);

Functions

createCheckout(params, options)

Creates an order via POST /api/v1/orders and returns:

• order
• orderToken
• checkoutUrl

params maps to the API schema:

• amount input XOR:
  • requestedUsdcAmount
  • requestedFiatAmount + requestedFiatCurrency
• destinationAddress (optional)
• destinationToken (optional)
• destinationChainId (optional)
• feePayer (optional)
• enabledRails (optional)
• successUrl (nullable, defaults to null)
• cancelUrl (nullable, defaults to null)
• notes (nullable, defaults to null)

In fiat mode, the API converts to canonical USD/USDC amounts and persists order amounts in USDC fields.

getCheckoutUrl(orderId, orderToken, options)

Builds the checkout URL using checkoutBaseUrl when provided and apiBaseUrl otherwise.

redirectToCheckout(orderId, orderToken, options)

Browser helper that redirects to the checkout URL.

createCheckoutAndRedirect(params, options)

Creates an order and immediately redirects.

getMerchant(options) (or getMerchant(merchantId, options) for compatibility)

Fetches merchant profile data via GET /api/v1/merchants/me.

Legacy APIs

Legacy session helper APIs are not exported from the current SDK surface.

Client options

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

Embedded checkout helpers

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

Supported event types:

• checkout.success
• checkout.failed

Error handling

SDK helpers throw Error when:

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

Wrap SDK calls in try/catch.