Iyzico SDK

Modern TypeScript SDK for Iyzico Payment Gateway with secure server-side architecture and React hooks support.

✨ Features

• 🔒 Secure Architecture: Client-side hooks + Server-side API functions
• ⚛️ React Hooks: Client-side state management with HTTP requests
• 🌐 Server-Side Functions: Secure Iyzico API integration
• 🏗️ Clean Architecture: HTTP Client abstraction with multiple implementations
• 🔐 API Key Security: Keys stay on server, never exposed to client
• 📦 Next.js Ready: Built-in API route handlers
• 🎯 Type Safe: Full TypeScript support with comprehensive type definitions
• 🔄 Multi-endpoint Support: Single service handling multiple related endpoints

📦 Installation

npm install @uzansadik/iyzico-sdk

For React hooks support:

npm install @uzansadik/iyzico-sdk react

🚀 Quick Start

1. Server-Side Setup (API Route)

Create API route in your Next.js project:

// pages/api/bin-check.ts (Pages Router)
import { handleBinCheckAPI } from '@uzansadik/iyzico-sdk';

export default handleBinCheckAPI;

Or for App Router:

// app/api/bin-check/route.ts
import { checkBinServer } from '@uzansadik/iyzico-sdk';

export async function POST(request: Request) {
  try {
    const { binNumber, locale } = await request.json();
    
    const result = await checkBinServer({
      binNumber,
      locale: locale || 'tr',
      conversationId: `api-${Date.now()}`
    });

    return Response.json(result);
  } catch (error) {
    const errorMessage = error instanceof Error ? error.message : 'Unknown error';
    return Response.json({ error: errorMessage }, { status: 500 });
  }
}

2. Environment Variables

Create .env.local:

IYZI_API_KEY=your-api-key
IYZI_SECRET_KEY=your-secret-key
IYZI_BASE_URL=https://sandbox-api.iyzipay.com

3. React Component (Client-Side)

import { useCard } from '@uzansadik/iyzico-sdk';

function CardChecker() {
  // Hook sadece HTTP request yapar, API keys kullanmaz
  const { 
    binNumber, 
    setBinNumber, 
    result, 
    loading, 
    error, 
    checkBin 
  } = useCard({ autoCheck: true });

  return (
    <div>
      <input 
        value={binNumber}
        onChange={(e) => setBinNumber(e.target.value)}
        placeholder="Card number (first 6 digits)"
      />
      
      {loading && <p>Checking...</p>}
      {error && <p>Error: {error.message}</p>}
      {result && (
        <div>
          <p>Bank: {result.bankName}</p>
          <p>Card Type: {result.cardType}</p>
          <p>Card Family: {result.cardFamily}</p>
        </div>
      )}
      
      <button onClick={checkBin}>Manual Check</button>
    </div>
  );
}

🏗️ Architecture

Secure Two-Layer Architecture

1. Server-Side Layer:

   • Server-side functions handle Iyzico API communication
   • API keys securely stored in environment variables
   • Functions: checkBinServer(), handleBinCheckAPI()

2. Client-Side Layer:

   • React hooks manage UI state and HTTP requests
   • No API keys or sensitive data on client
   • Hook: useCard()

Custom API Endpoint

const { result, loading, error } = useCard({ 
  autoCheck: true,
  apiEndpoint: '/api/custom-bin-check' // Custom endpoint
});

📚 API Reference

Server-Side Functions

checkBinServer(request: BinCheckRequest): Promise<BinCheckResponse>

Direct server-side bin check function.

import { checkBinServer } from '@uzansadik/iyzico-sdk';

const result = await checkBinServer({
  binNumber: '554960',
  locale: 'tr'
});

handleBinCheckAPI(req, res)

Ready-to-use Next.js API route handler.

import { handleBinCheckAPI } from '@uzansadik/iyzico-sdk';

export default handleBinCheckAPI;

Client-Side Hooks

useCard(options?): UseCardReturn

React hook for bin checking with state management.

interface UseCardOptions {
  autoCheck?: boolean;        // Auto-check on binNumber change
  apiEndpoint?: string;       // Custom API endpoint
}

interface UseCardReturn {
  binNumber: string;
  setBinNumber: (bin: string) => void;
  result: BinCheckResponse | null;
  loading: boolean;
  error: Error | null;
  checkBin: () => Promise<void>;
  clearResult: () => void;
}

Direct Client Usage (Server-Side Only)

import { IyziClient } from '@uzansadik/iyzico-sdk';

const client = IyziClient.getInstance({
  apiKey: 'your-api-key',
  secretKey: 'your-secret-key',
  baseUrl: 'https://sandbox-api.iyzipay.com',
});

const result = await client.binCheck.execute({
  binNumber: '554960',
  locale: 'tr'
});

🔧 Configuration

Environment Variables

IYZI_API_KEY=your-iyzico-api-key
IYZI_SECRET_KEY=your-iyzico-secret-key
IYZI_BASE_URL=https://sandbox-api.iyzipay.com  # or production URL

Hook Options

const hook = useCard({
  autoCheck: true,              // Auto-check on input change
  apiEndpoint: '/api/bin-check' // Your API endpoint
});

🛠️ Development

# Build
npm run build

# Watch mode  
npm run build:watch

# Clean
npm run clean

📄 License

MIT

🤝 Contributing

1. Fork the repository
2. Create your feature branch (git checkout -b feature/amazing-feature)
3. Commit your changes (git commit -m 'Add amazing feature')
4. Push to the branch (git push origin feature/amazing-feature)
5. Open a Pull Request

📋 Changelog

v1.2.2 (Latest)

• 🔒 BREAKING: Secure architecture - useCard no longer accepts API credentials
• 🌐 New: Server-side functions checkBinServer() and handleBinCheckAPI()
• ⚛️ Enhanced: Client-side hook now only handles HTTP requests
• 🔐 Security: API keys never exposed to client-side
• 📦 Added: Next.js API route examples and helpers
• 🎯 Improved: Better separation of concerns

v1.2.1

• 🔧 Fixed: useCard hook server-side environment variable support
• 🌐 Improved: Automatic environment variable detection
• ⚛️ Enhanced: Server-side safe React hooks implementation

v1.2.0

• ✨ Added HTTP client abstraction layer
• ⚛️ Added React hooks support (useCard)
• 🔄 Added multi-endpoint service pattern
• 📦 Added Fetch HTTP client implementation
• 🎯 Improved TypeScript definitions
• 🔧 Added query parameters support