Skip to main content

Integration Options

This guide covers common checkout integration patterns.

Full-Page Redirect (Recommended)​

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

const checkout = await createCheckout(params, opts);
window.location.href = checkout.checkoutUrl;

Flow​

  1. Backend creates an order (createCheckout).
  2. Customer is redirected to pay.peer.xyz/?order=...&token=....
  3. Customer completes payment.
  4. Customer returns via your successUrl or cancelUrl.

New Tab​

window.open(checkout.checkoutUrl, '_blank');

Good when you want to keep the merchant page open.

Embedded Iframe​

Embedded checkout is supported with the @zkp2p/pay-sdk/embedded helpers.

import { useEffect, useRef } from 'react';
import { EMBED_EVENT_CHANNEL, ensureEmbedModeUrl } from '@zkp2p/pay-sdk/embedded';

export function EmbeddedCheckout({ checkoutUrl }: { checkoutUrl: string }) {
  const iframeRef = useRef<HTMLIFrameElement | null>(null);

  useEffect(() => {
    const onMessage = (event: MessageEvent) => {
      if (event.source !== iframeRef.current?.contentWindow) return;
      if (!event.data || event.data.channel !== EMBED_EVENT_CHANNEL) return;

      if (event.data.type === 'checkout.success') {
        // parent success handling
      }

      if (event.data.type === 'checkout.failed') {
        // parent failure handling
      }
    };

    window.addEventListener('message', onMessage);
    return () => window.removeEventListener('message', onMessage);
  }, []);

  return (
    <iframe
      ref={iframeRef}
      title="Embedded Checkout"
      src={ensureEmbedModeUrl(checkoutUrl)}
      sandbox="allow-scripts allow-forms allow-same-origin allow-popups allow-popups-to-escape-sandbox"
    />
  );
}
const checkout = await createCheckout(
  {
    requestedUsdcAmount: '50.00',
    destinationChainId: 8453,
    destinationToken: 'USDC',
    successUrl: 'https://yoursite.com/payment/success',
    cancelUrl: 'https://yoursite.com/payment/cancelled',
    notes: { merchantOrderId: orderId },
  },
  opts,
);

await db.orders.update({
  where: { id: orderId },
  data: { checkoutOrderId: checkout.order.id },
});

return checkout.checkoutUrl;

Use webhooks for final state updates, especially PAYMENT_SETTLED, PAYMENT_FAILED, PAYMENT_EXPIRED, and ORDER_FULFILLED.

Checkout supports multi-currency quote selection and payment FX snapshots.