@payunit/nodejs-sdk
Version:
PayUnit Payment Processor SDK
372 lines (308 loc) • 11.4 kB
Markdown
# PayUnit Node.js SDK
[](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 Get Transaction Status](#14-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 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