@getblitz/shared-types

Shared TypeScript types for GetBlitz Payment Gateway — a self-hosted payment gateway for SEPA instant transfers across Europe.

Overview

This package provides shared TypeScript type definitions and Zod schemas used across the GetBlitz ecosystem. It ensures type safety and consistency between the server, client SDK, and any integrations.

Installation

npm install @getblitz/shared-types zod
# or
pnpm add @getblitz/shared-types zod
# or
yarn add @getblitz/shared-types zod

Note: zod is a required peer dependency (^3.24.0).

Usage

API Types

Types and schemas for the GetBlitz REST API:

import {
  CreateChallengeRequest,
  CreateChallengeRequestSchema,
  CreateChallengeResponse,
  CreateChallengeResponseSchema,
  PaymentSessionDetails,
  PaymentSessionDetailsSchema,
} from "@getblitz/shared-types";

// Validate request payload
const payload: CreateChallengeRequest = {
  amount: 500, // €5.00 in cents
  currency: "EUR",
  merchantReferenceId: "order-123", // Your own reference ID
  metadata: { orderId: "order_123" },
};

const validated = CreateChallengeRequestSchema.parse(payload);

Event Types

Types for real-time payment events via WebSocket/Redis pub-sub:

import {
  PAYMENT_EVENTS_CHANNEL,
  PaymentEvent,
  PaymentEventSchema,
  PaymentEventType,
} from "@getblitz/shared-types";

// Type-safe event handling
function handlePaymentEvent(event: PaymentEvent) {
  switch (event.type) {
    case "PAYMENT_SUCCESS":
      console.log("Payment confirmed:", event.sessionId);
      break;
    case "PAYMENT_FAILED":
      console.error("Payment failed:", event.sessionId);
      break;
    case "PAYMENT_EXPIRED":
      console.warn("Payment expired:", event.sessionId);
      break;
  }
}

SDK Configuration Types

Types for configuring the GetBlitz client SDK:

import {
  GetBlitzClientConfig,
  GetBlitzClientConfigSchema,
  GetBlitzEventCallbacks,
} from "@getblitz/shared-types";

// SDK configuration
const config: GetBlitzClientConfig = {
  sessionId: "550e8400-e29b-41d4-a716-446655440000",
  clientToken: "ey...", // From Create Challenge response
  apiUrl: "https://pay.example.com",
  wssUrl: "wss://wss.example.com",
  theme: "dark",
  locale: "de-DE",
};

// Validate configuration
const validatedConfig = GetBlitzClientConfigSchema.parse(config);

API Reference

API Types

| Type | Description | | ------------------------- | ----------------------------------------------------- | | CreateChallengeRequest | Request payload for creating a payment challenge | | CreateChallengeResponse | Response containing session ID, reference, and URL | | PaymentSessionDetails | Full session details for rendering the payment widget |

CreateChallengeRequest

interface CreateChallengeRequest {
  amount: number; // Amount in cents (e.g., 500 = €5.00)
  currency?: "EUR" | "USDC"; // Currency (default: EUR)
  bankAccountId?: string; // Specific bank account UUID
  merchantReferenceId?: string; // Your own reference ID (unique per org, max 64 chars)
  metadata?: Record<string, string>; // Optional merchant metadata
}

CreateChallengeResponse

interface CreateChallengeResponse {
  sessionId: string; // UUID of the payment session
  referenceId: string; // Bank reference (max 35 chars)
  merchantReferenceId?: string; // Your own reference ID (if provided)
  paymentUrl: string; // URL to redirect customer
  expiresAt: Date; // Session expiration time
}

PaymentSessionDetails

interface PaymentSessionDetails {
  sessionId: string;
  referenceId: string;
  amountCents: number;
  currency: "EUR";
  status: "PENDING" | "PAID" | "FAILED" | "EXPIRED";
  expiresAt: Date;
  organization: {
    name: string;
  };
  bankAccount: {
    providerId: string;
    accountName: string;
    iban: string;
  };
}

Event Types

| Type | Description | | ------------------ | ---------------------------------------------- | | PaymentEvent | Real-time payment status update event | | PaymentEventType | Enum of event types (SUCCESS, FAILED, EXPIRED) |

PaymentEvent

interface PaymentEvent {
  type: "PAYMENT_SUCCESS" | "PAYMENT_FAILED" | "PAYMENT_EXPIRED";
  referenceId: string; // Bank reference ID
  sessionId: string; // Payment session UUID
  status: "PENDING" | "PAID" | "FAILED" | "EXPIRED";
  clientToken?: string; // Proof of payment for the buyer
  timestamp: string; // ISO 8601 timestamp
}

Webhook Types

| Type | Description | | ------------------------ | ------------------------------------------------ | | MerchantWebhookPayload | Payload sent to merchant webhook endpoints | | WebhookEventType | Event types (payment.success, .failed, .expired) |

MerchantWebhookPayload

interface MerchantWebhookPayload {
  event: "payment.success" | "payment.failed" | "payment.expired";
  sessionId: string;
  referenceId: string;
  merchantReferenceId?: string; // Your own reference ID
  amountCents: number;
  currency: string;
  provider: string;
  clientToken?: string;
  timestamp: string;
  bankAccount: {
    connectionId: string; // Bank connection UUID
    connectionName: string; // Display name for the connection
    accountName: string; // Bank account name
    iban: string; // IBAN
    bic: string; // BIC/SWIFT code
  };
}

SDK Configuration Types

| Type | Description | | ------------------------ | -------------------------------------- | | GetBlitzClientConfig | Configuration for initializing the SDK | | GetBlitzEventCallbacks | Callback definitions for SDK events |

GetBlitzClientConfig

interface GetBlitzClientConfig {
  apiKey?: string; // Public API key (pk_live_...)
  sessionId: string; // Payment session ID (required)
  clientToken: string; // Auth token from Challenge response (required)
  wssUrl?: string; // WebSocket server URL
  apiUrl?: string; // API base URL
  theme?: "light" | "dark" | "auto"; // Widget theme
  locale?: string; // Locale for i18n (e.g., "de-DE")
}

GetBlitzEventCallbacks

interface GetBlitzEventCallbacks {
  onSuccess?: (token: string) => void; // Payment successful
  onError?: (error: Error) => void; // Payment failed
  onExpired?: () => void; // Session expired
  onCancel?: () => void; // User cancelled
}

Constants

| Constant | Value | Description | | ------------------------ | ------------------ | -------------------------- | | PAYMENT_EVENTS_CHANNEL | "payment_events" | Redis pub/sub channel name |

Zod Schemas

All types have corresponding Zod schemas for runtime validation:

• CreateChallengeRequestSchema
• CreateChallengeResponseSchema
• PaymentSessionDetailsSchema
• PaymentEventSchema
• PaymentEventTypeSchema
• GetBlitzClientConfigSchema
• MerchantWebhookPayloadSchema
• WebhookEventTypeSchema

Related Packages

• @getblitz/client — Embeddable payment SDK for merchant integration

Links

• GitHub Repository
• Documentation
• Report Issues

License

MIT © GetBlitz