Pesapal3 Documentation

Pesapal3

Pesapal3 is a comprehensive Node.js library for integrating Pesapal payment solutions into your applications. Simplify payment processing with our easy-to-use SDK.

Installation

npm install pesapal3

Quick Start


import { initialisePesapal, Iconfig, IpayDetails } from "pesapal3";

const config: Iconfig = {
  PESAPAL_ENVIRONMENT: "live", // or "sandbox"
  PESAPAL_CONSUMER_KEY: "your-consumer-key",
  PESAPAL_CONSUMER_SECRET: "your-consumer-secret",
  PESAPAL_IPN_URL: "https://yourserverdomain/pesapal/ipn",
};

const paymentInstance = initialisePesapal(config);

const details: IpayDetails = {
  amount: 1000,
  currency: "USD",
  description: "This is a test payment",
  // ...other_details
};

const ordered = await paymentInstance.submitOrder(
  details,
  "ProductId",
  "description"
);

if (ordered.success) {
  console.log(ordered.response);
} else {
  console.error(ordered.error);
}

Core Concepts

Authentication

Secure your API calls with consumer key and secret authentication.

Payments

Easily initiate, track, and manage payment transactions.

Transactions

Get real-time updates and detailed transaction information.

Configuration

Configuration Interface


interface Iconfig {
  PESAPAL_ENVIRONMENT: 'sandbox' | 'live';
  PESAPAL_CONSUMER_KEY: string;
  PESAPAL_CONSUMER_SECRET: string;
  PESAPAL_IPN_URL: string;
}

Environment Setup


// Sandbox Environment (Testing)
const sandboxConfig: Iconfig = {
  PESAPAL_ENVIRONMENT: 'sandbox',
  PESAPAL_CONSUMER_KEY: 'SANDBOX_KEY',
  PESAPAL_CONSUMER_SECRET: 'SANDBOX_SECRET',
  PESAPAL_IPN_URL: 'https://sandbox.yourserverdomain/pesapal/ipn'
};

// Live Environment (Production)
const liveConfig: Iconfig = {
  PESAPAL_ENVIRONMENT: 'live',
  PESAPAL_CONSUMER_KEY: 'LIVE_KEY',
  PESAPAL_CONSUMER_SECRET: 'LIVE_SECRET',
  PESAPAL_IPN_URL: 'https://yourserverdomain/pesapal/ipn'
};

Core Methods

Payment Submission


  async function processPayment() {
  const pesapal = await initialisePesapal(config);

  const paymentDetails = {
    id: generateUniqueId(),
    currency: 'UGX',
    amount: 10000,
    description: 'Product Purchase',
    callback_url: 'https://yoursite.com/payment-callback',
    billing_address: {
      email_address: '[email protected]',
      phone_number: '+256712345678',
      country_code: 'UGA',
      first_name: 'John',
      last_name: 'Doe'
    }
  };

  const orderResponse = await pesapal.submitOrder(
    paymentDetails, 
    'PRODUCT123', 
    'Sample Product Purchase'
  );

  if (orderResponse.success) {
    console.log(orderResponse.pesaPalOrderRes?.redirect_url);
  }
}

Transaction Status


async function checkTransactionStatus(orderTrackingId: string) {
  const pesapal = await initialisePesapal(config);

  const statusResponse = await pesapal.getTransactionStatus(orderTrackingId);

  if (statusResponse.success) {
    console.log('Transaction Details:', statusResponse.response);
  }
}

submitOrder()

Submit a new payment order with comprehensive details.

getTransactionStatus()

Retrieve the current status of a specific transaction.

refundRequest()

Process refunds for completed transactions.

Error Handling

Custom Error Types


// Custom Error Types
class PesaPalError extends Error {
  constructor(
    public code: string, 
    public details?: any
  ) {
    super(code);
    this.name = 'PesaPalError';
  }
}

Error Handling Example


try {
  const transaction = await pesapal.submitOrder(details);
} catch (error) {
  if (error instanceof PesaPalError) {
    switch (error.code) {
      case 'INVALID_CREDENTIALS':
        // Handle authentication error
        break;
      case 'INSUFFICIENT_FUNDS':
        // Handle payment failure
        break;
      default:
        // Generic error handling
    }
  }
}

Make Order

Creating a Payment

Initiate a payment by providing transaction details and customer information.


const ordered = await paymentInstance.submitOrder(
  details,
  "ProductId",
  "description"
);

if (ordered.success) {
  console.log(ordered.response);
} else {
  console.error(ordered.error);
}

Payment Methods

Mobile Money
Credit/Debit Cards
Bank Transfer

Supported payment methods vary by region and integration type.

Payment Status


// Check payment status
const response = await paymentInstance.getTransactionStatus(orderTrackingId);
  return response;

API Methods

Method	Description	Parameters	Returns
`submitOrder()`	Submit a new payment order	- `paymentDetails`: Payment details object - `productId`: Unique product identifier - `description`: Transaction description	Order submission response
`getTransactionStatus()`	Check the status of a specific transaction	- `orderTrackingId`: Unique order tracking ID	Transaction status details
`refundRequest()`	Process a refund for a completed transaction	- `refundRequestObj`: Refund request details	Refund request response
`registerIpn()`	Register an Instant Payment Notification (IPN) URL	- `ipn?`: Optional IPN URL - `notificationMethodType?`: Optional notification method	IPN registration result
`getIpnEndPoints()`	Retrieve registered IPN endpoints	None	List of IPN endpoints
`getToken()`	Obtain authentication token	None	Authentication token details

Pro Tip

Always handle potential errors when calling these methods. Use try-catch blocks and check the `success` property of the response to ensure proper error handling.

Support

Need help? Check out our support resources or contact our team.

Environment Configuration

Sandbox vs Live

Pesapal3 supports two environments to streamline your development and production workflows.


// Sandbox Environment (Testing)
const sandboxConfig: Iconfig = {
  PESAPAL_ENVIRONMENT: 'sandbox',
  PESAPAL_CONSUMER_KEY: 'SANDBOX_KEY',
  PESAPAL_CONSUMER_SECRET: 'SANDBOX_SECRET',
  PESAPAL_IPN_URL: 'https://sandbox.yourserverdomain/pesapal/ipn'
};

// Live Environment (Production)
const liveConfig: Iconfig = {
  PESAPAL_ENVIRONMENT: 'live',
  PESAPAL_CONSUMER_KEY: 'LIVE_KEY',
  PESAPAL_CONSUMER_SECRET: 'LIVE_SECRET',
  PESAPAL_IPN_URL: 'https://yourserverdomain/pesapal/ipn'
};

Best Practices

Always use sandbox for development and testing
Never use sandbox credentials in production
Rotate credentials periodically
Use environment variables for sensitive information

Pro Tip: Use different configuration files or environment-specific .env files