Official Node.js SDK for the ZevPay Checkout REST API.
npm install @zevpay/node- Node.js 18 or later
- A ZevPay secret API key (get one here)
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: 'customer@example.com',
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
}// Initialize
const session = await zevpay.checkout.initialize({
amount: 500000,
email: 'customer@example.com',
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);// 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();// Create
const invoice = await zevpay.invoices.create({
customerName: 'Jane Doe',
customerEmail: 'jane@example.com',
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);// 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);// 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);// 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' });// 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');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);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)
}
}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
});All amounts are in kobo (minor currency units):
| Naira | Kobo |
|---|---|
| ₦1 | 100 |
| ₦100 | 10,000 |
| ₦1,000 | 100,000 |
| ₦10,000 | 1,000,000 |
| 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 |
MIT