Node.js / TypeScript SDK

The official Seev SDK for JavaScript and TypeScript. Works in Node.js, Bun, Deno, and any JS runtime — framework-agnostic with no DOM dependencies.

The @seev/sdk package is a pure TypeScript SDK built on top of the Seev REST API. It has no framework dependencies — use it in Express, Fastify, NestJS, Next.js API routes, serverless functions, or any JS/TS environment.

Installation

npm install @seev/sdk
# or
pnpm add @seev/sdk
# or
yarn add @seev/sdk

Initialise

Call Seev.init() once at app startup — before making any other API calls.

import Seev from '@seev/sdk';

Seev.init({
  publicKey: 'pk_your_public_key',
  privateKey: 'sk_your_secret_key',
});

Never expose your privateKey in client-side code. Initialise the SDK only on the server.

Create a charge

Seev.charge(data) creates a checkout session and returns a URL to redirect your customer to.

const charge = await Seev.charge({
  type: 'checkout',
  recipient: {
    name: 'John Doe',
    email: 'john@example.com',
    phone: '+233501234567',
  },
  amount: 10000, // in smallest currency unit — 10000 = GHS 100.00
  currency: 'GHS',
  channels: ['card', 'mobile_money'],
  redirectUrl: 'https://myapp.com/callback',
});

console.log(charge.id);           // checkout session ID
console.log(charge.checkoutUrl);  // redirect your customer here

Charge from items

Pass items instead of amount to have Seev calculate the total automatically.

const charge = await Seev.charge({
  type: 'checkout',
  recipient: {
    name: 'Jane Doe',
    email: 'jane@example.com',
  },
  items: [
    { name: 'Product A', description: 'A great product', quantity: 2, price: 5000 },
    { name: 'Product B', quantity: 1, price: 3000 },
  ],
  currency: 'GHS',
  discount: 5,    // percentage
  tax: 2.5,       // percentage
  redirectUrl: 'https://myapp.com/callback',
});

Charge object

Property / Method	Description
`charge.id`	Checkout session ID
`charge.checkoutUrl`	URL to redirect the customer to
`charge.getResponse()`	Full API response object
`charge.getRaw(key)`	Access any custom response field

Handle the callback

After a customer completes (or cancels) a payment, Seev redirects them to your redirectUrl with a session_id query parameter. Call Seev.callback() on that page to verify the result.

// e.g. in your /callback route handler
const session = await Seev.callback();
// or pass a session ID explicitly:
// const session = await Seev.callback('checkout_session_xyz');

if (session.isSuccessful()) {
  console.log('Payment successful!');
  console.log('Session ID:', session.id);
  console.log('Reference:', session.reference);
} else {
  console.log('Payment failed or pending');
  console.log('Status:', session.status);
}

Callback object

Property / Method	Description
`session.isSuccessful()`	`true` if payment succeeded
`session.id`	Checkout session ID
`session.status`	Payment status string
`session.reference`	Transaction reference
`session.getSession()`	Full session object

Always verify the payment server-side using Seev.callback() or Seev.transaction() before fulfilling an order. The redirect URL alone is not proof of payment.

Handle webhooks

Seev sends POST requests to your webhook URL for every payment event. Use Seev.webhook() to parse the request body.

// Express example
app.post('/webhooks/seev', (req, res) => {
  const event = Seev.webhook(req.body, req.user); // user is optional

  if (event.is('checkout.completed')) {
    const { checkoutId, amount, currency } = event.getData();
    // fulfil order, send receipt, update database...
  } else if (event.is('checkout.failed')) {
    const { checkoutId, reason } = event.getData();
    // notify customer, release reserved stock...
  } else if (event.is('refund.issued')) {
    // update order status...
  }

  res.json({ received: true });
});

Common webhook events

Event	Description
`checkout.completed`	Payment succeeded
`checkout.failed`	Payment failed
`checkout.pending`	Payment is pending (e.g. mobile money awaiting PIN)
`refund.issued`	A refund was issued
`invoice.created`	Invoice was created
`invoice.paid`	Invoice was paid

Webhook object

Method	Description
`event.type()`	Event type string — e.g. `'checkout.completed'`
`event.is(type)`	Check if the event matches a given type
`event.getData()`	Event payload data
`event.user()`	The user passed during instantiation
`event.getRawEvent()`	Full raw event object

Fetch a transaction

const transaction = await Seev.transaction('txn_abc123xyz');

console.log(transaction.id);
console.log(transaction.status);   // 'completed' | 'pending' | 'failed'
console.log(transaction.amount);
console.log(transaction.currency);
console.log(transaction.reference);

Type reference

`ChargeRequest`

interface ChargeRequest {
  type: 'checkout' | 'invoice' | 'payment_link';
  recipient: CheckoutRecipient;
  currency?: 'GHS' | 'USD' | 'EUR' | 'GBP' | 'NGN' | 'USDC' | 'USDT' | 'ETH' | 'BTC' | 'XRP';
  channels?: ('card' | 'mobile_money' | 'bank_transfer' | 'seev' | 'crypto')[];
  amount?: number;
  items?: CheckoutItem[];
  discount?: number;
  tax?: number;
  redirectUrl: string;
}

`CheckoutRecipient`

interface CheckoutRecipient {
  name: string;
  email: string;
  address?: string;
  city?: string;
  phone?: string;
}

`CheckoutItem`

interface CheckoutItem {
  name: string;
  description?: string;
  quantity?: number;
  price: number;
  image?: string;
}

Error handling

All SDK methods throw on failure. Wrap calls in try/catch.

try {
  const charge = await Seev.charge({ /* ... */ });
} catch (error) {
  if (error instanceof Error) {
    console.error(error.message);
  }
}

Common error messages

Message	Cause
`Seev SDK not initialized. Call Seev.init() first.`	`Seev.init()` was not called before making a request
`Failed to create checkout session`	Invalid request data or API keys
`Failed to verify checkout session`	Invalid or expired session ID
`Invalid webhook payload: missing event type`	Webhook body is malformed
`Network error`	Cannot reach the Seev API

Full example

import Seev from '@seev/sdk';

// 1. Initialise once (server startup)
Seev.init({
  publicKey: 'pk_test_123',
  privateKey: 'sk_test_456',
});

// 2. Create a checkout and redirect the customer
const charge = await Seev.charge({
  type: 'checkout',
  recipient: { name: 'Jane Doe', email: 'jane@example.com' },
  items: [{ name: 'Widget', price: 2500, quantity: 1 }],
  currency: 'GHS',
  redirectUrl: 'https://myapp.com/checkout-complete',
});
res.redirect(charge.checkoutUrl!);

// 3. Verify on your callback page
const result = await Seev.callback();
if (result.isSuccessful()) {
  // fulfil order
}

// 4. Listen for server-side events via webhooks
app.post('/webhooks/seev', (req, res) => {
  const event = Seev.webhook(req.body);
  if (event.is('checkout.completed')) {
    // update database, send receipt...
  }
  res.json({ ok: true });
});

// 5. Look up a transaction by ID
const txn = await Seev.transaction(charge.id);
console.log(`${txn.amount} ${txn.currency} — ${txn.status}`);