@payunit/nodejs-sdk v1.1.0

PayUnit Node.js SDK

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
  • Table of Contents
  • Features
  • Prerequisites
  • Installation
  • Configuration
    • Configuration Options
  • Usage
    • 1. Collections Service
      • 1.1 Initiate Payment
      • 1.2 Pay with card
      • 1.3 Make Payment (Mobile Money)
      • 1.4 Get Transaction Status
    • 2. Checkout Service
      • 2.1 Initialize a Checkout Session
      • 2.2 Process Payment
      • 2.3 Get Checkout Status
    • 3. Invoices Service
      • 3.1 Create a Normal Invoice
      • 3.2 Create an Installment Invoice
      • 3.3 Pay Invoice
      • 3.4 Get Invoice
    • 4. Disbursements Service
      • 4.1 Create Disbursement
      • 4.2 Confirm Disbursement
      • 4.3 Get Disbursement Status
  • Development
  • Contributing
  • License

Features

• Secure API Communication: Built-in encryption and authentication
• TypeScript Support: Full TypeScript definitions for better development experience
• Multiple Payment Methods: Support for card payments and mobile money
• 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
• For developer documentation. click here. Payunit Developer Documentation

Installation

# 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:

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

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

Configuration Options

Usage

1. Collections Service

The Collections service handles payment collection and transaction management.

1.1 Initiate Payment

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',
  },
});

1.2 Pay with card

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

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)

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

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

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

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

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

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

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

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

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

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

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

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 before submitting pull requests.

License

ISC