JavaScript SDK

Official JavaScript/TypeScript SDK for Zentra

The official Zentra SDK for JavaScript and TypeScript. Works in Node.js, browsers, and modern frameworks like React, Next.js, and Vue.

The reviewed public HTTP surface for this SDK is transfers, webhooks, virtual accounts, payments, cards, and tenant-enabled identity. Customers, wallets, and other generated helpers may still exist for compatibility or draft use cases, but they are not the default reviewed public API path.

Installation

npm

npm install @zentra/sdk

yarn add @zentra/sdk

pnpm add @zentra/sdk

Requirements

• Node.js 18+ or modern browser
• JavaScript ES2020+ or TypeScript 4.5+

Quick Start

import { Zentra } from '@zentra/sdk';

const zentra = new Zentra({
  secretKey: process.env.ZENTRA_SECRET_KEY,
});

const transfer = await zentra.transfers.create({
  amount: 50000,
  accountNumber: '0123456789',
  bankCode: '058',
  accountName: 'Vendor Settlement Account',
  narration: 'Vendor payout',
  reference: `TRF_${Date.now()}`,
});

TypeScript Support

Full TypeScript support with type definitions included:

import { Zentra } from '@zentra/sdk';

const zentra = new Zentra({
  secretKey: process.env.ZENTRA_SECRET_KEY,
});

// Type-safe API calls
const identity = await zentra.identity.verifyBVN({
  bvn: '22222222222',
  firstName: 'John',
  lastName: 'Doe',
  dateOfBirth: '1990-01-01',
});

const account = await zentra.virtualAccounts.create({
  customerId: 'rail_customer_123',
  accountName: 'John Doe',
  preferredBank: 'wema-bank',
  bvn: '22222222222',
});

Configuration

const zentra = new Zentra({
  secretKey: 'sk_live_...', // Required
  timeout: 30000, // Request timeout (ms)
  maxRetries: 3, // Max retry attempts
  baseUrl: 'https://api.usezentra.com', // Custom base URL
});

API Methods

Identity

// Verify BVN
const verification = await zentra.identity.verifyBVN({
  bvn: '22222222222',
  firstName: 'John',
  lastName: 'Doe',
  dateOfBirth: '1990-01-01',
});

// Verify NIN
const ninVerification = await zentra.identity.verifyNIN({
  nin: '12345678901',
  firstName: 'John',
  lastName: 'Doe',
  dateOfBirth: '1990-01-01',
});

Virtual Accounts

// Create virtual account
const account = await zentra.virtualAccounts.create({
  customerId: 'rail_customer_123',
  accountName: 'John Doe',
  preferredBank: 'wema-bank',
  bvn: '22222222222',
});

// Get account
const account = await zentra.virtualAccounts.get('va_123');

// List accounts
const accounts = await zentra.virtualAccounts.list({
  customerId: 'rail_customer_123',
  status: 'active',
});

// Close account
await zentra.virtualAccounts.close('va_123', {
  reason: 'customer_request',
});

Transfers

// Create transfer
const transfer = await zentra.transfers.create({
  amount: 50000, // ₦500.00
  accountNumber: '0123456789',
  bankCode: '058',
  accountName: 'Recipient Name',
  narration: 'Payment for services',
  reference: 'TRF_' + Date.now(),
});

// Get transfer status
const transfer = await zentra.transfers.get('TRF_12345');

// List transfers
const transfers = await zentra.transfers.list({
  status: 'completed',
  limit: 20,
});

Payments

// Create a reviewed-public charge
const charge = await zentra.payments.charge({
  amount_minor: 100000,
  currency: 'NGN',
  email: '[e-mail]',
  reference: 'PAY_' + Date.now(),
  capture_mode: 'customer_action_required',
});

// Verify charge
const verified = await zentra.payments.verify(charge.reference);

// Save a reusable card token
const token = await zentra.payments.storeCardToken({
  customer_id: 'cus_123',
  card_number: '4242424242424242',
  expiry_month: '12',
  expiry_year: '30',
  cvv: '123',
});

// Create a refund
const refund = await zentra.payments.createRefund({
  charge_reference: verified.reference,
  amount_minor: 50000,
  reason: 'customer_request',
});

Cards

// Create virtual card
const card = await zentra.cards.create({
  customerId: 'cus_123',
  type: 'virtual',
  currency: 'NGN',
});

// List cards for one customer
const cards = await zentra.cards.list({
  customerId: 'cus_123',
  limit: 20,
});

// Fund card
await zentra.cards.fund('card_123', {
  amountMinor: 5000,
  currency: 'NGN',
  transactionReference: 'card_fund_123',
  idempotencyKey: 'card_fund_123',
});