PawaPay Node.js SDK

Official Node.js SDK for PawaPay - Accept mobile money and card payments in Ghana.

Installation

npm install pawapay-node

or

yarn add pawapay-node

Quick Start

import PawaPay from 'pawapay-node';

// Initialize with your API key
const pay = new PawaPay('sk_test_your_api_key');

// Charge via mobile money
const payment = await pay.momo.charge({
  amount: 10000, // Amount in pesewas (100 GHS)
  phone: '233244123456',
  network: 'MTN',
  email: '[email protected]'
});

console.log(payment);

Features

• ✅ Mobile Money payments (MTN, Vodafone, AirtelTigo)
• ✅ Hosted checkout page
• ✅ Payment verification
• ✅ TypeScript support
• ✅ Promise-based API
• ✅ Automatic retries
• ✅ Test mode support

Usage

Initialize the SDK

import PawaPay from 'pawapay-node';

const pay = new PawaPay('sk_test_your_api_key');

// Or with custom base URL
const pay = new PawaPay('sk_test_your_api_key', 'https://api.pawapay.com/api/v1');

Mobile Money Payments

Direct Charge

try {
  const payment = await pay.momo.charge({
    amount: 10000, // Amount in pesewas (100 GHS)
    phone: '233244123456',
    network: 'MTN', // MTN, VODAFONE, or AIRTELTIGO
    email: '[email protected]',
    currency: 'GHS', // Optional, defaults to GHS
    metadata: { // Optional
      order_id: '12345',
      customer_name: 'John Doe'
    }
  });

  console.log('Payment Reference:', payment.paymentReference);
  console.log('Status:', payment.status);
} catch (error) {
  console.error('Payment failed:', error.message);
}

Hosted Checkout

Initialize Payment

try {
  const transaction = await pay.payments.initialize({
    email: '[email protected]',
    amount: 10000, // Amount in pesewas
    currency: 'GHS', // Optional
    callback_url: 'https://yoursite.com/callback', // Optional
    metadata: { // Optional
      order_id: '12345'
    }
  });

  console.log('Checkout URL:', transaction.data.authorization_url);
  console.log('Reference:', transaction.data.reference);

  // Redirect customer to checkout URL
  // transaction.data.authorization_url
} catch (error) {
  console.error('Initialization failed:', error.message);
}

Verify Payment

try {
  const verification = await pay.payments.verify('transaction_reference');

  if (verification.data.status === 'success') {
    console.log('Payment successful!');
    console.log('Amount:', verification.data.amount);
    console.log('Customer:', verification.data.customer.email);
    
    // Deliver value to customer
  } else {
    console.log('Payment not successful:', verification.data.status);
  }
} catch (error) {
  console.error('Verification failed:', error.message);
}

API Reference

PawaPay

Constructor

new PawaPay(apiKey: string, baseURL?: string)

• apiKey (required): Your PawaPay API key (starts with sk_test_ or sk_live_)
• baseURL (optional): Custom API base URL

Mobile Money (pay.momo)

charge()

pay.momo.charge(params: MobileMoneyChargeParams): Promise<PaymentResponse>

Parameters:

interface MobileMoneyChargeParams {
  amount: number;           // Amount in pesewas
  phone: string;            // Customer phone number (e.g., '233244123456')
  network: 'MTN' | 'VODAFONE' | 'AIRTELTIGO';
  email: string;            // Customer email
  currency?: string;        // Currency code (default: 'GHS')
  metadata?: Record<string, any>; // Additional data
}

Returns:

interface PaymentResponse {
  success: boolean;
  paymentReference?: string;
  status?: string;
  message?: string;
}

Payments (pay.payments)

initialize()

pay.payments.initialize(params: PaymentInitializeParams): Promise<InitializeResponse>

Parameters:

interface PaymentInitializeParams {
  email: string;            // Customer email
  amount: number;           // Amount in pesewas
  currency?: string;        // Currency code (default: 'GHS')
  callback_url?: string;    // URL to redirect after payment
  metadata?: Record<string, any>; // Additional data
}

Returns:

interface InitializeResponse {
  status: boolean;
  message: string;
  data: {
    authorization_url: string;  // Checkout page URL
    access_code: string;        // Access code for the transaction
    reference: string;          // Transaction reference
  };
}

verify()

pay.payments.verify(reference: string): Promise<VerifyResponse>

Parameters:

• reference (required): Transaction reference from initialization

Returns:

interface VerifyResponse {
  status: boolean;
  message: string;
  data: {
    id: string;
    amount: number;
    currency: string;
    status: string;           // 'success', 'failed', 'pending', etc.
    reference: string;
    paid_at: string | null;
    created_at: string;
    channel: string;
    customer: {
      email: string;
      phone?: string;
    };
    metadata?: Record<string, any>;
  };
}

Test Mode

Use test API keys (starting with sk_test_) for testing. In test mode:

• No real money is charged
• All payments are simulated
• Use any phone number and it will succeed

Test API Key Example:

const pay = new PawaPay('sk_test_4286d96cbb7c393a6f0a5c31f2be8ae5952b65cd4554ca63776fc021a5db5c1c');

Error Handling

All methods throw errors that should be caught:

try {
  const payment = await pay.momo.charge({
    amount: 10000,
    phone: '233244123456',
    network: 'MTN',
    email: '[email protected]'
  });
} catch (error) {
  console.error('Error:', error.message);
  // Handle error appropriately
}

TypeScript Support

The SDK is written in TypeScript and includes type definitions:

import PawaPay, { 
  MobileMoneyChargeParams, 
  PaymentResponse,
  InitializeResponse,
  VerifyResponse 
} from 'pawapay-node';

const pay = new PawaPay('sk_test_your_api_key');

const params: MobileMoneyChargeParams = {
  amount: 10000,
  phone: '233244123456',
  network: 'MTN',
  email: '[email protected]'
};

const payment: PaymentResponse = await pay.momo.charge(params);

Examples

Express.js Integration

import express from 'express';
import PawaPay from 'pawapay-node';

const app = express();
const pay = new PawaPay(process.env.PAWAPAY_SECRET_KEY);

app.use(express.json());

// Initialize payment
app.post('/pay', async (req, res) => {
  try {
    const { email, amount } = req.body;
    
    const transaction = await pay.payments.initialize({
      email,
      amount: amount * 100, // Convert to pesewas
      callback_url: `${req.protocol}://${req.get('host')}/callback`
    });

    res.json({
      checkout_url: transaction.data.authorization_url,
      reference: transaction.data.reference
    });
  } catch (error) {
    res.status(400).json({ error: error.message });
  }
});

// Payment callback
app.get('/callback', async (req, res) => {
  try {
    const { reference } = req.query;
    
    const verification = await pay.payments.verify(reference);

    if (verification.data.status === 'success') {
      // Payment successful - deliver value
      res.send('Payment successful!');
    } else {
      res.send('Payment failed');
    }
  } catch (error) {
    res.status(400).send('Verification failed');
  }
});

app.listen(3000);

Next.js API Route

// pages/api/initialize-payment.js
import PawaPay from 'pawapay-node';

const pay = new PawaPay(process.env.PAWAPAY_SECRET_KEY);

export default async function handler(req, res) {
  if (req.method !== 'POST') {
    return res.status(405).json({ error: 'Method not allowed' });
  }

  try {
    const { email, amount } = req.body;

    const transaction = await pay.payments.initialize({
      email,
      amount,
      callback_url: `${process.env.NEXT_PUBLIC_URL}/payment/callback`
    });

    res.json(transaction.data);
  } catch (error) {
    res.status(400).json({ error: error.message });
  }
}

Support

• Documentation: https://docs.pawapay.com
• Email: [email protected]
• GitHub Issues: https://github.com/pawapay/node-sdk/issues

License

MIT License - see LICENSE file for details