SDK
Nodejs SDK

PayUnit Node.js SDK

semantic-release (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.

Table of Contents

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

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

OptionTypeRequiredDefaultDescription
baseURLstringNohttps://gateway.payunit.netBase URL for the PayUnit API
apiKeystringYes-Your PayUnit API key
apiUsernamestringYes-Your PayUnit API username
apiPasswordstringYes-Your PayUnit API password
mode'test' | 'live'Yes-API environment mode (either 'test' or 'live')
timeoutnumberNo10000API 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 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:

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

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

Last updated on November 26, 2025
Pay InvoiceFlutter