PayUnit Node.js SDK

(opens in a new tab)

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.

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 (opens in a new tab)
For developer documentation. click here. Payunit Developer Documentation (opens in a new tab)

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', // 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

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

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

Last updated on June 24, 2025

Pay Invoice Flutter