Unit Testing Paystack Integrations

Three areas worth unit testing:

1. Webhook signature validation — the HMAC SHA512 check that prevents fake webhooks
2. Event handling logic — what happens when charge.success fires (fulfill), charge.failed fires (mark failed), subscription.disable fires (cancel)
3. Idempotency — duplicate events for the same reference must not cause double fulfillment

What you do not need to unit test: Paystack's own API behavior, the correctness of the transaction data Paystack returns, or network-level reliability.

// webhook-handler.test.js
const crypto = require('crypto');
const { handleWebhook } = require('./webhook-handler');

const SECRET = 'test_secret_key';

function makeSignature(body) {
  return crypto.createHmac('sha512', SECRET).update(body).digest('hex');
}

describe('Webhook signature validation', () => {
  it('accepts a request with valid signature', async () => {
    var body = JSON.stringify({ event: 'charge.success', data: { reference: 'ref_001', amount: 100000, status: 'success', metadata: { order_id: '123' } } });
    var sig = makeSignature(body);
    var result = await handleWebhook(body, sig, SECRET);
    expect(result.status).toBe(200);
  });

  it('rejects a request with wrong signature', async () => {
    var body = JSON.stringify({ event: 'charge.success', data: {} });
    var result = await handleWebhook(body, 'wrong_sig', SECRET);
    expect(result.status).toBe(401);
  });
});

describe('Charge fulfillment', () => {
  it('fulfills order on charge.success', async () => {
    var mockDb = { orders: { update: jest.fn() } };
    var event = { event: 'charge.success', data: { reference: 'ref_002', amount: 100000, status: 'success', metadata: { order_id: '456' } } };
    await fulfillOrder(event.data, mockDb);
    expect(mockDb.orders.update).toHaveBeenCalledWith({ id: '456', status: 'paid', paystack_ref: 'ref_002' });
  });

  it('does not fulfill on charge.failed', async () => {
    var mockDb = { orders: { update: jest.fn() } };
    var event = { event: 'charge.failed', data: { reference: 'ref_003', metadata: { order_id: '789' } } };
    await handleFailedCharge(event.data, mockDb);
    expect(mockDb.orders.update).toHaveBeenCalledWith({ id: '789', status: 'payment_failed' });
    // Crucially: fulfillOrder should NOT have been called
  });
});

describe('Idempotency', () => {
  it('skips fulfillment if reference already processed', async () => {
    var mockDb = {
      webhookEvents: { findOne: jest.fn().mockResolvedValue({ id: 1 }), create: jest.fn() },
      orders: { update: jest.fn() },
    };
    var event = { event: 'charge.success', data: { reference: 'ref_001', metadata: { order_id: '123' } } };
    await handleWithIdempotency(event, mockDb);
    expect(mockDb.orders.update).not.toHaveBeenCalled();
  });
});

This guide is part of the Paystack testing guide.

Sign up for the McTaba newsletter