SDK API Reference

const ramp = createRampClient({
  environment: "production" | "staging",
  partnerId: string,           // 1-64 chars [A-Za-z0-9_-]
  sendStore?: ZecSendStore,    // required when supplying onZecSendRequest
  apiBaseUrl?: string,         // https origin; required for staging
  paneOrigins?: string[],      // exact https origins
  requestTimeoutMs?: number,   // default 15000; bounds fetch + body
  locale?: "pt" | "en" | "es" | "hi" | "id",
  logger?: Logger,
  fetch?: typeof globalThis.fetch,
});

interface CreateSessionInput {
  idempotencyKey?: string;     // 32-128 chars [A-Za-z0-9_-]
  direction: "sell" | "buy";
  asset: "ZEC";
  fiat: string;                // ISO 4217
  amountAsset?: string;        // display hint
  zecReceiver?: string;        // BUY: transparent t-addr
  returnUrl?: string;          // <= 2048 chars; letter-first scheme (RFC 3986) or https
  partnerSessionId?: string;
}

// Returns:
interface RampSession {
  sessionUrl: string;
  sessionRef: string;
  statusTicket: string;
  expiresAt: string;           // ISO 8601
}

interface PaneBridgeHandlers {
  transport: PaneTransport;
  sessionRef?: string;         // defaults to most recent session
  onZecSendRequest?: (request: ZecSendRequestPayload, ctx: { signal: AbortSignal }) => Promise<ZecSendOutcome>;
  onReady?: (ready: unknown) => void;
  onResult?: (result: unknown) => void;
  onSendRecoveryRequired?: (info: { reason: string; txids?: string[] }) => void;
  onClose?: () => void;
  onProtocolError?: (error: PspError) => void;
}

interface PaneTransport {
  post(message: unknown): void;
  subscribe(handler: (raw: unknown) => void): () => void;
}

interface SessionStatus {
  outcome: "created" | "opened" | "user-active"
         | "settled" | "failed" | "expired" | "cancelled";
  terminal: boolean;
  zecTxids?: string[];
  fiat?: { currency: string; amountDisplay: string };
  updatedAt: string;
}

interface ParsedReturnUrl {
  sessionRef: string | null;
  outcome: "settled" | "failed" | "expired" | "cancelled" | null;
  claimsTerminal: boolean;
  params: URLSearchParams;
}

type ParsedZecSendHandoff = ZecSendRequestPayload & { sessionRef: string };

interface ZecSendResumeEvidence {
  txid?: string;     // identified deposit transaction
  txids?: string[];  // 1-32 related transaction IDs
}

interface ZecSendRequestPayload {
  requestId: string;       // stable across reconnects
  address: string;         // transparent t-addr
  amountZat: string;       // integer zatoshi (10^-8 ZEC) as string
  memo?: string;
}