zips-typescript-sdk

ZIPS TypeScript SDK

A comprehensive TypeScript SDK for integrating with the ZIPS Payment Gateway. This server-side SDK provides a clean, type-safe interface for handling payments, transactions, and customers in Node.js applications.

Latest Version: v1.1.4 - Enhanced with improved API reliability, better error handling, and optimized React Native SDK integration.

🆕 Latest Features (v1.1.4)

• 🔧 Enhanced Reliability: Improved API endpoint configurations for better network performance
• 🛠️ Better Error Handling: Enhanced error messages and network resilience
• ⚡ Performance Optimizations: Faster API calls and improved response handling
• 🔗 React Native Integration: Optimized compatibility with React Native SDK v2.3.39
• 📦 Build Quality: Enhanced TypeScript compilation and package distribution
• 🔍 Developer Experience: Better debugging capabilities and enhanced documentation

🚀 Features

• 💻 Server-Side Focus: Designed specifically for backend/server-side applications
• 🔒 Type Safety: Full TypeScript support with comprehensive type definitions
• ⚡ Modern Architecture: Built with modern TypeScript and async/await patterns
• 📦 Lightweight: Minimal dependencies (only axios for HTTP requests)
• 🛡️ Error Handling: Comprehensive error handling with meaningful error messages

📦 Installation

# Install latest version
npm install zips-typescript-sdk@latest

# Or install specific version
npm install zips-typescript-sdk

Requirements

• Node.js >= 16.0.0
• npm >= 7.0.0
• TypeScript >= 4.5.0 (for TypeScript projects)

🔧 Quick Start

import Zips from "zips-typescript-sdk";

// Initialize the SDK with your API key
const zips = new Zips("your-api-key");

// Create a payment
async function createPayment() {
  try {
    const payment = await zips.payments.create({
      name: "Product Purchase",
      quantity: 1,
      amount: 5000, // Amount in GMD (dalasi)
      description: "Premium subscription",
      projectId: "your-project-id",
      currency: "GMD",
      country: "The Gambia",
      firstName: "John",
      lastName: "Doe",
      phoneNumber: "2207001234",
      merchantAccountId: "your-merchant-account-id",
    });

    console.log("Payment created:", payment.referenceNumber);
    return payment;
  } catch (error) {
    console.error("Payment creation failed:", error.message);
  }
}

// Get transaction details
async function getTransaction(referenceNumber: string) {
  try {
    const transaction = await zips.transactions.single(referenceNumber);
    console.log("Transaction status:", transaction.data.status);
    return transaction;
  } catch (error) {
    console.error("Failed to fetch transaction:", error.message);
  }
}

📚 API Reference

Zips Class

The main SDK class that provides access to all modules.

const zips = new Zips(apiKey: string);

Payments Module

Create Payment

const payment = await zips.payments.create({
  name: string;              // Product/service name
  quantity: number;          // Quantity of items
  amount: number;           // Amount in GMD (dalasi)
  description?: string;     // Payment description
  projectId: string;        // Your project ID
  currency: string;         // Currency code (e.g., "GMD")
  country?: string;         // Country name
  firstName: string;        // Customer's first name
  middleName?: string;      // Customer's middle name (optional)
  lastName: string;         // Customer's last name
  phoneNumber: string;      // Customer's phone number
  merchantAccountId: string; // Your merchant account ID
});

Response:

{
  data: string; // Payment data
  success: boolean; // Success status
  referenceNumber: string; // Unique payment reference
  message: string; // Response message
}

Transactions Module

Get Single Transaction

const transaction = await zips.transactions.single(referenceNumber: string);

Response:

{
  status: string;           // Transaction status
  success: boolean;         // Success status
  message: string;          // Response message
  data: {
    id: string;
    projectId: string;
    orderId: string;
    amount: string;
    status: string;
    country: string;
    reference: string;
    fees: number;
    createdAt: string;
    updatedAt: string;
    projectTransaction?: string;
    isSettled?: boolean;
    merchantId?: string;
    bankName?: string;
  };
  url: string;             // Payment URL
}

Get All Transactions

const transactions = await zips.transactions.all({
  limit?: number;    // Number of transactions to retrieve (default: 15)
  page?: number;     // Page number (default: 1)
});

🔐 Authentication

The SDK uses API key authentication. You can obtain your API key from your ZIPS merchant dashboard.

const zips = new Zips("your-api-key-here");

🌍 Environment Configuration

The SDK automatically handles environment configuration based on your setup. The SDK will connect to the appropriate ZIPS API endpoints based on your environment settings.

This configuration supports:

• Local development and testing
• Integration with ZIPS API services
• Production environment deployment

Make sure you have the appropriate API keys and environment setup before using the SDK.

📋 TypeScript Support

This SDK is built with TypeScript and provides comprehensive type definitions:

import Zips, { PaymentParams, Payment, Transaction } from "zips-typescript-sdk";

// All types are exported for your use
const paymentData: PaymentParams = {
  // ... your payment data with full type checking
};

❌ Error Handling

The SDK provides meaningful error messages:

try {
  const payment = await zips.payments.create(paymentData);
} catch (error) {
  console.error("Error:", error.message);
  // Handle error appropriately
}

🛠️ Advanced Usage

Custom Configuration

// The SDK handles configuration automatically
// Advanced users can extend the base modules for custom functionality

Webhooks

// Webhook handling will be available in future versions
// For now, implement webhook endpoints according to ZIPS documentation

📝 Examples

E-commerce Integration

import Zips from "zips-typescript-sdk";

class PaymentService {
  private zips: Zips;

  constructor(apiKey: string) {
    this.zips = new Zips(apiKey);
  }

  async processOrder(orderData: any) {
    try {
      // Create payment
      const payment = await this.zips.payments.create({
        name: orderData.productName,
        quantity: orderData.quantity,
        amount: orderData.totalAmount,
        description: `Order #${orderData.orderId}`,
        projectId: process.env.ZIPS_PROJECT_ID!,
        currency: "GMD",
        country: "The Gambia",
        firstName: orderData.customer.firstName,
        lastName: orderData.customer.lastName,
        phoneNumber: orderData.customer.phone,
        merchantAccountId: process.env.ZIPS_MERCHANT_ID!,
      });

      // Store reference number for tracking
      await this.savePaymentReference(
        orderData.orderId,
        payment.referenceNumber
      );

      return {
        success: true,
        referenceNumber: payment.referenceNumber,
        message: "Payment initiated successfully",
      };
    } catch (error) {
      return {
        success: false,
        error: error.message,
      };
    }
  }

  async checkPaymentStatus(referenceNumber: string) {
    try {
      const transaction = await this.zips.transactions.single(referenceNumber);
      return {
        status: transaction.data.status,
        isSettled: transaction.data.isSettled,
        amount: transaction.data.amount,
      };
    } catch (error) {
      throw new Error(`Failed to check payment status: ${error.message}`);
    }
  }

  private async savePaymentReference(orderId: string, referenceNumber: string) {
    // Implement your database logic here
  }
}

🔧 Requirements

• Node.js 16 or higher
• TypeScript 4.5 or higher (for TypeScript projects)

🤝 Support

For support and questions:

• 📧 Email: [e-mail]
• 📖 Documentation: ZIPS Developer Docs
• 🐛 Issues: GitHub Issues

📄 License

MIT License - see LICENSE file for details.

🔄 Changelog

v1.1.4

• Enhanced API endpoint configurations for improved reliability
• Updated URL configurations for better development experience
• Improved error handling and network reliability
• Bug fixes and performance optimizations

v1.1.3

• Enhanced TypeScript definitions and interfaces
• Improved error handling with better error messages
• Performance optimizations for API calls
• Enhanced compatibility with React Native SDK integration

v1.1.2

• Bug fixes and performance improvements
• Enhanced payment creation flow
• Better error handling and validation
• Improved type safety and documentation

v1.1.1

• Enhanced API configurations for improved development experience
• Improved API endpoint management
• Better integration with React Native SDK
• Performance optimizations and bug fixes

v1.1.0

• Configured for development environment
• Enhanced API endpoint management
• Optimized for development and testing workflows

v1.0.0

• Initial release
• Payment creation functionality
• Transaction querying
• Full TypeScript support
• Comprehensive error handling