Skip to main content
The Paystack TypeScript SDK uses API keys to authenticate requests. All API requests must include a valid secret key to interact with the Paystack API.

​
Getting Your API Keys

To use the SDK, you’ll need to obtain your API keys from the Paystack Dashboard:
1

Log in to Paystack

Visit https://dashboard.paystack.com and sign in to your account.
2

Navigate to Settings

Click on Settings in the sidebar, then select API Keys & Webhooks.
3

Copy Your Secret Key

You’ll see both your Test and Live secret keys. Copy the appropriate key for your environment.
Never expose your secret keys in client-side code, public repositories, or version control systems. Secret keys should only be used server-side.

​
Test vs Live Keys

Paystack provides two types of secret keys to separate development and production environments:

Test Keys

  • Prefix: sk_test_
  • Use for development and testing
  • No real money is processed
  • Safe to experiment with

Live Keys

  • Prefix: sk_live_
  • Use for production
  • Processes real transactions
  • Requires extra security measures

​
Key Format Validation

The SDK automatically validates your API key format when initializing the Paystack client. Here’s the validation logic from src/index.ts:34-42:
src/index.ts
const secretKeySchema = z
  .string()
  .startsWith("sk_live_")
  .or(z.string().startsWith("sk_test_"));
  
if (!secretKeySchema.safeParse(secretKey).success) {
  throw new Error(
    "Invalid secret key. It must start with 'sk_live_' or 'sk_test_'.",
  );
}
If you provide a key that doesn’t start with either prefix, the SDK will throw an error immediately.

​
Basic Setup

Initialize the SDK by passing your secret key to the Paystack constructor: 
import { Paystack } from '@efobi/paystack';

const paystack = new Paystack('sk_test_your_secret_key_here');
The constructor validates the key format and throws an error if invalid: 
// ✅ Valid - will work
const paystack = new Paystack('sk_test_abc123...');
const paystack = new Paystack('sk_live_xyz789...');

// ❌ Invalid - will throw error
const paystack = new Paystack('invalid_key'); // Error: Invalid secret key
const paystack = new Paystack('pk_test_...');  // Error: Invalid secret key (public key)

​
Environment Variables

The recommended approach is to store your API keys in environment variables rather than hardcoding them: 
# Development environment
PAYSTACK_SECRET_KEY=sk_test_your_test_key_here

# Production environment
# PAYSTACK_SECRET_KEY=sk_live_your_live_key_here

​
Environment-Based Configuration

You can dynamically select keys based on your environment: 
import { Paystack } from '@efobi/paystack';

const secretKey = process.env.NODE_ENV === 'production'
  ? process.env.PAYSTACK_LIVE_KEY!
  : process.env.PAYSTACK_TEST_KEY!;

const paystack = new Paystack(secretKey);

​
How Authentication Works

Under the hood, the SDK uses Bearer token authentication. From src/main/fetcher.ts:38-39:
src/main/fetcher.ts
const init: RequestInit = {
  method,
  headers: {
    Authorization: `Bearer ${this.secretKey}`,
  },
};
Every API request automatically includes your secret key in the Authorization header. You don’t need to manually add authentication to individual requests.

​
Security Best Practices

Add .env files to your .gitignore:
.gitignore
.env
.env.local
.env.*.local
Use environment variables or secret management services instead.
Maintain separate API keys for:
  • Local development (test key)
  • Staging/QA (test key)
  • Production (live key)
This prevents accidental charges during testing.
Periodically regenerate your API keys, especially if:
  • A team member with access leaves
  • You suspect a key may have been compromised
  • As part of routine security maintenance
You can regenerate keys from the Paystack Dashboard without downtime by updating both old and new keys simultaneously.
  • Limit which team members can view live keys
  • Use secret management tools (AWS Secrets Manager, HashiCorp Vault, etc.)
  • Never log or display secret keys in application logs
  • Avoid sending keys via email or chat
Secret keys should never be used in:
  • Frontend JavaScript (React, Vue, etc.)
  • Mobile apps (iOS, Android)
  • Browser extensions
  • Any client-side code
Always make Paystack API calls from your backend server.

​
Multi-Account Support

If you need to work with multiple Paystack accounts, create separate instances: 
import { Paystack } from '@efobi/paystack';

const mainAccount = new Paystack(process.env.PAYSTACK_MAIN_KEY!);
const subAccount = new Paystack(process.env.PAYSTACK_SUB_KEY!);

// Use different instances for different accounts
const mainTxn = await mainAccount.transaction.initialize({
  email: 'customer@example.com',
  amount: '50000'
});

const subTxn = await subAccount.transaction.initialize({
  email: 'customer@example.com',
  amount: '25000'
});

​
Troubleshooting

Cause: The provided key doesn’t start with sk_test_ or sk_live_.Solution:
  • Verify you’re using the secret key, not the public key (which starts with pk_)
  • Check for typos or extra whitespace
  • Ensure the key is copied completely from the dashboard
// ❌ Wrong - using public key
const paystack = new Paystack('pk_test_...');

// ✅ Correct - using secret key
const paystack = new Paystack('sk_test_...');
Cause: The API key is invalid, expired, or doesn’t have permission.Solution:
  • Verify the key is still active in your Paystack Dashboard
  • Check if you’re using the correct environment (test vs live)
  • Regenerate the key if necessary
Cause: The environment variable isn’t loaded or is undefined.Solution:
  • Ensure your .env file is in the correct location
  • Check if you need to install dotenv (Node.js): npm install dotenv
  • Load environment variables: import 'dotenv/config' (Node.js)
  • Restart your development server after changing .env

​
Next Steps

Error Handling

Learn how to handle API errors and validation issues

Type Safety

Understand TypeScript types and runtime validation