KiraPay SDK

Official TypeScript/JavaScript SDK for the KiraPay API. This SDK provides a simple and intuitive way to integrate KiraPay's payment functionality into your applications.

Features

• ✅ Full TypeScript support with detailed type definitions
• ✅ Promise-based API with async/await support
• ✅ Comprehensive error handling
• ✅ Support for all KiraPay API endpoints
• ✅ Lightweight with minimal dependencies
• ✅ Works in Node.js and modern browsers
• ✅ Detailed documentation and examples

Installation

npm install kirapay-sdk

or

yarn add kirapay-sdk

Quick Start

import { KiraPay } from 'kirapay-sdk';

// Initialize the client
const kirapay = new KiraPay({
  apiKey: 'your-api-key-here',
  baseUrl: 'https://kirapay.focalfossa.site/api' // optional, defaults to production
});

// Create a payment link
async function createPayment() {
  try {
    const result = await kirapay.createPaymentLink({
      currency: 'USDC',
      receiver: '0x742d35Cc6634C0532925a3b8D4C9db96C4b4d8b6',
      price: 100.5,
      name: 'Order #A1209',
      redirectUrl: 'https://yoursite.com/thank-you'
    });
    
    console.log('Payment URL:', result.url);
  } catch (error) {
    console.error('Error creating payment:', error);
  }
}

API Reference

Constructor

const kirapay = new KiraPay(config: KiraPayConfig);

Parameters:

• config.apiKey (string, required): Your KiraPay API key
• config.baseUrl (string, optional): API base URL (defaults to production)

Methods

createPaymentLink(request: CreateLinkRequest): Promise<CreateLinkResponse>

Create a new payment link for customers to pay to.

const result = await kirapay.createPaymentLink({
  currency: 'USDC',
  receiver: '0x742d35Cc6634C0532925a3b8D4C9db96C4b4d8b6',
  price: 100.5,
  name: 'Product Purchase',
  redirectUrl: 'https://yoursite.com/success' // optional
});

console.log(result.url); // https://kirapay.focalfossa.site/abc123def4

Parameters:

• currency (string): Currency type (currently only 'USDC' supported)
• receiver (string): Ethereum wallet address to receive payments
• price (number): Payment amount (must be ≥ 0)
• name (string): Display name for the payment link
• redirectUrl (string, optional): URL to redirect after successful payment

getPaymentLinks(request?: GetLinksRequest): Promise<GetLinksResponse>

Retrieve a paginated list of your payment links.

const result = await kirapay.getPaymentLinks({
  page: 1,
  limit: 10
});

console.log(result.links);
console.log(`Total: ${result.total}, Page: ${result.page}/${result.totalPages}`);

Parameters:

• page (number, optional): Page number (default: 1)
• limit (number, optional): Items per page (default: 10, max: 100)

getPaymentLinkByCode(code: string): Promise<PaymentLink>

Get detailed information about a payment link by its code. This is a public endpoint.

const link = await kirapay.getPaymentLinkByCode('abc123def4');
console.log(link.name, link.price, link.receiver);

getWalletTransactions(request?: GetTransactionsRequest): Promise<GetTransactionsResponse>

Retrieve wallet transactions with filtering and pagination.

const result = await kirapay.getWalletTransactions({
  status: 'COMPLETED',
  page: 1,
  limit: 20,
  from_date: '2025-01-01T00:00:00.000Z',
  to_date: '2025-01-31T23:59:59.999Z'
});

console.log(result.transactions);

Parameters:

• status (string, optional): Filter by status ('PENDING', 'COMPLETED', 'FAILED', 'CANCELLED')
• transaction_hash (string, optional): Filter by specific transaction hash
• from_date (string, optional): Filter from date (ISO 8601 format)
• to_date (string, optional): Filter to date (ISO 8601 format)
• page (number, optional): Page number (default: 1)
• limit (number, optional): Items per page (default: 10, max: 100)

TypeScript Support

The SDK is written in TypeScript and provides comprehensive type definitions:

import { 
  KiraPay, 
  CreateLinkRequest, 
  PaymentLink, 
  Transaction,
  KiraPayError 
} from 'kirapay-sdk';

// All API responses are fully typed
const links: PaymentLink[] = (await kirapay.getPaymentLinks()).links;

Error Handling

The SDK throws KiraPayError for API errors with detailed information:

import { KiraPayError } from 'kirapay-sdk';

try {
  await kirapay.createPaymentLink({
    currency: 'USDC',
    receiver: 'invalid-address',
    price: 100,
    name: 'Test'
  });
} catch (error) {
  if (error instanceof KiraPayError) {
    console.error(`API Error ${error.statusCode}: ${error.message}`);
    console.error('Timestamp:', error.timestamp);
    console.error('Path:', error.path);
  } else {
    console.error('Unexpected error:', error);
  }
}

Configuration Management

Update configuration after initialization:

// Update API key
kirapay.setApiKey('new-api-key');

// Update base URL (for testing/staging)
kirapay.setBaseUrl('https://staging-api.kirapay.com');

// Get current configuration
const config = kirapay.getConfig();
console.log('Current API key:', config.apiKey);

Examples

Complete E-commerce Integration

import { KiraPay, KiraPayError } from 'kirapay-sdk';

class PaymentService {
  private kirapay: KiraPay;

  constructor(apiKey: string) {
    this.kirapay = new KiraPay({ apiKey });
  }

  async createOrderPayment(orderId: string, amount: number, customerWallet: string) {
    try {
      const result = await this.kirapay.createPaymentLink({
        currency: 'USDC',
        receiver: customerWallet,
        price: amount,
        name: `Order #${orderId}`,
        redirectUrl: `https://mystore.com/orders/${orderId}/success`
      });

      return {
        success: true,
        paymentUrl: result.url,
        orderId
      };
    } catch (error) {
      if (error instanceof KiraPayError) {
        console.error(`Payment creation failed: ${error.message}`);
        return {
          success: false,
          error: error.message,
          statusCode: error.statusCode
        };
      }
      throw error;
    }
  }

  async getOrderPayments() {
    const result = await this.kirapay.getPaymentLinks({
      limit: 100 // Get all recent payments
    });

    return result.links.map(link => ({
      orderId: link.name.replace('Order #', ''),
      amount: link.price,
      status: link.createdAt,
      paymentUrl: link.url || `https://kirapay.focalfossa.site/${link.code}`
    }));
  }

  async getTransactionHistory(days: number = 30) {
    const fromDate = new Date();
    fromDate.setDate(fromDate.getDate() - days);

    const result = await this.kirapay.getWalletTransactions({
      from_date: fromDate.toISOString(),
      status: 'COMPLETED',
      limit: 100
    });

    return result.transactions;
  }
}

// Usage
const paymentService = new PaymentService('your-api-key');

// Create a payment for an order
const payment = await paymentService.createOrderPayment('ORD-001', 99.99, '0x742d35Cc...');
if (payment.success) {
  console.log('Payment URL:', payment.paymentUrl);
}

// Get transaction history
const history = await paymentService.getTransactionHistory(7); // Last 7 days
console.log(`Found ${history.length} completed transactions`);

Browser Usage

The SDK works in modern browsers with fetch support:

<!DOCTYPE html>
<html>
<head>
  <title>KiraPay Browser Example</title>
</head>
<body>
  <script type="module">
    import { KiraPay } from 'https://unpkg.com/kirapay-sdk@latest/dist/index.mjs';
    
    const kirapay = new KiraPay({
      apiKey: 'your-api-key-here'
    });
    
    document.getElementById('create-payment').addEventListener('click', async () => {
      try {
        const result = await kirapay.createPaymentLink({
          currency: 'USDC',
          receiver: '0x742d35Cc6634C0532925a3b8D4C9db96C4b4d8b6',
          price: 50,
          name: 'Browser Payment Test'
        });
        
        window.open(result.url, '_blank');
      } catch (error) {
        alert('Error: ' + error.message);
      }
    });
  </script>
  
  <button id="create-payment">Create Payment Link</button>
</body>
</html>

API Endpoints Covered

• ✅ POST /link/generate - Create payment link
• ✅ GET /link - Get user's payment links
• ✅ GET /link/{code} - Get payment link by code (public)
• ✅ GET /wallet/transactions - Get wallet transactions

Requirements

• Node.js 16+ (for Node.js usage)
• Modern browser with fetch support (for browser usage)
• KiraPay API key

License

MIT

Support

For issues and questions:

• GitHub Issues: Create an issue
• API Documentation: https://kirapay.focalfossa.site/docs
• Email: [email protected]

Contributing

Contributions are welcome! Please read our contributing guidelines and submit pull requests to our repository.

Changelog

v1.0.0

• Initial release
• Full API coverage for all public endpoints
• TypeScript support
• Comprehensive error handling
• Browser and Node.js compatibility