Afrimomo SDK

v0.0.1-beta.13

A unified TypeScript SDK for seamless integration with African payment providers. Type-safe, reliable, and built for production.

Installation

npm install afrimomo-sdk
# or
pnpm add afrimomo-sdk
# or
yarn add afrimomo-sdk

The SDK requires Node.js 18.0.0 or higher and includes full TypeScript type definitions.

Quick Start

import { AfromomoSDK } from "afrimomo-sdk";

// Initialize the SDK
const sdk = new AfromomoSDK({
  environment: "sandbox", // or "production"
  pawapay: {
    apiToken: "your-pawapay-token"
  },
  paychangu: {
    secretKey: "your-paychangu-secret"
  }
});

// Use PawaPay
const payment = await sdk.pawapay.payments.initiate({
  depositId: "order-123",
  amount: "50.00",
  msisdn: "260971234567",
  country: "ZMB",
  returnUrl: "https://your-app.com/callback",
  statementDescription: "Payment for services",
  language: "EN",
  reason: "Service payment"
});

// Use PayChangu
const operators = await sdk.paychangu.getMobileMoneyOperators();

Configuration

The SDK supports both sandbox and production environments. Use sandbox credentials during development and switch to production when ready to process real payments.

import { AfromomoSDK, Environment } from "afrimomo-sdk";

const sdk = new AfromomoSDK({
  environment: Environment.SANDBOX, // or Environment.PRODUCTION
  pawapay: {
    apiToken: process.env.PAWAPAY_TOKEN
  },
  paychangu: {
    secretKey: process.env.PAYCHANGU_SECRET
  }
});

Security Tip: Never commit API keys to version control. Use environment variables or secure configuration management.

PawaPay API

Deposits

// Request a deposit
const deposit = await sdk.pawapay.payments.initiate({
  depositId: "unique-deposit-id",
  amount: "100.00",
  msisdn: "260971234567",
  country: "ZMB",
  returnUrl: "https://your-app.com/callback",
  statementDescription: "Online purchase",
  language: "EN",
  reason: "Payment for goods"
});

// Get deposit details
const details = await sdk.pawapay.payments.getDeposit(depositId);

// Resend callback
await sdk.pawapay.payments.resendCallback(depositId);

Payouts

// Send a payout
const payout = await sdk.pawapay.payouts.send({
  payoutId: "payout-123",
  amount: "50.00",
  msisdn: "260701234567",
  country: "ZMB",
  statementDescription: "Withdrawal"
});

// Send bulk payouts
const bulkPayout = await sdk.pawapay.payouts.sendBulk([
  {
    payoutId: "payout-001",
    amount: "25.00",
    msisdn: "260701234567",
    country: "ZMB"
  },
  {
    payoutId: "payout-002",
    amount: "30.00",
    msisdn: "260709876543",
    country: "ZMB"
  }
]);

// Get payout status
const status = await sdk.pawapay.payouts.getStatus(payoutId);

Wallet Management

// Get all wallet balances
const balances = await sdk.pawapay.wallets.getBalances();

// Get balance for specific country
const zambiaBalance = await sdk.pawapay.wallets.getCountryBalance("ZMB");

PayChangu API

Payments

// Initiate hosted checkout
const payment = await sdk.paychangu.initiatePayment({
  amount: 1000,
  currency: "MWK",
  tx_ref: "order-456",
  email: "customer@example.com",
  first_name: "John",
  last_name: "Doe",
  callback_url: "https://your-app.com/webhook",
  return_url: "https://your-app.com/success"
});

// Verify transaction
const verification = await sdk.paychangu.verifyTransaction(tx_ref);

// Initiate direct charge
const directCharge = await sdk.paychangu.initiateDirectChargePayment({
  amount: 5000,
  currency: "MWK",
  chargeId: "charge-789",
  accountInfo: {
    email: "customer@example.com",
    first_name: "John",
    last_name: "Doe"
  }
});

Mobile Money

// Get mobile money operators
const operators = await sdk.paychangu.getMobileMoneyOperators();

// Send mobile money payout
const payout = await sdk.paychangu.mobileMoneyPayout({
  amount: 2000,
  currency: "MWK",
  recipient_phone: "265991234567",
  operator_id: "operator-uuid",
  reference: "payout-123"
});

// Get payout details
const details = await sdk.paychangu.getMobilePayoutDetails(reference);

Bank Transfers

// Get supported banks
const banks = await sdk.paychangu.getSupportedBanks("MWK");

// Process bank transfer
const transfer = await sdk.paychangu.processBankTransfer({
  amount: 10000,
  currency: "MWK",
  bank_id: "bank-uuid",
  account_number: "123456789",
  account_name: "John Doe"
});

// Send bank payout
const bankPayout = await sdk.paychangu.bankPayout({
  amount: 5000,
  currency: "MWK",
  account_number: "987654321",
  bank_uuid: "bank-uuid",
  reference: "bank-payout-456"
});

Type Definitions

All types are exported from the main package. No deep imports needed:

// ✅ Correct way
import type {
  ActiveConfigResponse,
  PayChanguOperatorsResponse,
  PayChanguTypes,
  PawaPayTypes
} from "afrimomo-sdk";

// ❌ Avoid deep imports
import type { ActiveConfigResponse } from "afrimomo-sdk/dist/...";

Getting API Credentials

PawaPay

  1. Visit PawaPay and create a developer account
  2. Complete the onboarding process and verification
  3. Get your API token from the PawaPay dashboard
  4. Use sandbox tokens for testing

PayChangu

  1. Sign up at PayChangu
  2. Complete business verification
  3. Get your secret key from the merchant dashboard
  4. Use test credentials for sandbox environment

Used in Production

Vwaza Multimedia

Vwaza Multimedia uses Afrimomo SDK in production

Additional Resources