zips-typescript-sdk/README.md

TypeScript SDK for ZIPS Payment Gateway - Complete payment solution for server-side applications

# 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.

> **Note**: This version (1.1.0+) is configured for localhost development. The SDK connects to local ZIPS API servers at `localhost:9005` (merchant API) and `localhost:9008` (gateway API).

## 🚀 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
- **� Local Development**: Pre-configured for localhost ZIPS API servers
- **📦 Lightweight**: Minimal dependencies (only axios for HTTP requests)
- **🛡️ Error Handling**: Comprehensive error handling with meaningful error messages

## 📦 Installation

```bash
npm install zips-typescript-sdk
```

## 🔧 Quick Start

```typescript
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.

```typescript
const zips = new Zips(apiKey: string);
```

### Payments Module

#### Create Payment

```typescript
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:**

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

### Transactions Module

#### Get Single Transaction

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

**Response:**

```typescript
{
  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

```typescript
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.

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

## 🌍 Environment Configuration

This SDK version is pre-configured for localhost development:

- **Merchant API**: `http://localhost:9005/api/v1/`
- **Gateway API**: `http://localhost:9008/api/v1/`

This configuration is ideal for:
- Local development and testing
- Integration with local ZIPS API servers
- Development environment setup

Make sure your local ZIPS merchant and gateway services are running on the specified ports before using the SDK.

## 📋 TypeScript Support

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

```typescript
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:

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

## 🛠️ Advanced Usage

### Custom Configuration

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

### Webhooks

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

## 📝 Examples

### E-commerce Integration

```typescript
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: support@zigtech.gm
- 📖 Documentation: [ZIPS Developer Docs](https://docs.zips.gm)
- 🐛 Issues: [GitHub Issues](https://github.com/zigtech/zips-typescript-sdk/issues)

## 📄 License

MIT License - see LICENSE file for details.

## 🔄 Changelog

### v1.1.0
- Configured for localhost development environment
- Pre-set API endpoints for local ZIPS servers
- Optimized for development and testing workflows

### v1.0.0
- Initial release
- Payment creation functionality
- Transaction querying
- Full TypeScript support
- Comprehensive error handling