PayKLY 🚀

The Official KLYCoin Facilitator Payment SDK

PayKLY is the easiest way to integrate KLYCoin payments into your applications. Built for facilitators, merchants, and developers who want to accept crypto payments with just a few lines of code.

🌟 Why PayKLY?

• ⚡ Lightning Fast - Accept payments in seconds, not minutes
• 🔒 Bank-Grade Security - Built-in signature verification and validation
• 💰 Multi-Currency - Support for KOLAY, BNB, USDT, BUSD
• 📱 Developer Friendly - TypeScript-first with complete type safety
• 🌐 Real-time Updates - Webhook integration for instant notifications
• 🛠 Production Ready - Used by 100+ merchants processing $1M+ monthly

🚀 Quick Start

Installation

npm install paykly
# or
yarn add paykly
# or  
pnpm add paykly

Your First Payment (30 seconds)

import { PayKLYFacilitator } from 'paykly';

// 1. Initialize
const paykly = new PayKLYFacilitator({
  facilitatorAddress: '0x742d35Cc4bF516a687E5b111a7c5f8aAbe4C5827',
  merchantId: 'your-merchant-id'
});

// 2. Create payment
const payment = await paykly.createPayment({
  amount: 50,
  currency: 'USDT',
  orderId: 'order_123',
  description: 'Premium subscription'
});

// 3. Done! 🎉
console.log(`Payment URL: ${payment.paymentUrl}`);

That's it! Your customers can now pay with crypto.

💼 Real-World Examples

🛒 E-commerce Store

import { PayKLYFacilitator } from 'paykly';

class CheckoutService {
  private paykly = new PayKLYFacilitator({
    facilitatorAddress: process.env.FACILITATOR_ADDRESS,
    merchantId: process.env.MERCHANT_ID
  });

  async processCheckout(cart) {
    const payment = await this.paykly.createPayment({
      amount: cart.total,
      currency: 'USDT',
      orderId: cart.id,
      description: `Order with ${cart.items.length} items`,
      metadata: { 
        customerId: cart.userId,
        items: cart.items.map(i => i.name)
      }
    });

    return { paymentId: payment.paymentId, status: 'pending' };
  }
}

🎯 SaaS Subscription

import { PayKLYFacilitator, PayKLYWebhook } from 'paykly';

class SubscriptionService {
  private paykly = new PayKLYFacilitator({
    facilitatorAddress: process.env.FACILITATOR_ADDRESS,
    merchantId: process.env.MERCHANT_ID
  });

  async createSubscription(userId, plan) {
    const plans = {
      basic: { amount: 10, features: ['Basic Support'] },
      pro: { amount: 25, features: ['Priority Support', 'Advanced Analytics'] }
    };

    return await this.paykly.createPayment({
      amount: plans[plan].amount,
      currency: 'KOLAY',
      orderId: `sub_${userId}_${Date.now()}`,
      description: `${plan} subscription`,
      metadata: { userId, plan, type: 'subscription' }
    });
  }
}

🎮 Gaming Platform

import { PayKLYFacilitator } from 'paykly';

class GameStore {
  private paykly = new PayKLYFacilitator({
    facilitatorAddress: process.env.FACILITATOR_ADDRESS,
    merchantId: process.env.MERCHANT_ID
  });

  async buyGameCurrency(playerId, amount) {
    // 100 coins = $1 USD
    const usdAmount = amount / 100;
    
    const payment = await this.paykly.createPayment({
      amount: usdAmount,
      currency: 'BUSD',
      orderId: `coins_${playerId}_${Date.now()}`,
      description: `${amount} game coins`,
      metadata: { playerId, coinAmount: amount }
    });

    return payment;
  }
}

📡 Webhook Integration

Stay updated with real-time payment events:

import express from 'express';
import { PayKLYWebhook } from 'paykly';

const app = express();
const webhook = new PayKLYWebhook(process.env.WEBHOOK_SECRET);

app.post('/webhooks/paykly', express.raw({ type: 'application/json' }), async (req, res) => {
  try {
    await webhook.processWebhook(
      req.body.toString(),
      req.headers['x-paykly-signature'],
      async (event) => {
        switch (event.event) {
          case 'payment.completed':
            console.log('💰 Payment completed!', event.data.amount);
            // Fulfill order, activate subscription, etc.
            await fulfillOrder(event.data.orderId);
            break;
            
          case 'payment.failed':
            console.log('❌ Payment failed:', event.data.error);
            // Handle failure, notify customer
            await handleFailure(event.data.orderId);
            break;
        }
      }
    );
    res.status(200).send('OK');
  } catch (error) {
    res.status(400).send('Invalid signature');
  }
});

🛠 Advanced Features

Fee Calculation

const fees = paykly.calculateFees(100, 'USDT');
console.log(`Total fees: ${fees.total} USDT`); // 2.5 USDT

Payment Status Tracking

const status = await paykly.getPaymentStatus('payment_abc123');
if (status.status === 'completed') {
  console.log('Payment successful!');
}

Transaction Verification

const isValid = await paykly.verifyTransaction('0x...');
if (isValid) {
  console.log('Transaction confirmed on blockchain ✅');
}

Bulk Payment Listing

const payments = await paykly.listPayments({
  status: 'completed',
  limit: 50
});
console.log(`Found ${payments.length} completed payments`);

🔧 Configuration Options

Networks

// Production (BSC Mainnet)
const paykly = new PayKLYFacilitator({
  facilitatorAddress: '0x...',
  merchantId: 'your-merchant-id',
  network: 'mainnet' // Default
});

// Development (BSC Testnet)
const paykly = new PayKLYFacilitator({
  facilitatorAddress: '0x...',
  merchantId: 'your-merchant-id', 
  network: 'testnet'
});

Custom API Endpoint

const paykly = new PayKLYFacilitator({
  facilitatorAddress: '0x...',
  merchantId: 'your-merchant-id',
  apiUrl: 'https://your-custom-api.com' // Optional
});

🎯 Supported Currencies

| Currency | Symbol | Network | Decimals | |----------|--------|---------|----------| | KLYCoin | KOLAY | BSC | 18 | | Binance Coin | BNB | BSC | 18 | | Tether | USDT | BSC | 18 | | Binance USD | BUSD | BSC | 18 |

💡 Utilities & Helpers

PayKLY includes handy utilities:

import { PayKLYUtils } from 'paykly';

// Address validation
PayKLYUtils.isValidAddress('0x742d35Cc...'); // true

// Transaction hash validation  
PayKLYUtils.isValidTxHash('0xabc123...'); // true

// Amount formatting
PayKLYUtils.formatAmount(123.456789, 'KOLAY', 4); // "123.4568 KOLAY"

// Order ID generation
PayKLYUtils.generateOrderId('invoice'); // "invoice_1640995200000_abc123"

// Unit conversion
PayKLYUtils.fromWei('1000000000000000000', 18); // 1
PayKLYUtils.toWei(1, 18); // "1000000000000000000"

// Network configuration
const config = PayKLYUtils.getNetworkConfig('mainnet');
console.log(config.explorerUrl); // "https://bscscan.com"

🚨 Error Handling

PayKLY provides detailed error messages:

try {
  const payment = await paykly.createPayment({
    amount: 0, // Invalid amount
    currency: 'INVALID', // Invalid currency  
    orderId: ''  // Missing order ID
  });
} catch (error) {
  console.error('Payment creation failed:', error.message);
  // "Amount must be greater than 0"
}

Common errors:

• Invalid facilitator address
• Insufficient funds in facilitator wallet
• Invalid currency
• Amount must be greater than 0
• Order ID already exists

🧪 Testing

Running Tests

npm test
npm run test:coverage

Mock Webhook Events

import { PayKLYWebhook } from 'paykly';

const webhook = new PayKLYWebhook('test-secret');
const payload = JSON.stringify({
  event: 'payment.completed',
  paymentId: 'test_payment_123',
  data: { amount: 100, currency: 'USDT' }
});

const signature = webhook.createSignature(payload);
// Use for testing webhook endpoints

📚 API Reference

PayKLYFacilitator

Constructor

new PayKLYFacilitator(config: PaymentConfig)

Methods

| Method | Description | Returns | |--------|-------------|---------| | createPayment(request) | Create a new payment | Promise<PaymentResponse> | | getPaymentStatus(id) | Get payment status | Promise<PaymentStatus> |
| listPayments(options?) | List payments with filters | Promise<PaymentResponse[]> | | cancelPayment(id) | Cancel pending payment | Promise<boolean> | | verifyTransaction(hash) | Verify blockchain transaction | Promise<boolean> | | calculateFees(amount, currency) | Calculate payment fees | FeeCalculation |

PayKLYWebhook

Constructor

new PayKLYWebhook(secret: string)

Methods

| Method | Description | Returns | |--------|-------------|---------| | processWebhook(payload, signature, handler) | Process webhook with verification | Promise<void> | | verifySignature(payload, signature) | Verify webhook signature | boolean | | createSignature(payload) | Create signature for testing | string |

🌍 Environment Variables

Create a .env file:

# Required
FACILITATOR_ADDRESS=0x742d35Cc4bF516a687E5b111a7c5f8aAbe4C5827
MERCHANT_ID=your-merchant-id

# Optional  
PAYKLY_API_URL=https://api.klycoin.com
PAYKLY_NETWORK=mainnet
WEBHOOK_SECRET=your-webhook-secret-here

🔄 Migration Guide

From v0.x to v1.x

// Old (v0.x)
import PayKLY from 'paykly';
const client = new PayKLY(config);

// New (v1.x) 
import { PayKLYFacilitator } from 'paykly';
const client = new PayKLYFacilitator(config);

🏗 Contributing

We welcome contributions! Here's how to get started:

1. Fork the repository
2. Clone your fork: git clone https://github.com/yourusername/paykly.git
3. Install dependencies: npm install
4. Create a feature branch: git checkout -b feature/amazing-feature
5. Make your changes
6. Test your changes: npm test
7. Commit your changes: git commit -m 'Add amazing feature'
8. Push to the branch: git push origin feature/amazing-feature
9. Open a Pull Request

Development Setup

git clone https://github.com/klycoin/paykly.git
cd paykly
npm install
npm run dev # Start development mode
npm run build # Build the package
npm run lint # Check code style
npm run test # Run tests

📈 Roadmap

• [x] v1.0 - Core payment processing
• [x] v1.1 - Webhook integration
• [x] v1.2 - Multi-currency support
• [ ] v1.3 - Recurring payments
• [ ] v1.4 - Mobile SDKs (React Native)
• [ ] v1.5 - Advanced analytics dashboard
• [ ] v2.0 - Multi-chain support (Ethereum, Polygon)

🆘 Support & Community

Getting Help

• 📧 Email: [email protected]
• 💬 Discord: KLYCoin Community
• 📱 Telegram: @KLYCoinOfficial
• 🐛 Issues: GitHub Issues
• 📚 Docs: docs.klycoin.com

FAQ

Q: Is PayKLY free to use? A: Yes! PayKLY is free. You only pay standard network fees (2-3%) per transaction.

Q: Which networks are supported?
A: Currently BSC (Binance Smart Chain). Ethereum and Polygon coming soon.

Q: Can I use this in production? A: Absolutely! PayKLY is used by 100+ merchants processing millions in volume.

Q: Do you provide test environment? A: Yes! Use network: 'testnet' for testing with BSC testnet.

📄 License

MIT License - see the LICENSE file for details.

🙏 Acknowledgments

• Built with ❤️ by the KLYCoin team
• Powered by Binance Smart Chain
• Thanks to our amazing community of developers and merchants

Made with ❤️ for the crypto community

⭐ Star us on GitHub • 🐦 Follow on Twitter • 📧 Get Support