TypeScript Types

All types are available from the @zkp2p-pay/shared package, or directly from the SDK.

npm install @zkp2p-pay/sdk

import type {
  CheckoutSession,
  CreateSessionRequest,
  CreateSessionResponse,
  // ...
} from '@zkp2p-pay/sdk';

Core Types

CheckoutSession

type CheckoutSession = {
  id: string;
  merchantId: string;
  amountUsdc: string;
  destinationChainId: number;
  destinationToken: string;
  recipientAddress: string;
  status: SessionStatusType;
  selectedPaymentPlatform?: PaymentPlatformType | null;
  selectedFiatCurrency?: string | null;
  successUrl?: string | null;
  cancelUrl?: string | null;
  metadata?: Record<string, string> | null;
  expiresAt?: string | null;
  activeOrderId?: string | null;

  // Checkout mode
  checkoutMode?: CheckoutModeType;
  fiatAmount?: string | null;
  fiatCurrency?: string | null;
  maxFeePercentage?: number | null;

  // Bridge fields (for cross-chain payments)
  requiresBridge?: boolean;
  bridgeInputAmount?: string | null;
  bridgeOutputAmount?: string | null;
  bridgeFeeAmount?: string | null;
  bridgeMinOutputAmount?: string | null;
  bridgeEstimatedTime?: number | null;

  // Payment platform restrictions
  enabledPaymentPlatforms?: PaymentPlatformType[] | null;

  createdAt: string;
  updatedAt: string;
  merchant?: {
    id: string;
    name: string;
    logoUrl?: string | null;
  } | null;
  activeOrder?: Order | null;
};

Order

type Order = {
  id: string;
  sessionId: string;
  merchantId: string;
  status: OrderStatusType;
  intentHash?: string | null;
  signalTx?: string | null;
  fulfillTx?: string | null;
  paymentPlatform?: PaymentPlatformType | null;
  fiatCurrency?: string | null;
  amountUsdc?: string | null;
  conversionRate?: string | null;
  recipient?: string | null;
  quote?: Quote | null;
  expiresAt?: string | null;
  currentProofId?: string | null;

  // Bridge execution tracking
  bridgeCommitmentData?: string | null;
  bridgeFulfillData?: string | null;
  bridgeDepositTxHash?: string | null;
  bridgeStatus?: 'pending' | 'filled' | 'expired' | null;
  bridgeFilledAt?: string | null;
  bridgeFilledTxHash?: string | null;

  // Cancellation
  cancelTx?: string | null;
  cancelledAt?: string | null;
  cancelReason?: string | null;

  // Error tracking
  errorCode?: string | null;
  errorMessage?: string | null;
  errorDetails?: Record<string, unknown> | null;
  failedAt?: string | null;

  createdAt: string;
  updatedAt: string;
};

Quote

type Quote = {
  fiatAmount: string;
  fiatAmountFormatted: string;
  tokenAmount: string;
  tokenAmountFormatted: string;
  paymentMethod: string;
  payeeAddress: string;
  conversionRate: string;
  intent: QuoteIntent;
  payeeData?: Record<string, string>;
};

type QuoteIntent = {
  depositId: string;
  processorName: string;
  amount: string;
  toAddress: string;
  payeeDetails: string;
  processorIntentData: Record<string, unknown>;
  fiatCurrencyCode: string;
  chainId: string;
};

Merchant

type Merchant = {
  id: string;
  name: string;
  logoUrl?: string | null;
  apiKey: string;

  // Checkout defaults
  defaultChainId?: number | null;
  defaultCheckoutMode?: CheckoutModeType | null;
  defaultMaxFeePercentage?: number | null;
  enabledPaymentPlatforms?: PaymentPlatformType[] | null;

  createdAt: string;
  updatedAt: string;
};

MerchantInfo

Public merchant information (excludes API key):

type MerchantInfo = {
  id: string;
  name: string;
  logoUrl?: string | null;
  /** EVM wallet address (0x...) for Base, Ethereum, and other EVM chains */
  privyWalletAddress?: string | null;
  /** Solana wallet address (base58) for Solana chain destinations */
  defaultSolanaAddress?: string | null;
  defaultChainId?: number | null;
  defaultCheckoutMode?: CheckoutModeType | null;
  defaultMaxFeePercentage?: number | null;
  enabledPaymentPlatforms?: string[] | null;
  createdAt: string;
  updatedAt: string;
};

BridgeInfo

Cross-chain bridge details:

type BridgeInfo = {
  required: boolean;
  inputAmount?: string | null;      // Amount on Base (includes fees)
  outputAmount?: string | null;     // Expected output after bridge
  feeAmount?: string | null;        // Total bridge fee
  minOutputAmount?: string | null;  // Merchant's requested amount
  estimatedTimeSeconds?: number | null;
};

ProofAttempt

type ProofAttempt = {
  id: string;
  orderId: string;
  intentHash: string;
  proof: Record<string, unknown>;
  submittedAt: string;
  status: ProofAttemptStatusType;
  verifiedAt?: string | null;
  attestationResponse?: Record<string, unknown> | null;
  verificationError?: string | null;
  verificationMessage?: string | null;
  txHash?: string | null;
  txSubmittedAt?: string | null;
  txConfirmedAt?: string | null;
  txError?: string | null;
};

Request/Response Types

Create Session

// Exact-token mode (default)
type CreateSessionExactTokenRequest = {
  merchantId: string;
  amountUsdc: string;
  destinationChainId: number;
  destinationToken: string;
  recipientAddress: string;
  successUrl?: string;
  cancelUrl?: string;
  metadata?: Record<string, string>;
  enabledPaymentPlatforms?: PaymentPlatformType[];
  checkoutMode?: 'exact-token';
};

// Exact-fiat mode
type CreateSessionExactFiatRequest = {
  merchantId: string;
  checkoutMode: 'exact-fiat';
  fiatAmount: string;
  fiatCurrency: string;
  maxFeePercentage?: number;
  destinationChainId: number;
  destinationToken: string;
  recipientAddress: string;
  successUrl?: string;
  cancelUrl?: string;
  metadata?: Record<string, string>;
  enabledPaymentPlatforms?: PaymentPlatformType[];
};

// Union type
type CreateSessionRequest =
  | CreateSessionExactTokenRequest
  | CreateSessionExactFiatRequest;

type CreateSessionResponse = {
  session: CheckoutSession;
  sessionToken: string;      // Required for checkout URL
  checkoutUrl: string;       // Pre-built checkout URL
  bridge?: BridgeInfo;       // Present for cross-chain payments
};

Start Session

type StartSessionRequest = {
  paymentPlatform?: PaymentPlatformType;
  fiatCurrency?: string;
};

type StartSessionResponse = {
  session: CheckoutSession;
  order: Order;
  quote: Quote;
  intentHash: string;
  expiresAt?: string | null;
};

Webhook Types

WebhookPayload

type WebhookPayload = {
  id: string;
  type: WebhookEventTypeValue;
  timestamp: string;
  data: {
    session: CheckoutSession;
    order?: Order | null;
    txHash?: string | null;
    error?: {
      code: string;
      message: string;
    } | null;
  };
};

Webhook

type Webhook = {
  id: string;
  merchantId: string;
  url: string;
  events: WebhookEventTypeValue[];
  active: boolean;
  createdAt: string;
  updatedAt: string;
};

type WebhookWithSecret = Webhook & {
  secret: string;
};

type WebhookDelivery = {
  id: string;
  webhookId: string;
  eventType: WebhookEventTypeValue;
  eventId: string;
  status: WebhookDeliveryStatusType;
  attempts: number;
  lastAttemptAt?: string | null;
  nextRetryAt?: string | null;
  responseCode?: number | null;
  createdAt: string;
};

Enums and Constants

CheckoutMode

const CheckoutMode = {
  EXACT_TOKEN: 'exact-token',  // Merchant specifies USDC amount
  EXACT_FIAT: 'exact-fiat',    // Merchant specifies fiat amount
} as const;

type CheckoutModeType = typeof CheckoutMode[keyof typeof CheckoutMode];

SupportedChains

const SupportedChains = {
  8453: 'Base',           // Origin chain
  1: 'Ethereum',
  10: 'Optimism',
  42161: 'Arbitrum',
  137: 'Polygon',
  324: 'zkSync Era',
  59144: 'Linea',
  534352: 'Scroll',
  999: 'HyperEVM',
  34268394551451: 'Solana',  // Non-EVM
} as const;

type SupportedChainId = keyof typeof SupportedChains;

PaymentPlatform

const PaymentPlatform = {
  VENMO: 'venmo',
  CASHAPP: 'cashapp',
  REVOLUT: 'revolut',
  WISE: 'wise',
  ZELLE: 'zelle',
  PAYPAL: 'paypal',
  MONZO: 'monzo',
  N26: 'n26',
} as const;

type PaymentPlatformType = typeof PaymentPlatform[keyof typeof PaymentPlatform];

See Order Status and Payment Platforms for more details on status values and platform support.