@codepunter-labs/mock-paystack

Mock SDK for Paystack API. Provides fully-typed mock implementations for testing Paystack payment integrations without making real API calls.

Installation

npm install @codepunter-labs/mock-paystack

Features

• Transactions: Initialize, verify, and list transactions
• Customers: Create, update, and manage customers
• Plans: Create and manage subscription plans
• Subscriptions: Create and manage subscriptions
• Invoices: Create and manage invoices
• Transfers: Initiate transfers, list transfer recipients
• Banks: List supported banks and verify account numbers
• Type-safe: Full TypeScript support with accurate API types
• Test Framework Agnostic: Works with Jest, Vitest, and other spy-based frameworks

Repository

• GitHub: https://github.com/DERRICK-TORKORNOO/mock-sdks/tree/main/packages/mock-paystack
• Source Code: src/
• Tests: tests/

Usage

Basic Setup

import { vi } from 'vitest';
import { createMockPaystack } from '@codepunter-labs/mock-paystack';

const paystack = createMockPaystack({ spy: vi.fn });

Using with Jest

import { createMockPaystack } from '@codepunter-labs/mock-paystack';

const paystack = createMockPaystack({ spy: jest.fn });

Example: Initialize Transaction

// Default behavior - returns realistic mock data
const result = await paystack.transaction.initialize({
  amount: 50000,
  email: '[email protected]',
  currency: 'GHS',
  reference: 'ref_123456'
});

console.log(result.data.authorization_url);
// https://paystack.com/pay/ref_123456

Example: Verify Transaction

const result = await paystack.transaction.verify('ref_123456');

console.log(result.data.status);
// 'success'

Example: Create Customer

const result = await paystack.customer.create({
  email: '[email protected]',
  first_name: 'John',
  last_name: 'Doe',
  phone: '+233544919953'
});

Example: List Transactions

const result = await paystack.transaction.list({
  perPage: 50,
  page: 1
});

console.log(result.data.length);
// 50

Example: Override Mock Response

import { makeTransactionResponse } from '@codepunter-labs/mock-paystack';

paystack.transaction.initialize.mockResolvedValue({
  status: true,
  message: 'Authorization URL created',
  data: makeTransactionResponse({
    reference: 'custom_ref',
    amount: 100000
  })
});

Example: Error Simulation

import { PaystackErrors } from '@codepunter-labs/mock-paystack';

paystack.transaction.initialize.mockRejectedValue(
  PaystackErrors.invalidAmount()
);

API Reference

MockPaystack

| Method | Description | Source | |--------|-------------|--------| | transaction.initialize(request) | Initialize a transaction | mock-paystack.ts | | transaction.verify(reference) | Verify a transaction | mock-paystack.ts | | transaction.list(options?) | List transactions | mock-paystack.ts | | transaction.fetch(reference) | Fetch a transaction | mock-paystack.ts | | transaction.chargeAuthorization(request) | Charge authorization | mock-paystack.ts | | customer.create(request) | Create a customer | mock-paystack.ts | | customer.list(options?) | List customers | mock-paystack.ts | | customer.fetch(customerId) | Fetch a customer | mock-paystack.ts | | customer.update(customerId, request) | Update a customer | mock-paystack.ts | | plan.create(request) | Create a plan | mock-paystack.ts | | plan.list(options?) | List plans | mock-paystack.ts | | subscription.create(request) | Create a subscription | mock-paystack.ts | | subscription.list(options?) | List subscriptions | mock-paystack.ts | | subscription.disable(code, token) | Disable a subscription | mock-paystack.ts | | invoice.create(request) | Create an invoice | mock-paystack.ts | | invoice.list(options?) | List invoices | mock-paystack.ts | | transfer.initiate(request) | Initiate a transfer | mock-paystack.ts | | transfer.list(options?) | List transfers | mock-paystack.ts | | transfer.recipient.list(options?) | List transfer recipients | mock-paystack.ts | | transfer.recipient.create(request) | Create transfer recipient | mock-paystack.ts | | bank.list(currency?) | List banks | mock-paystack.ts | | bank.resolve(accountNumber, bankCode) | Resolve account number | mock-paystack.ts |

Fixture Factories

| Factory | Description | Source | |---------|-------------|--------| | makeTransactionResponse(options?) | Create transaction response | fixtures.ts | | makeCustomer(options?) | Create customer | fixtures.ts | | makePlan(options?) | Create plan | fixtures.ts | | makeSubscription(options?) | Create subscription | fixtures.ts | | makeInvoice(options?) | Create invoice | fixtures.ts | | makeTransfer(options?) | Create transfer | fixtures.ts | | makeTransferRecipient(options?) | Create transfer recipient | fixtures.ts | | makeBank(options?) | Create bank | fixtures.ts | | makeAccountResolution(options?) | Create account resolution | fixtures.ts |

Error Factories

| Error | Description | Source | |-------|-------------|--------| | PaystackErrors.invalidAmount() | Invalid amount error | errors.ts | | PaystackErrors.invalidEmail() | Invalid email error | errors.ts | | PaystackErrors.transactionNotFound() | Transaction not found error | errors.ts | | PaystackErrors.insufficientBalance() | Insufficient balance error | errors.ts | | PaystackErrors.transferFailed() | Transfer failed error | errors.ts |

Testing Patterns

Test Success Path

test('should initialize transaction successfully', async () => {
  const paystack = createMockPaystack({ spy: vi.fn });
  
  const result = await paystack.transaction.initialize({
    amount: 50000,
    email: '[email protected]'
  });
  
  expect(result.status).toBe(true);
  expect(result.data.authorization_url).toBeDefined();
});

Test Error Handling

test('should handle invalid amount error', async () => {
  const paystack = createMockPaystack({ spy: vi.fn });
  
  paystack.transaction.initialize.mockRejectedValue(
    PaystackErrors.invalidAmount()
  );
  
  await expect(
    paystack.transaction.initialize({ amount: -100, email: '[email protected]' })
  ).rejects.toMatchObject({ message: /Invalid amount/ });
});

Test with Custom Data

test('should use custom transaction reference', async () => {
  const paystack = createMockPaystack({ spy: vi.fn });
  
  paystack.transaction.initialize.mockResolvedValue({
    status: true,
    message: 'Authorization URL created',
    data: makeTransactionResponse({ reference: 'custom_ref' })
  });
  
  const result = await paystack.transaction.initialize({
    amount: 50000,
    email: '[email protected]'
  });
  
  expect(result.data.reference).toBe('custom_ref');
});

Test Webhook Handling

test('should verify webhook signature', () => {
  const paystack = createMockPaystack({ spy: vi.fn });
  
  const isValid = paystack.webhook.verify(
    JSON.stringify({ event: 'charge.success' }),
    'signature',
    'secret'
  );
  
  expect(isValid).toBe(true);
});

License

MIT