Node.js / TypeScript SDK

The official Novasend SDK for Node.js allows you to quickly integrate Mobile Money payments, transfers, and refunds into your backend applications.

Installation

Install the package via your preferred package manager:

npm install novasend-sdk

Configuration

The SDK uses environment variables for maximum security. Never hardcode your keys.

.env

NOVASEND_API_KEY=your_public_key
NOVASEND_SECRET_KEY=your_secret_key
NOVASEND_BASE_URL=https://business.novasend.app

Quick Start

Client Initialization

import { NovasendClient } from "novasend-sdk";
 
const client = new NovasendClient({
  apiKey: process.env.NOVASEND_API_KEY!,
  secretKey: process.env.NOVASEND_SECRET_KEY!,
  baseUrl: process.env.NOVASEND_BASE_URL!,
  language: "en", // 'fr' or 'en'
});

Create a Payment (Wallet)

This method generates a redirect link to the Novasend payment portal.

const response = await client.createWalletPayment({
  reference: "order_12345",
  amount: 2500,
  msisdn: "+2250700000000",
  customerName: "John Doe",
  country: "CI",
  action: {
    successUrl: "https://your-site.com/success",
    failureUrl: "https://your-site.com/cancel",
  },
});
 
console.log("Payment Link:", response.paymentUrl);

Check Status

const status = await client.getPaymentStatus("order_12345");
console.log("Status:", status.status); // 'processing', 'processed', 'failed', 'expired'

Built-in Validation

The SDK validates your data locally before sending the request to avoid unnecessary calls:

Payment Amount: 100 to 2,000,000 FCFA.
Transfer Amount: 200 to 1,500,000 FCFA.
Phone Format: Validates +225 (CI) and +237 (CM) formats.
Orange OTP: Required if the provider is Orange Money for direct payment.

⚠️

Always use an X-Idempotency-Key (automatically handled by the SDK) to prevent double charges in case of network issues.

Webhook Handling

To receive payment confirmations, set up an endpoint on your server and use the signature verification utility.

import { NovasendWebhooks } from "novasend-sdk";
 
const webhooks = new NovasendWebhooks(process.env.NOVASEND_WEBHOOK_SECRET!);
 
// In your Express/Next.js controller
const signature = req.headers["x-signature-value"];
try {
  const event = webhooks.verifySignature(req.body, signature);
  // Process the event (event.status, event.reference, etc.)
} catch (err) {
  // Invalid signature
}

Errors PHP