> ## Documentation Index
> Fetch the complete documentation index at: https://paystack-sdk.efobi.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# Installation

> Install and configure the Paystack TypeScript SDK in your project

## Prerequisites

Before installing the SDK, ensure you have:

<CardGroup cols={2}>
  <Card title="Node.js or Runtime">
    * Node.js 16+ (for Node.js environments)
    * Bun, Deno, or any modern JavaScript runtime
  </Card>

  <Card title="TypeScript (Optional)">
    * TypeScript 5.0+ recommended for the best experience
    * Works with JavaScript projects too
  </Card>
</CardGroup>

<Note>
  You'll need a Paystack account and API keys. Get yours at [paystack.com](https://paystack.com)
</Note>

## Package Installation

Install the SDK using your preferred package manager:

<CodeGroup>
  ```bash npm theme={null}
  npm install @efobi/paystack
  ```

  ```bash yarn theme={null}
  yarn add @efobi/paystack
  ```

  ```bash pnpm theme={null}
  pnpm add @efobi/paystack
  ```

  ```bash bun theme={null}
  bun add @efobi/paystack
  ```
</CodeGroup>

## Install Peer Dependencies

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

<CodeGroup>
  ```bash npm theme={null}
  npm install zod
  ```

  ```bash yarn theme={null}
  yarn add zod
  ```

  ```bash pnpm theme={null}
  pnpm add zod
  ```

  ```bash bun theme={null}
  bun add zod
  ```
</CodeGroup>

<Tip>
  The SDK requires Zod ^4.0.0. If you're using an older version, you may need to upgrade.
</Tip>

## 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

<Warning>
  Never commit your secret keys to version control. Always use environment variables.
</Warning>

### Configure Environment Variables

Create a `.env` file in your project root:

```bash .env theme={null}
PAYSTACK_SECRET_KEY=sk_test_your_secret_key_here
```

<Tip>
  Add `.env` to your `.gitignore` file to prevent accidentally committing secrets.
</Tip>

### Environment-Specific Configuration

For different environments, use separate environment variables:

```bash .env.example theme={null}
# 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`:

```json tsconfig.json theme={null}
{
  "compilerOptions": {
    "target": "ES2020",
    "module": "ESNext",
    "moduleResolution": "node",
    "strict": true,
    "esModuleInterop": true,
    "skipLibCheck": true,
    "forceConsistentCasingInFileNames": true,
    "resolveJsonModule": true
  }
}
```

<Note>
  The SDK uses ES modules. Ensure your project is configured to support them.
</Note>

### Type Definitions

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

```typescript types.ts theme={null}
import type { 
  Transaction,
  TransactionInitializeInput,
  TransactionResponse 
} from '@efobi/paystack';
```

## Framework-Specific Setup

### Node.js with Express

```bash theme={null}
npm install express dotenv
npm install -D @types/express
```

```typescript index.ts theme={null}
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`:

```bash .env.local theme={null}
PAYSTACK_SECRET_KEY=sk_test_your_secret_key_here
```

```typescript app/api/payment/route.ts theme={null}
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:

```typescript index.ts theme={null}
import { Paystack } from '@efobi/paystack';

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

### Cloudflare Workers

Use Wrangler secrets for environment variables:

```bash theme={null}
wrangler secret put PAYSTACK_SECRET_KEY
```

```typescript worker.ts theme={null}
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

```typescript mod.ts theme={null}
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:

```typescript test.ts theme={null}
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:

<CodeGroup>
  ```bash node theme={null}
  node test.ts
  ```

  ```bash bun theme={null}
  bun run test.ts
  ```

  ```bash deno theme={null}
  deno run --allow-env test.ts
  ```
</CodeGroup>

<Tip>
  If you see "Invalid secret key" error, check that your key starts with `sk_test_` or `sk_live_`.
</Tip>

## Common Issues

<AccordionGroup>
  <Accordion title="Module not found errors">
    Ensure you've installed both `@efobi/paystack` and `zod`:

    ```bash theme={null}
    npm install @efobi/paystack zod
    ```
  </Accordion>

  <Accordion title="Invalid secret key error">
    The SDK validates that your key starts with `sk_test_` or `sk_live_`. Check your environment variables:

    ```typescript theme={null}
    console.log('Key format:', process.env.PAYSTACK_SECRET_KEY?.substring(0, 8));
    ```
  </Accordion>

  <Accordion title="TypeScript errors">
    Ensure you're using TypeScript 5.0 or higher:

    ```bash theme={null}
    npm install -D typescript@latest
    ```
  </Accordion>

  <Accordion title="ESM import issues">
    If you're using CommonJS, ensure your `package.json` has:

    ```json theme={null}
    {
      "type": "module"
    }
    ```

    Or use `.mjs` file extensions.
  </Accordion>
</AccordionGroup>

## Next Steps

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

<Card title="Quick Start Guide" icon="rocket" href="/quickstart">
  Learn how to initialize transactions and verify payments
</Card>