# PayUnit Node.js SDK

[![semantic-release](https://img.shields.io/badge/%20%20%F0%9F%93%A6%F0%9F%9A%80-semantic--release-e10079.svg)](https://github.com/semantic-release/semantic-release)

A TypeScript/Node.js SDK for integrating with the PayUnit payment gateway. This SDK provides a simple and secure way to process payments, manage invoices, handle checkouts, and process disbursements in your Node.js applications.

## Table of Contents

- [PayUnit Node.js SDK](#payunit-nodejs-sdk)
  - [Table of Contents](#table-of-contents)
  - [Features](#features)
  - [Prerequisites](#prerequisites)
  - [Installation](#installation)
  - [Configuration](#configuration)
    - [Configuration Options](#configuration-options)
  - [Usage](#usage)
    - [1. Collections Service](#1-collections-service)
      - [1.1 Initiate Payment](#11-initiate-payment)
      - [1.2 Pay with card](#12-pay-with-card)
      - [1.3 Make Payment (Mobile Money)](#13-make-payment-mobile-money)
      - [1.4 Initiate and Make Payment (Mobile Money) - One Step](#14-initiate-and-make-payment-mobile-money---one-step)
      - [1.5 Get Transaction Status](#15-get-transaction-status)
    - [2. Checkout Service](#2-checkout-service)
      - [2.1 Initialize a Checkout Session](#21-initialize-a-checkout-session)
      - [2.2 Process Payment](#22-process-payment)
      - [2.3 Get Checkout Status](#23-get-checkout-status)
    - [3. Invoices Service](#3-invoices-service)
      - [3.1 Create a Normal Invoice](#31-create-a-normal-invoice)
      - [3.2 Create an Installment Invoice](#32-create-an-installment-invoice)
      - [3.3 Pay Invoice](#33-pay-invoice)
      - [3.4 Get Invoice](#34-get-invoice)
    - [4. Disbursements Service](#4-disbursements-service)
      - [4.1 Create Disbursement](#41-create-disbursement)
      - [4.2 Confirm Disbursement](#42-confirm-disbursement)
      - [4.3 Get Disbursement Status](#43-get-disbursement-status)
  - [Development](#development)
  - [Contributing](#contributing)
  - [License](#license)

## Features

- **Secure API Communication**: Built-in encryption and authentication
- **Semantic Versioning**: Follows semantic versioning for better version control
- **TypeScript Support**: Full TypeScript definitions for better development experience, types for requests and responses
- **Multiple Payment Methods**: Support for card payments and mobile money
- **Client Side Validation**: Built-in validation for requests and responses
- **Collections**: Process payments and verify transactions
- **Disbursements**: Initiate and manage payouts
- **Checkout**: Seamless checkout integration with customizable success/cancel URLs
- **Invoices**: Create and manage payment requests with support for normal and installment types

## Prerequisites

- Node.js 18.x or later
- npm 9.x or later
- A PayUnit merchant account with API credentials. click here to get credentials. [Payunit Mechant](https://pu.payunit.net)
- For developer documentation. click here. [Payunit Developer Documentation](https://developer.payunit.net)

## Installation

```bash
# Using npm
npm install @payunit/nodejs-sdk

# Or using Yarn
yarn add @payunit/nodejs-sdk

# Or using pnpm
pnpm add @payunit/nodejs-sdk
```

## Configuration

Create a configuration object with your PayUnit API credentials:

```typescript
import { PayunitClient } from '@payunit/nodejs-sdk';

// Initialize with configuration
const client = new PayunitClient({
  baseURL: 'https://gateway.payunit.net', // optional
  apiKey: 'your_api_key',
  apiUsername: 'your_api_username',
  apiPassword: 'your_api_password',
  mode: 'test', // or 'live',
  timeout: 10000, // optional
});
```

### Configuration Options

| Option        | Type               | Required | Default                       | Description                                    |
| ------------- | ------------------ | -------- | ----------------------------- | ---------------------------------------------- |
| `baseURL`     | `string`           | No       | `https://gateway.payunit.net` | Base URL for the PayUnit API                   |
| `apiKey`      | `string`           | Yes      | -                             | Your PayUnit API key                           |
| `apiUsername` | `string`           | Yes      | -                             | Your PayUnit API username                      |
| `apiPassword` | `string`           | Yes      | -                             | Your PayUnit API password                      |
| `mode`        | `'test' \| 'live'` | Yes      | -                             | API environment mode (either 'test' or 'live') |
| `timeout`     | `number`           | No       | `10000`                       | API request timeout in milliseconds            |

## Usage

### 1. Collections Service

The Collections service handles payment collection and transaction management.

#### 1.1 Initiate Payment

```typescript
const payment = await client.collections.initiatePayment({
  total_amount: 1000, // Amount
  currency: 'XAF',
  transaction_id: `TXN_${Date.now()}`,
  return_url: 'https://your-site.com/return',
  notify_url: 'https://your-site.com/webhook',
  payment_country: 'CM', // Optional
  pay_with: 'CM_MTNMOMO', // Optional
  redirect_on_failed: 'yes', // Optional, 'yes' or 'no'
  custom_fields: {
    // Optional custom fields
    order_id: '12345',
    customer_type: 'premium',
  },
});
```

#### 1.2 Pay with card

To pay with card you need to initiate the payment request first like

```typescript
const payment = await client.collections.initiatePayment({
  total_amount: 1000, // Amount in smallest currency unit (e.g., cents)
  currency: 'XAF',
  transaction_id: `TXN_${Date.now()}`,
  return_url: 'https://your-site.com/return',
  notify_url: 'https://your-site.com/webhook',
  payment_country: 'CM', // Optional
  pay_with: 'CM_MTNMOMO', // Optional
  redirect_on_failed: 'yes', // Optional, 'yes' or 'no'
  custom_fields: {
    // Optional custom fields
    order_id: '12345',
    customer_type: 'premium',
  },
});
```

and then redirect to `transaction_url` in the web to complete the payment on our side.

#### 1.3 Make Payment (Mobile Money)

```typescript
const paymentResult = await client.collections.makePayment({
  amount: 1000,
  gateway: 'CM_MTNMOMO', // or 'CM_ORANGE'
  currency: 'XAF',
  transaction_id: 'TXN_123456',
  phone_number: '6XXXXXX',
  return_url: 'https://your-site.com/return',
  notify_url: 'https://your-site.com/webhook',
});
```

#### 1.4 Initiate and Make Payment (Mobile Money) - One Step

This method combines both initiate payment and make payment into a single call for mobile money transactions:

```typescript
const paymentResult = await client.collections.initiateAndMakePaymentMobileMoney({
  total_amount: 1000, // Amount
  currency: 'XAF',
  transaction_id: `TXN_${Date.now()}`,
  gateway: 'CM_MTNMOMO', // Required: mobile money provider
  phone_number: '6XXXXXX', // Required: customer phone number
  return_url: 'https://your-site.com/return', // Optional
  notify_url: 'https://your-site.com/webhook', // Optional
  payment_country: 'CM', // Optional
  redirect_on_failed: 'yes', // Optional, 'yes' or 'no'
  custom_fields: {
    // Optional custom fields
    order_id: '12345',
    customer_type: 'premium',
  },
});
```

#### 1.5 Get Transaction Status

```typescript
const status = await client.collections.getTransactionStatus('TXN_123456');
```

### 2. Checkout Service

The Checkout service allows you to create payment sessions and process payments.

#### 2.1 Initialize a Checkout Session

```typescript
const checkoutSession = await client.checkout.initialize({
  cancel_url: 'https://your-site.com/cancel',
  success_url: 'https://your-site.com/success',
  notify_url: 'https://your-site.com/webhook', // Optional
  currency: 'XAF',
  mode: 'payment', // or 'subscription'
  transaction_id: `TXN_${Date.now()}`,
  total_amount: 1000, // Amount in smallest currency unit (e.g., cents)
  payment_country: 'CM', // Optional
  items: [
    {
      price_description: {
        unit_amount: 100,
      },
      product_description: {
        name: 'Test Item',
        image_url: 'https://example.com/image.jpg',
        about_product: 'Test product description',
      },
      quantity: 1,
    },
  ],
  customer: {
    name: 'John Doe',
    email: 'john@example.com',
    phone: '6XXXXXX',
  },
  meta: {
    phone_number_collection: true,
    address_collection: true,
  },
});
```

#### 2.2 Process Payment

```typescript
const paymentResult = await client.checkout.processPayment({
  checkout_id: checkoutSession.checkoutId,
  customer: {
    email: 'john@example.com',
    phone: '6XXXXXX',
    country: 'CM',
    name: 'John Doe',
  },
  shipping: {
    address: '123 Test St',
    phone: '6XXXXXX',
    payment_method: 'CM_MTNMOMO',
    payment_info: {
      phone: '6XXXXXX',
    },
  },
});
```

#### 2.3 Get Checkout Status

```typescript
const status = await client.checkout.getStatus('checkout_123');
```

### 3. Invoices Service

The Invoice service allows you to create and manage payment invoices.

#### 3.1 Create a Normal Invoice

```typescript
const invoice = await client.invoice.createInvoice({
  client_name: 'John Doe',
  client_email: 'john@example.com',
  client_phone_number: '6XXXXXX',
  due_date: new Date(Date.now() + 7 * 24 * 60 * 60 * 1000).toISOString(),
  partial_payment: false,
  is_custom_company: false,
  type: 'NORMAL',
  currency: 'XAF',
  callback_url: 'https://your-site.com/callback',
  items: [
    {
      name: 'Service Fee',
      amount: 1000,
      quantity: 1,
    },
  ],
  // Optional custom billing company
  custom_billing_company: {
    name: 'Your Company',
    logo: 'https://your-company.com/logo.png',
    email: 'billing@your-company.com',
    phone_number: '6XXXXXX',
  },
});
```

#### 3.2 Create an Installment Invoice

```typescript
const invoice = await client.invoice.createInvoice({
  client_name: 'John Doe',
  client_email: 'john@example.com',
  client_phone_number: '6XXXXXX',
  due_date: new Date(Date.now() + 7 * 24 * 60 * 60 * 1000).toISOString(),
  partial_payment: true,
  type: 'INSTALLMENT',
  currency: 'XAF',
  callback_url: 'https://your-site.com/callback',
  items: [
    {
      name: 'Installment Plan',
      amount: 3000,
      quantity: 1,
    },
  ],
  installments: [
    { title: 'Installment 1', due_date: '2023-07-01', amount: 1000 },
    { title: 'Installment 2', due_date: '2023-08-01', amount: 1000 },
    { title: 'Installment 3', due_date: '2023-09-01', amount: 1000 },
  ],
});
```

#### 3.3 Pay Invoice

```typescript
const invoicePayment = await client.invoice.payInvoice({
  invoice_id: 'INV_123456', // invoice.uuid
  amount: 1000,
  currency: 'XAF',
  callback_url: 'https://your-site.com/callback', // optional
  installment_id: 'INS_123456', // if invoice typeis installment installment uuid
});
```

#### 3.4 Get Invoice

```typescript
const invoiceDetails = await client.invoice.getInvoice('INV_123456');
```

### 4. Disbursements Service

The Disbursement service allows you to send money to bank accounts or mobile money wallets.

#### 4.1 Create Disbursement

```typescript
const disbursement = await client.disbursement.createDisbursement({
  destination_currency: 'XAF',
  debit_currency: 'XAF',
  account_number: '2376XXXXXX',
  amount: 1000,
  beneficiary_name: 'John Doe',
  deposit_type: 'MOBILE_MONEY',
  transaction_id: `DISB_${Date.now()}`,
  country: 'CM',
  account_bank: 'CM_MTNMOMO', // or 'CM_ORANGE'.
});
```

#### 4.2 Confirm Disbursement

```typescript
const confirmation = await client.disbursement.confirmDisbursement({
  pay_token: disbursement.pay_token,
  deposit_message: 'Payment for services',
  deposit_note: 'Thank you for your service',
  notify_url: 'https://your-site.com/webhook',
});
```

#### 4.3 Get Disbursement Status

```typescript
const status = await client.disbursement.getDisbursementStatus('DISB_123456');
```

## Development

1. Clone the repository
2. Install dependencies: `npm install`
3. Build the project: `npm run build`
4. Run tests: `npm test`
5. Run linter: `npm run lint`
6. Run formatter: `npm run format`
7. Run before publish: `npm run beforePublish` to test the whole code and process

## Contributing

Contributions are welcome! Please read our [contributing guidelines](CONTRIBUTING.md) before submitting pull requests.

## License

ISC