StartButton Node.js SDK

Official Node.js SDK for the StartButton Payment API. This SDK provides a clean, type-safe, and developer-friendly interface for integrating StartButton payment services into your Node.js applications.

Features

🚀 TypeScript Support: Full TypeScript support with comprehensive type definitions
🔐 Authentication: Automatic API key management and authentication
🛡️ Security: Built-in webhook signature verification
🔄 Retry Logic: Automatic retry with exponential backoff
📝 Validation: Comprehensive input validation
🧪 Testing: High test coverage with Jest
📚 Documentation: Comprehensive JSDoc documentation

Installation

npm install @startbutton/node-sdk

Quick Start

import { StartButtonSDK } from '@startbutton/node-sdk';

// Initialize the SDK
const sdk = new StartButtonSDK('your-secret-key', {
  environment: 'test' // or 'live'
});

// Initialize a transaction
const transaction = await sdk.transactions.initialize({
  email: 'customer@example.com',
  amount: 100000, // in kobo (1000 naira)
  currency: 'NGN',
  reference: 'unique-reference-123'
});

console.log('Transaction initialized:', transaction.data);

Configuration

Configuration Options

const sdk = new StartButtonSDK('your-secret-key', {
  environment: 'test', // 'test' or 'live'
  timeout: 30000, // Request timeout in milliseconds
  baseUrl: 'https://api.startbutton.com' // Custom base URL (optional)
});

Note: the SDK does not auto-read environment variables. Pass your secret key and options explicitly when constructing StartButtonSDK.

Core Modules

Transactions

Handle payment transactions and collections.

// Initialize a transaction
const transaction = await sdk.transactions.initialize({
  email: 'customer@example.com',
  amount: 100000,
  reference: 'unique-reference',
  currency: 'NGN',
  callbackUrl: 'https://your-site.com/callback'
});

// Verify a transaction
const verification = await sdk.transactions.verify('transaction-reference');

Merchants

Access merchant account information.

// Get wallet balance
const balance = await sdk.merchants.getWalletBalance();

Webhooks

Verify and handle webhooks securely.

// Verify webhook signature
const isValid = sdk.webhooks.verifySignature(
  typeof req.body === 'string' ? req.body : req.body.toString('utf8'),
  signature,
  'your-webhook-secret'
);

if (isValid) {
  // Transaction status query
  const webhookData = sdk.webhooks.transactionStatus(req.body.transactionReference);
  console.log('Webhook received:', webhookData);
}

Default headers sent with each request

The SDK automatically sends these headers:

Authorization: Bearer
Content-Type: application/json
User-Agent: /
X-SDK-Version:
X-SDK-Source: node-sdk

Error Handling

The SDK provides comprehensive error handling with specific error types:

try {
  const transaction = await sdk.transactions.initialize({
    email: 'invalid-email',
    amount: -100
  });
} catch (error) {
  if (error instanceof ValidationError) {
    console.log('Validation failed:', error.errors);
  } else if (error instanceof AuthenticationError) {
    console.log('Authentication failed');
  } else if (error instanceof RateLimitError) {
    console.log('Rate limit exceeded');
  } else {
    console.log('Unexpected error:', error.message);
  }
}

Testing

Run the test suite:

# Run all tests
npm test

# Run tests in watch mode
npm run test:watch

# Run tests with coverage
npm run test:coverage

Development

Building the SDK

# Build for production
npm run build

# Build TypeScript declarations
npm run build:types

# Clean build artifacts
npm run clean

Code Quality

# Lint code
npm run lint

# Fix linting issues
npm run lint:fix

# Format code
npm run format

API Reference

For detailed API documentation, see the API Reference.

License

MIT License - see LICENSE for details.

Support

Documentation: https://startbutton.gitbook.io