Skip to main content

TypeScript Types

All types are available from the @zkp2p-pay/shared package.

npm install @zkp2p-pay/shared
import type {
  CheckoutSession,
  Order,
  WebhookPayload,
  // ...
} from '@zkp2p-pay/shared';

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;
  activeOrderId?: string | null;
  createdAt: string;
  updatedAt: string;
  merchant?: {
    id: string;
    name: string;
    displayName?: string | null;
    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;
  cancelTx?: string | null;
  cancelledAt?: string | null;
  cancelReason?: string | null;
  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;
  displayName?: string | null;
  logoUrl?: string | null;
  apiKey: string;
  createdAt: string;
  updatedAt: string;
};

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​

type CreateSessionRequest = {
  merchantId: string;
  amountUsdc: string;
  destinationChainId: number;
  destinationToken: string;
  recipientAddress: string;
  successUrl?: string;
  cancelUrl?: string;
  metadata?: Record<string, string>;
};

type CreateSessionResponse = {
  session: CheckoutSession;
  checkoutUrl: string;
};

Start Session​

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

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

Fulfill Intent​

type FulfillIntentRequest = {
  intentHash: string;
  proof: Record<string, unknown> | string;
};

type FulfillIntentResponse = {
  order: Order;
  proofAttemptId: string;
  txHash: string;
};

type FulfillIntentError = {
  proofAttemptId: string;
  errorCode?: string;
  errorMessage: string;
  canRetry: boolean;
};

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​

See Order Status and Payment Platforms for enum values.