@gatepaybd/core/README.md

Official JavaScript/TypeScript SDK for GatePay payment gateway supporting bKash, Nagad, Rocket and other Bangladesh payment methods

# GatePay SDK for JavaScript/TypeScript

Official JavaScript/TypeScript SDK for the GatePay payment gateway. Supports Node.js, React, Vue, Angular, and all modern JavaScript environments.

## Installation

```bash
npm install gatepay
# or
yarn add gatepay
```

## Quick Start

```typescript
import { PayflowSDK, PaymentMethod } from 'payflow-sdk';

// Initialize the SDK
const payflow = new PayflowSDK({
  apiKey: 'your-api-key',
  environment: 'sandbox' // or 'production'
});

// Create a payment
const payment = await payflow.payments.create({
  amount: 1000, // Amount in smallest currency unit (e.g., paisa for BDT)
  currency: 'BDT',
  paymentMethod: PaymentMethod.BKASH,
  customerInfo: {
    name: 'John Doe',
    email: 'john@example.com',
    phone: '+8801234567890'
  },
  returnUrl: 'https://yoursite.com/success',
  cancelUrl: 'https://yoursite.com/cancel'
});

console.log('Payment created:', payment);
```

## API Reference

### Configuration

```typescript
interface PayflowConfig {
  apiKey: string;
  environment?: 'sandbox' | 'production';
  baseUrl?: string; // Custom API base URL
  timeout?: number; // Request timeout in milliseconds
}
```

### Payment Methods

Create a payment:
```typescript
const payment = await payflow.payments.create({
  amount: 1000,
  currency: 'BDT',
  paymentMethod: PaymentMethod.BKASH,
  customerInfo: {
    name: 'Customer Name',
    email: 'customer@email.com',
    phone: '+8801234567890'
  }
});
```

Get payment status:
```typescript
const payment = await payflow.payments.get('payment-id');
```

List transactions:
```typescript
const transactions = await payflow.payments.list({
  page: 1,
  limit: 20,
  status: PaymentStatus.COMPLETED,
  startDate: new Date('2024-01-01'),
  endDate: new Date('2024-12-31')
});
```

Process/Execute payment:
```typescript
const result = await payflow.payments.execute('payment-id');
```

Refund payment:
```typescript
const refund = await payflow.payments.refund({
  transactionId: 'payment-id',
  amount: 500, // Partial refund (optional)
  reason: 'Customer request'
});
```

### Supported Payment Methods

```typescript
enum PaymentMethod {
  BKASH = 'BKASH',
  NAGAD = 'NAGAD',
  ROCKET = 'ROCKET',
  UPAY = 'UPAY',
  MCASH = 'MCASH',
  VISA = 'VISA',
  MASTERCARD = 'MASTERCARD',
  AMEX = 'AMEX',
  INTERNET_BANKING = 'INTERNET_BANKING',
}
```

### Error Handling

```typescript
import { PayflowSDKError, PayflowValidationError, PayflowNetworkError } from 'payflow-sdk';

try {
  const payment = await payflow.payments.create(paymentData);
} catch (error) {
  if (error instanceof PayflowSDKError) {
    console.error('API Error:', error.code, error.message);
  } else if (error instanceof PayflowValidationError) {
    console.error('Validation Error:', error.message);
  } else if (error instanceof PayflowNetworkError) {
    console.error('Network Error:', error.message);
  }
}
```

## Framework Examples

### React

```tsx
import React, { useState } from 'react';
import { PayflowSDK, PaymentMethod } from 'payflow-sdk';

const payflow = new PayflowSDK({
  apiKey: process.env.REACT_APP_PAYFLOW_API_KEY!,
  environment: 'sandbox'
});

function PaymentButton() {
  const [loading, setLoading] = useState(false);
  
  const handlePayment = async () => {
    setLoading(true);
    try {
      const payment = await payflow.payments.create({
        amount: 1000,
        currency: 'BDT',
        paymentMethod: PaymentMethod.BKASH,
      });
      
      // Redirect to payment URL
      window.location.href = payment.paymentUrl!;
    } catch (error) {
      console.error('Payment failed:', error);
    } finally {
      setLoading(false);
    }
  };
  
  return (
    <button onClick={handlePayment} disabled={loading}>
      {loading ? 'Processing...' : 'Pay with bKash'}
    </button>
  );
}
```

### Node.js

```javascript
const { PayflowSDK, PaymentMethod } = require('payflow-sdk');

const payflow = new PayflowSDK({
  apiKey: process.env.PAYFLOW_API_KEY,
  environment: 'production'
});

// Express.js route example
app.post('/create-payment', async (req, res) => {
  try {
    const payment = await payflow.payments.create({
      amount: req.body.amount,
      currency: 'BDT',
      paymentMethod: req.body.paymentMethod,
      customerInfo: req.body.customerInfo
    });
    
    res.json({ success: true, payment });
  } catch (error) {
    res.status(400).json({ success: false, error: error.message });
  }
});
```

## License

MIT