Types

Type definitions, branded IDs, and enums for the ZendFi SDK.

Types

The SDK provides full TypeScript type coverage for every API request and response. It also uses branded types to prevent accidentally mixing up different ID strings.

Branded IDs

Branded types add compile-time safety to string IDs. A PaymentId cannot be accidentally passed where a MerchantId is expected, even though both are strings at runtime.

import { asPaymentId, asMerchantId } from '@zendfi/sdk';

const paymentId = asPaymentId('pay_test_abc123');
const merchantId = asMerchantId('merch_xyz789');

// These are type-safe at compile time
await zendfi.getPayment(paymentId);   // works
await zendfi.getPayment(merchantId);  // type error

Available Branded Types

Type	Factory	Example
PaymentId	asPaymentId()	pay_test_abc123
MerchantId	asMerchantId()	merch_xyz789
InvoiceId	asInvoiceId()	inv_test_abc123
SubscriptionId	asSubscriptionId()	sub_abc123
InstallmentPlanId	asInstallmentPlanId()	inst_abc123
PaymentLinkCode	asPaymentLinkCode()	link_abc123

How Branding Works

type Brand<T, B> = T & { __brand: B };
type PaymentId = Brand<string, 'PaymentId'>;

The __brand property is a phantom type — it exists only in the type system and has zero runtime overhead. You can still use branded IDs as regular strings:

const id = asPaymentId('pay_test_abc123');
console.log(id);           // "pay_test_abc123"
console.log(id.length);    // 17
console.log(`ID: ${id}`);  // "ID: pay_test_abc123"

---

Enums

Environment

type Environment = 'development' | 'staging' | 'production';

ApiKeyMode

type ApiKeyMode = 'test' | 'live';

Currency

type Currency = 'USD' | 'EUR' | 'GBP';

PaymentToken

type PaymentToken = 'SOL' | 'USDC' | 'USDT';

Status Types

type PaymentStatus = 'pending' | 'confirmed' | 'failed' | 'expired';
type SubscriptionStatus = 'active' | 'canceled' | 'past_due' | 'paused';
type InstallmentPlanStatus = 'active' | 'completed' | 'defaulted' | 'cancelled';
type InvoiceStatus = 'draft' | 'sent' | 'paid';
type SplitStatus = 'pending' | 'processing' | 'completed' | 'failed' | 'refunded';

---

Configuration

ZendFiConfig

interface ZendFiConfig {
  apiKey?: string;
  baseURL?: string;
  environment?: Environment;
  mode?: ApiKeyMode;
  timeout?: number;        // default: 30000
  retries?: number;        // default: 3
  idempotencyEnabled?: boolean;  // default: true
  debug?: boolean;         // default: false
}

---

Request Types

CreatePaymentRequest

interface CreatePaymentRequest {
  amount: number;
  currency?: Currency;          // default: 'USD'
  token?: PaymentToken;         // default: 'USDC'
  description?: string;
  customer_email?: string;
  redirect_url?: string;
  metadata?: Record<string, any>;
  split_recipients?: SplitRecipient[];
}

CreatePaymentLinkRequest

interface CreatePaymentLinkRequest {
  amount: number;
  currency?: string;
  token?: string;
  description?: string;
  max_uses?: number;
  expires_at?: string;          // ISO 8601
  metadata?: Record<string, any>;
  onramp?: boolean;             // enable fiat on-ramp
  amount_ngn?: number;          // NGN amount for exact conversion
  payer_service_charge?: boolean; // add service charge to payer
}

CreateSubscriptionPlanRequest

interface CreateSubscriptionPlanRequest {
  name: string;
  description?: string;
  amount: number;
  currency?: Currency;
  interval: 'daily' | 'weekly' | 'monthly' | 'yearly';
  interval_count?: number;      // default: 1
  trial_days?: number;          // default: 0
  metadata?: Record<string, any>;
}

CreateSubscriptionRequest

interface CreateSubscriptionRequest {
  plan_id: string;
  customer_email: string;
  customer_wallet?: string;
  metadata?: Record<string, any>;
}

CreateInstallmentPlanRequest

interface CreateInstallmentPlanRequest {
  customer_wallet: string;
  customer_email?: string;
  total_amount: number;
  installment_count: number;
  first_payment_date?: string;  // ISO 8601, default: tomorrow
  payment_frequency_days: number;
  description?: string;
  late_fee_amount?: number;
  grace_period_days?: number;   // default: 7
  metadata?: Record<string, any>;
}

CreateInvoiceRequest

interface CreateInvoiceRequest {
  customer_email: string;
  customer_name?: string;
  amount: number;
  token?: PaymentToken;
  description: string;
  line_items?: InvoiceLineItem[];
  due_date?: string;            // ISO 8601
  metadata?: Record<string, any>;
}

SplitRecipient

interface SplitRecipient {
  recipient_wallet: string;
  recipient_name?: string;
  percentage?: number;          // 0-100, sum must equal 100
  fixed_amount_usd?: number;    // alternative to percentage
  split_order?: number;
}

---

Response Types

Payment

interface Payment {
  id: string;
  merchant_id: string;
  amount_usd?: number;
  amount?: number;
  currency?: string;
  payment_token?: PaymentToken;
  status: PaymentStatus;
  customer_wallet?: string;
  customer_email?: string;
  description?: string;
  checkout_url?: string;
  payment_url?: string;
  qr_code?: string;
  expires_at: string;
  confirmed_at?: string;
  transaction_signature?: string;
  metadata?: Record<string, any>;
  split_ids?: string[];
  created_at?: string;
  updated_at?: string;
}

PaymentLink

interface PaymentLink {
  link_code: string;
  merchant_id: string;
  title?: string;
  description?: string;
  amount: number;
  currency: string;
  payment_methods?: string[];
  redirect_url?: string;
  expires_at?: string;
  metadata?: Record<string, any>;
  payment_url: string;
  hosted_page_url: string;
  url: string;            // alias for hosted_page_url
  id?: string;
  token?: string;
  max_uses?: number;
  uses_count?: number;
  is_active?: boolean;
  onramp?: boolean;
  payer_service_charge?: boolean;
  created_at: string;
  updated_at: string;
}

Invoice

interface Invoice {
  id: string;
  invoice_number: string;
  merchant_id: string;
  customer_email: string;
  customer_name?: string;
  amount_usd: number;
  token: PaymentToken;
  description: string;
  line_items?: InvoiceLineItem[];
  status: InvoiceStatus;
  payment_url?: string;
  due_date?: string;
  created_at: string;
  updated_at: string;
}

Webhook Types

type WebhookEvent =
  | 'payment.created'
  | 'payment.confirmed'
  | 'payment.failed'
  | 'payment.expired'
  | 'subscription.created'
  | 'subscription.activated'
  | 'subscription.canceled'
  | 'subscription.payment_failed'
  | 'split.completed'
  | 'split.failed'
  | 'installment.due'
  | 'installment.paid'
  | 'installment.late'
  | 'invoice.sent'
  | 'invoice.paid';

interface WebhookPayload {
  event: WebhookEvent;
  timestamp: string;
  merchant_id: string;
  data: Payment | Subscription;
}

interface VerifyWebhookRequest {
  payload: string | object;
  signature: string;
  secret: string;
}

Pagination

interface PaginatedResponse<T> {
  data: T[];
  pagination: {
    page: number;
    limit: number;
    total: number;
    total_pages: number;
  };
}