createCheckoutSession

Creates a new checkout session for a payment.

Signature

function createCheckoutSession(
  params: CreateSessionRequest,
  opts: CheckoutClientOptions
): Promise<CreateSessionResponse>

Parameters

params: CreateSessionRequest

Property	Type	Required	Description
merchantId	string	Yes	Your merchant ID
amountUsdc	string	Yes	Amount in USDC (e.g., "50.00")
destinationChainId	number	Yes	Target chain ID (8453 for Base)
destinationToken	string	Yes	Token address (USDC on Base)
recipientAddress	string	Yes	Wallet to receive funds
successUrl	string	No	Redirect URL after successful payment
cancelUrl	string	No	Redirect URL if user cancels
metadata	Record<string, string>	No	Custom key-value pairs (passed to webhooks)

opts: CheckoutClientOptions

Property	Type	Required	Description
apiBaseUrl	string	Yes	API server URL
apiKey	string	Yes	Your merchant API key
checkoutBaseUrl	string	No	Checkout UI URL (defaults to apiBaseUrl)
fetcher	typeof fetch	No	Custom fetch implementation

Returns

interface CreateSessionResponse {
  session: CheckoutSession;
  checkoutUrl: string;
}

The response includes the full session object and a ready-to-use checkout URL.

Example

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

const response = await createCheckoutSession(
  {
    merchantId: 'merchant_abc123',
    amountUsdc: '99.99',
    destinationChainId: 8453,
    destinationToken: '0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913',
    recipientAddress: '0x742d35Cc6634C0532925a3b844Bc9e7595f8fE71',
    successUrl: 'https://mystore.com/order/success',
    cancelUrl: 'https://mystore.com/cart',
    metadata: {
      orderId: 'order_12345',
      customerId: 'cust_67890',
      productName: 'Premium Subscription',
    },
  },
  {
    apiBaseUrl: 'https://api.zkp2p-pay.xyz',
    apiKey: process.env.ZKPAY_API_KEY!,
  }
);

console.log('Session ID:', response.session.id);
console.log('Checkout URL:', response.checkoutUrl);

Error Handling

The function throws an error if:

• The API key is missing or invalid
• The request parameters are invalid
• The API request fails

try {
  const response = await createCheckoutSession(params, opts);
} catch (error) {
  console.error('Failed to create session:', error.message);
}

Notes

• The amountUsdc should be a decimal string (e.g., "50.00", not 50)
• The metadata object is limited to string values
• Session IDs are unique and can be used to track the payment
• The checkoutUrl expires after 24 hours