@zevpay/node

Official Node.js SDK for the ZevPay Checkout REST API.

Installation

npm install @zevpay/node

Requirements

• Node.js 18 or later
• A ZevPay secret API key (get one here)

Quick Start

import ZevPay from '@zevpay/node';

const zevpay = new ZevPay('sk_live_xxx');

// Initialize a checkout session
const session = await zevpay.checkout.initialize({
  amount: 500000, // ₦5,000 in kobo
  email: '[email protected]',
  reference: 'ORDER-123',
  callbackUrl: 'https://yoursite.com/callback',
});

console.log(session.checkoutUrl); // Redirect your customer here

// Verify payment
const result = await zevpay.checkout.verify(session.sessionId);
if (result.status === 'completed') {
  // Payment successful
}

Usage

Checkout Sessions

// Initialize
const session = await zevpay.checkout.initialize({
  amount: 500000,
  email: '[email protected]',
  currency: 'NGN',
  reference: 'ORDER-123',
  callbackUrl: 'https://yoursite.com/callback',
  metadata: { orderId: '123' },
});

// Select payment method
const method = await zevpay.checkout.selectPaymentMethod(session.sessionId, {
  paymentMethod: 'bank_transfer',
});

// Verify
const verification = await zevpay.checkout.verify(session.sessionId);

// Get session details
const details = await zevpay.checkout.get(session.sessionId);

Transfers

// Bank transfer
const transfer = await zevpay.transfers.create({
  type: 'bank_transfer',
  amount: 1000000, // ₦10,000
  accountNumber: '0123456789',
  bankCode: '044',
  accountName: 'John Doe',
  narration: 'Payout',
});

// PayID transfer
const payidTransfer = await zevpay.transfers.create({
  type: 'payid',
  amount: 500000,
  payId: 'johndoe',
});

// List transfers
const transfers = await zevpay.transfers.list({
  page: 1,
  pageSize: 20,
  status: 'completed',
});

// Verify transfer
const verified = await zevpay.transfers.verify('TXN-123');

// List banks
const banks = await zevpay.transfers.listBanks();

// Resolve bank account
const account = await zevpay.transfers.resolveAccount({
  accountNumber: '0123456789',
  bankCode: '044',
});

// Calculate fees
const charges = await zevpay.transfers.calculateCharges({
  amount: 1000000,
  bankCode: '044',
});

// Get wallet balance
const balance = await zevpay.transfers.getBalance();

Invoices

// Create
const invoice = await zevpay.invoices.create({
  customerName: 'Jane Doe',
  customerEmail: '[email protected]',
  dueDate: '2026-04-01',
  lineItems: [
    { description: 'Web Design', quantity: 1, unitPrice: 5000000 },
  ],
  taxRate: 7.5,
  note: 'Thank you for your business',
});

console.log(invoice.paymentUrl); // Send this to your customer

// Send invoice
await zevpay.invoices.send(invoice.publicId);

// List invoices
const invoices = await zevpay.invoices.list({ status: 'sent' });

// Cancel invoice
await zevpay.invoices.cancel(invoice.publicId);

Static PayIDs

// Create
const payid = await zevpay.staticPayId.create({
  payId: 'mystore',
  suffix: '.spid',
  name: 'My Store',
  description: 'Accept payments to my store',
});

// List
const payids = await zevpay.staticPayId.list();

// Update
await zevpay.staticPayId.update(payid.id, { name: 'Updated Name' });

// Deactivate / Reactivate
await zevpay.staticPayId.deactivate(payid.id);
await zevpay.staticPayId.reactivate(payid.id);

Dynamic PayIDs

// Create
const dpayid = await zevpay.dynamicPayId.create({
  amount: 1000000,
  name: 'Donation Drive',
  expiresInMinutes: 60,
});

// List
const dpayids = await zevpay.dynamicPayId.list({ status: 'active' });

// Deactivate
await zevpay.dynamicPayId.deactivate(dpayid.id);

Virtual Accounts

// Create
const va = await zevpay.virtualAccounts.create({
  amount: 1000000,
  validityMinutes: 60,
});

console.log(va.accountNumber); // Customer pays to this account

// List
const accounts = await zevpay.virtualAccounts.list({ status: 'pending' });

Wallet

// Get wallet details
const wallet = await zevpay.wallet.get();

// List members
const members = await zevpay.wallet.listMembers();

// Add member
await zevpay.wallet.addMember({ payId: 'johndoe' });

// Remove member
await zevpay.wallet.removeMember('johndoe');

Webhook Verification

import ZevPay from '@zevpay/node';

// Express example
app.post('/webhooks/zevpay', (req, res) => {
  const signature = req.headers['x-zevpay-signature'] as string;
  const webhookSecret = process.env.ZEVPAY_WEBHOOK_SECRET;

  try {
    const event = ZevPay.webhooks.constructEvent(
      JSON.stringify(req.body),
      signature,
      webhookSecret,
    );

    switch (event.event) {
      case 'charge.success':
        // Handle successful payment
        break;
      case 'transfer.success':
        // Handle successful transfer
        break;
      case 'transfer.failed':
        // Handle failed transfer
        break;
      case 'invoice.paid':
        // Handle paid invoice
        break;
    }

    res.sendStatus(200);
  } catch (err) {
    res.status(400).send('Invalid signature');
  }
});

You can also verify without parsing:

const isValid = ZevPay.webhooks.verify(rawBody, signature, webhookSecret);

Error Handling

All API errors throw typed exceptions:

import ZevPay, {
  ZevPayError,
  ZevPayValidationError,
  ZevPayAuthenticationError,
  ZevPayNotFoundError,
  ZevPayRateLimitError,
} from '@zevpay/node';

try {
  await zevpay.transfers.create({ ... });
} catch (err) {
  if (err instanceof ZevPayValidationError) {
    console.log(err.code);       // e.g. 'VALIDATION_ERROR'
    console.log(err.message);    // Human-readable message
    console.log(err.details);    // Field-level errors
    console.log(err.statusCode); // 400
  } else if (err instanceof ZevPayAuthenticationError) {
    // Invalid API key (401)
  } else if (err instanceof ZevPayRateLimitError) {
    console.log(err.retryAfter); // Seconds to wait
  } else if (err instanceof ZevPayNotFoundError) {
    // Resource not found (404)
  }
}

Configuration

const zevpay = new ZevPay('sk_live_xxx', {
  baseUrl: 'https://api.zevpaycheckout.com', // default
  timeout: 30000,  // 30s default
  maxRetries: 2,   // retries on 5xx errors, default 2
});

Amounts

All amounts are in kobo (minor currency units):

| Naira | Kobo | |-------|------| | ₦1 | 100 | | ₦100 | 10,000 | | ₦1,000 | 100,000 | | ₦10,000 | 1,000,000 |

Webhook Events

| Event | Description | |-------|-------------| | charge.success | Checkout payment completed | | transfer.success | Transfer completed | | transfer.failed | Transfer failed (auto-reversed) | | transfer.reversed | Transfer reversed | | invoice.created | Invoice created | | invoice.sent | Invoice sent to customer | | invoice.payment_received | Partial invoice payment | | invoice.paid | Invoice fully paid | | invoice.overdue | Invoice past due | | invoice.cancelled | Invoice cancelled |

License

MIT