Skip to main content

​
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

​
Install Peer Dependencies

The SDK requires Zod for runtime validation. Install it if you haven’t already: 
npm install 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

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
If you see “Invalid secret key” error, check that your key starts with sk_test_ or sk_live_.

​
Common Issues

Ensure you’ve installed both @efobi/paystack and zod:
npm install @efobi/paystack zod
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));
Ensure you’re using TypeScript 5.0 or higher:
npm install -D typescript@latest
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