createCheckout

Creates an order and returns an authenticated checkout URL.

Signature

function createCheckout(
  params: CreateOrderRequest,
  opts: CheckoutClientOptions
): Promise<CreateCheckoutResult>

Parameters

params: CreateOrderRequest

Property	Type	Required	Description
requestedUsdcAmount	string	Conditional	Use this for direct USDC mode. Mutually exclusive with fiat-mode fields.
requestedFiatAmount	string	Conditional	Fiat-mode input amount. Requires requestedFiatCurrency.
requestedFiatCurrency	string	Conditional	Fiat-mode ISO currency code (for example EUR). Requires requestedFiatAmount.
destinationAddress	string	No	Override destination wallet (falls back to merchant config when omitted)
destinationToken	string	No	Override destination token alias/address
destinationChainId	number	No	Override destination chain
feePayer	FeePayerType	No	Fee mode override
enabledRails	string[]	No	Restrict available rails
successUrl	string | null	No	Redirect target after successful checkout (defaults to null)
cancelUrl	string | null	No	Redirect target when user cancels (defaults to null)
notes	Record<string, unknown> | null	No	Merchant notes payload (defaults to null)

createCheckout sends these fields to POST /api/v1/orders using the same structure as the API schema.

Create-order amount input is XOR:

• USDC mode: requestedUsdcAmount
• Fiat mode: requestedFiatAmount + requestedFiatCurrency

In fiat mode, the API converts fiat to USD (USD->USDC is 1:1), rounds to 2 decimals (half-up), and persists canonical order amounts in USDC fields.

opts: CheckoutClientOptions

Property	Type	Required	Description
apiBaseUrl	string	Yes	API base URL (for example https://api.pay.peer.xyz)
apiKey	string	Yes	Merchant API key
checkoutBaseUrl	string	No	Checkout host override
fetcher	typeof fetch	No	Custom fetch implementation

Returns

type CreateCheckoutResult = {
  order: CheckoutOrder;
  orderToken: string;
  checkoutUrl: string;
};

checkoutUrl already includes the order token, so you can redirect immediately.

Example

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

const checkout = await createCheckout(
  {
    requestedFiatAmount: '75.00',
    requestedFiatCurrency: 'EUR',
    destinationChainId: 8453,
    destinationToken: 'USDC',
    destinationAddress: '0x742d35Cc6634C0532925a3b844Bc9e7595f8fE71',
    successUrl: 'https://example.com/success',
    cancelUrl: 'https://example.com/cancel',
    notes: {
      orderId: 'order_12345',
      customerId: 'cust_67890',
    },
  },
  {
    apiBaseUrl: 'https://api.pay.peer.xyz',
    apiKey: process.env.ZKPAY_API_KEY!,
  }
);

console.log(checkout.order.id);
console.log(checkout.checkoutUrl);

Notes

• Quote selection uses the buyer-selected fiat currency.
• Payment rows persist currencyPerUsdRate for the selected payment currency.
• Legacy helpers are not exported.