Installation

Prerequisites

Before installing the SDK, ensure you have:

Node.js or Runtime

Node.js 16+ (for Node.js environments)
Bun, Deno, or any modern JavaScript runtime

TypeScript (Optional)

TypeScript 5.0+ recommended for the best experience
Works with JavaScript projects too

You’ll need a Paystack account and API keys. Get yours at paystack.com

Package Installation

Install the SDK using your preferred package manager:

npm install @efobi/paystack

yarn add @efobi/paystack

pnpm add @efobi/paystack

bun add @efobi/paystack

Install Peer Dependencies

The SDK requires Zod for runtime validation. Install it if you haven’t already:

npm install zod

yarn add zod

pnpm add zod

bun add zod

The SDK requires Zod ^4.0.0. If you’re using an older version, you may need to upgrade.

Environment Setup

Get Your API Keys

Paystack provides two types of secret keys:

Test keys (sk_test_...) - For development and testing
Live keys (sk_live_...) - For production use

Never commit your secret keys to version control. Always use environment variables.

Configure Environment Variables

Create a .env file in your project root:

.env

PAYSTACK_SECRET_KEY=sk_test_your_secret_key_here

Add .env to your .gitignore file to prevent accidentally committing secrets.

Environment-Specific Configuration

For different environments, use separate environment variables:

.env.example

# Development
PAYSTACK_SECRET_KEY=sk_test_your_test_key

# Production
PAYSTACK_SECRET_KEY=sk_live_your_live_key

TypeScript Configuration

Recommended tsconfig.json

For optimal TypeScript support, configure your tsconfig.json:

tsconfig.json

{
  "compilerOptions": {
    "target": "ES2020",
    "module": "ESNext",
    "moduleResolution": "node",
    "strict": true,
    "esModuleInterop": true,
    "skipLibCheck": true,
    "forceConsistentCasingInFileNames": true,
    "resolveJsonModule": true
  }
}

The SDK uses ES modules. Ensure your project is configured to support them.

Type Definitions

The SDK includes full TypeScript definitions. Import types as needed:

types.ts

import type { 
  Transaction,
  TransactionInitializeInput,
  TransactionResponse 
} from '@efobi/paystack';

Framework-Specific Setup

Node.js with Express

npm install express dotenv
npm install -D @types/express

index.ts

import express from 'express';
import dotenv from 'dotenv';
import { Paystack } from '@efobi/paystack';

dotenv.config();

const app = express();
const paystack = new Paystack(process.env.PAYSTACK_SECRET_KEY!);

app.use(express.json());

app.listen(3000, () => {
  console.log('Server running on port 3000');
});

Next.js (App Router)

No additional configuration needed. Use environment variables in .env.local:

.env.local

PAYSTACK_SECRET_KEY=sk_test_your_secret_key_here

app/api/payment/route.ts

import { Paystack } from '@efobi/paystack';

const paystack = new Paystack(process.env.PAYSTACK_SECRET_KEY!);

export async function POST(request: Request) {
  // Your payment logic here
}

Bun

Bun has built-in environment variable support:

index.ts

import { Paystack } from '@efobi/paystack';

const paystack = new Paystack(process.env.PAYSTACK_SECRET_KEY!);

Cloudflare Workers

Use Wrangler secrets for environment variables:

wrangler secret put PAYSTACK_SECRET_KEY

worker.ts

import { Paystack } from '@efobi/paystack';

export default {
  async fetch(request: Request, env: Env) {
    const paystack = new Paystack(env.PAYSTACK_SECRET_KEY);
    // Your logic here
  }
};

Deno

mod.ts

import { Paystack } from 'npm:@efobi/paystack';

const paystack = new Paystack(Deno.env.get('PAYSTACK_SECRET_KEY')!);

Verify Installation

Create a simple test file to verify your setup:

test.ts

import { Paystack } from '@efobi/paystack';

// This will throw an error if your key format is invalid
try {
  const paystack = new Paystack(process.env.PAYSTACK_SECRET_KEY!);
  console.log('✅ Paystack SDK initialized successfully!');
} catch (error) {
  console.error('❌ Initialization failed:', error.message);
}

Run the test:

node test.ts

bun run test.ts

deno run --allow-env test.ts

If you see “Invalid secret key” error, check that your key starts with sk_test_ or sk_live_.

Common Issues

Module not found errors

Ensure you’ve installed both @efobi/paystack and zod:

npm install @efobi/paystack zod

Invalid secret key error

The SDK validates that your key starts with sk_test_ or sk_live_. Check your environment variables:

console.log('Key format:', process.env.PAYSTACK_SECRET_KEY?.substring(0, 8));

TypeScript errors

Ensure you’re using TypeScript 5.0 or higher:

npm install -D typescript@latest

ESM import issues

If you’re using CommonJS, ensure your package.json has:

{
  "type": "module"
}

Or use .mjs file extensions.

Next Steps

Now that you have the SDK installed, you’re ready to build your first integration:

Quick Start Guide

Learn how to initialize transactions and verify payments

Get Started

Core Concepts

Guides

Prerequisites

Node.js or Runtime

TypeScript (Optional)

Package Installation

Install Peer Dependencies

Environment Setup

Get Your API Keys

Configure Environment Variables

Environment-Specific Configuration

TypeScript Configuration

Recommended tsconfig.json

Type Definitions

Framework-Specific Setup

Node.js with Express

Next.js (App Router)

Bun

Cloudflare Workers

Deno

Verify Installation

Common Issues

Next Steps

Quick Start Guide

​Prerequisites

Node.js or Runtime

TypeScript (Optional)

​Package Installation

​Install Peer Dependencies

​Environment Setup

​Get Your API Keys

​Configure Environment Variables

​Environment-Specific Configuration

​TypeScript Configuration

​Recommended tsconfig.json

​Type Definitions

​Framework-Specific Setup

​Node.js with Express

​Next.js (App Router)

​Bun

​Cloudflare Workers

​Deno

​Verify Installation

​Common Issues

​Next Steps

Quick Start Guide

Prerequisites

Package Installation

Install Peer Dependencies

Environment Setup

Get Your API Keys

Configure Environment Variables

Environment-Specific Configuration

TypeScript Configuration

Recommended tsconfig.json

Type Definitions

Framework-Specific Setup

Node.js with Express

Next.js (App Router)

Bun

Cloudflare Workers

Deno

Verify Installation

Common Issues

Next Steps