pesapal-hono/DOCUMENTATION.md

A lightweight Pesapal payment gateway integration using Hono.js

# Pesapal API Client for Node.js

This is a Node.js client for interacting with the Pesapal API. It provides a convenient way to integrate Pesapal payment services into your Node.js applications.

## Installation

```bash
npm install pesapal-hono
```

## Usage

### Initialization

First, you need to initialize the Pesapal client with your consumer key, consumer secret, and the API base URL.

```typescript
import { Pesapal } from 'pesapal-hono';

const config = {
  consumerKey: 'YOUR_CONSUMER_KEY',
  consumerSecret: 'YOUR_CONSUMER_SECRET',
  apiBaseUrl: 'https://cybqa.pesapal.com/pesapalv3/api', // Use 'https://pay.pesapal.com/v3/api' for production
};

const pesapal = new Pesapal(config);
```

### Authentication

The client handles authentication automatically. You can, however, explicitly get an authentication token if needed.

```typescript
const token = await pesapal.getAuthToken();
console.log(token);
```

### IPN (Instant Payment Notification)

#### Register an IPN URL

```typescript
const response = await pesapal.registerIPN({
  url: 'YOUR_IPN_CALLBACK_URL',
  ipn_notification_type: 'POST', // or 'GET'
});
console.log(response);
```

### Payments

#### Initiate a Payment

```typescript
const response = await pesapal.submitOrder({
  id: 'ORDER_ID',
  currency: 'KES',
  amount: 100,
  description: 'Payment for goods',
  callback_url: 'YOUR_PAYMENT_CALLBACK_URL',
  notification_id: 'YOUR_IPN_ID',
  billing_address: {
    email_address: 'test@example.com',
    phone_number: '123456789',
    first_name: 'John',
    last_name: 'Doe',
  },
});
console.log(response);
```

### Transaction Status

#### Get Transaction Status

```typescript
const response = await pesapal.getTransactionStatus('ORDER_TRACKING_ID');
console.log(response);
```

## API Reference

The client exposes the following methods:

- `getAuthToken()`: Returns a promise that resolves to the authentication token.
- `registerIPN(data)`: Registers an IPN URL.
- `submitOrder(data)`: Initiates a payment.
- `getTransactionStatus(orderTrackingId)`: Gets the status of a transaction.

## Contributing

Contributions are welcome! Please open an issue or submit a pull request.

## License

This project is licensed under the MIT License.