WhileSmart Pay SDK

Official TypeScript/JavaScript SDK for the WhileSmart Pay API. Create and manage payment links and subscriptions.

Installation

npm install @whilesmart/pay

Quick Start

import { WhilesmartPay } from '@whilesmart/pay';

const pay = new WhilesmartPay({
  clientId: 'your-client-id',
  clientSecret: 'your-client-secret',
});

Payment Links

Create a Payment Link

// Using plain object
const link = await pay.paymentLinks.create({
  name: 'Product Payment',
  amount: 1000,
  amount_type: 'fixed', // or 'variable'
  currency: 'NGN',
  description: 'Payment for product',
  payment_methods: ['card', 'mtn_momo'],
  usage_type: 'multi', // or 'single'
  external_id: 'your-reference-123',
  expires_at: '2025-12-31 23:59:59',
  redirect_url: 'https://example.com/success',
  webhook_url: 'https://example.com/webhook',
  max_payments: 100,
  min_amount: 500,
  max_amount: 50000,
  custom_thank_you_message: 'Thank you for your payment!',
  metadata: { order_id: 'ORD-001' },
  require_name: true,
  require_email: true,
  require_phone: false,
  tax_enabled: true,
  tax_rate: 7.5,
});

// Using typed request class
import { CreatePaymentLinkRequest } from '@whilesmart/pay';

const link = await pay.paymentLinks.create(
  new CreatePaymentLinkRequest({
    name: 'Product Payment',
    amount: 1000,
    amountType: 'fixed',
    currency: 'NGN',
    paymentMethods: ['card', 'mtn_momo'],
    usageType: 'single',
  })
);

List Payment Links

const links = await pay.paymentLinks.list({
  per_page: '10',
  page: '1',
});

Get a Payment Link

// By slug
const link = await pay.paymentLinks.get('link-slug');

// By ID
const link = await pay.paymentLinks.get(123);

// Explicit methods
const link = await pay.paymentLinks.getBySlug('link-slug');
const link = await pay.paymentLinks.getById(123);

Update a Payment Link

// By slug or ID
const link = await pay.paymentLinks.update('link-slug', {
  name: 'Updated Name',
  amount: 2000,
  active: true,
});

Delete a Payment Link

// By slug or ID
await pay.paymentLinks.delete('link-slug');

Get Link Analytics

// By slug or ID
const analytics = await pay.paymentLinks.analytics('link-slug');

Subscriptions

Create a Subscription

const subscription = await pay.subscriptions.create({
  name: 'Monthly Plan',
  amount: 5000,
  currency: 'NGN',
  interval: 'monthly', // daily, weekly, monthly, yearly
});

List Subscriptions

const subscriptions = await pay.subscriptions.list();

Get a Subscription

const subscription = await pay.subscriptions.get('subscription-id');

Update a Subscription

const subscription = await pay.subscriptions.update('subscription-id', {
  amount: 6000,
});

Cancel a Subscription

await pay.subscriptions.cancel('subscription-id');

Pause a Subscription

await pay.subscriptions.pause('subscription-id');

Resume a Subscription

await pay.subscriptions.resume('subscription-id');

Error Handling

import {
  WhilesmartPay,
  ApiError,
  AuthenticationError,
  ValidationError,
} from '@whilesmart/pay';

try {
  const link = await pay.paymentLinks.create({...});
} catch (error) {
  if (error instanceof AuthenticationError) {
    // Invalid credentials (401)
    console.error(error.message);
  } else if (error instanceof ValidationError) {
    // Validation errors (422)
    console.error(error.message);
    console.error(error.errors);
  } else if (error instanceof ApiError) {
    // Other API errors
    console.error(error.message);
    console.error(error.statusCode);
  }
}

Configuration Options

| Option | Description | Required | |--------|-------------|----------| | clientId | Your app's client ID | Yes | | clientSecret | Your app's client secret | Yes |

Requirements

• Node.js 18 or higher

License

MIT