SDK Overview

The @zendfi/sdk package gives you a fully-typed TypeScript client for the ZendFi API. It handles authentication, retries, idempotency, and environment detection automatically — install it and start accepting payments in under a minute.

Installation

npm install @zendfi/sdk

pnpm add @zendfi/sdk

yarn add @zendfi/sdk

Quick Start

import { ZendFiClient } from '@zendfi/sdk';

const zendfi = new ZendFiClient({
  apiKey: process.env.ZENDFI_API_KEY,
});

const payment = await zendfi.createPayment({
  amount: 25.00,
  description: 'My first payment',
});

console.log(payment.payment_url);

Zero-Config Design

The SDK reads configuration from multiple sources in this order:

Explicit Options

Values passed directly to the ZendFiClient constructor take highest priority.

Environment Variables

ZENDFI_API_KEY, NEXT_PUBLIC_ZENDFI_API_KEY, and REACT_APP_ZENDFI_API_KEY are checked automatically.

CLI Credentials

If you ran zendfi init, your key is stored in ~/.zendfi/credentials.json and loaded automatically.

Auto-Detection

The SDK detects your environment and mode from context:

Signal	Detection
`zfi_test_` prefix	Test mode (Solana Devnet)
`zfi_live_` prefix	Live mode (Solana Mainnet)
`NODE_ENV=production`	Production environment
`localhost` hostname	Development environment

Singleton vs Custom Instance

The SDK exports both a singleton and a constructor:

// Singleton -- auto-configured from environment
import { zendfi } from '@zendfi/sdk';
const payment = await zendfi.createPayment({ amount: 10 });

// Custom instance -- explicit configuration
import { ZendFiClient } from '@zendfi/sdk';
const client = new ZendFiClient({ apiKey: 'zfi_test_...' });
const payment = await client.createPayment({ amount: 10 });

The singleton throws a helpful error if ZENDFI_API_KEY is not set:

ZendFi singleton not initialized. Set ZENDFI_API_KEY environment 
variable or create a custom instance: new ZendFiClient({ apiKey: "..." })

Package Exports

The SDK exports everything you need from a single entry point:

import {
  // Client
  ZendFiClient,
  zendfi,

  // Types
  type Payment,
  type PaymentLink,
  type Subscription,
  type Invoice,
  type InstallmentPlan,
  type ZendFiConfig,

  // Branded IDs
  asPaymentId,
  asMerchantId,
  asInvoiceId,

  // Errors
  ZendFiError,
  AuthenticationError,
  PaymentError,
  ValidationError,

  // Embedded Checkout
  ZendFiEmbeddedCheckout,

  // Webhooks
  processWebhook,

  // Interceptors
  InterceptorManager,
} from '@zendfi/sdk';

What’s Next

Client Reference

Full method reference for ZendFiClient.

Sub Accounts

Sub-account lifecycle, delegation tokens, programmable controls, and scoped transfer methods.

Types

All type definitions and branded IDs.

Errors

Error classes and handling patterns.

Embedded Checkout

Drop-in payment UI component.

Sub-Account Programmable Controls

The SDK supports full programmable-controls parity with backend APIs.

​SDK Overview

​Installation

​Quick Start

​Zero-Config Design

​Auto-Detection

​Singleton vs Custom Instance

​Package Exports

​What’s Next