PayChangu TypeScript Library

A TypeScript library for integrating with the PayChangu payment gateway, supporting online payments and mobile money transactions in Malawi.

Installation

npm install paychangu-ts --save

or using yarn:

yarn add paychangu-ts

Usage

Initialize the PayChangu Service

import { PaymentsService } from 'paychangu-ts';

const paymentsService = new PaymentsService({
  apiKey: 'your-api-key-here',
  // Optional: override the base URL
  // baseURL: 'https://api.paychangu.com'
});

Initiate a Payment

const initiatePayment = async () => {
  try {
    const response = await paymentsService.initiatePayment({
      amount: 1000,
      email: '[email protected]',
      first_name: 'John',
      last_name: 'Doe',
      description: 'Payment for order #123',
      callbackUrl: 'https://your-website.com/callback',
      returnUrl: 'https://your-website.com/thank-you'
    });
    
    console.log('Payment initiated:', response);
    console.log('Checkout URL:', response.data.link);
    
    // Redirect the user to the checkout page
    // window.location.href = response.data.link;
  } catch (error) {
    console.error('Payment initiation failed:', error);
  }
};

Verify a Payment

const verifyPayment = async (txRef) => {
  try {
    const response = await paymentsService.verifyPayment(txRef);
    console.log('Payment verification:', response);
    
    if (response.data.status === 'successful') {
      // Payment was successful
      console.log('Payment was successful!');
    } else {
      // Payment failed or is pending
      console.log('Payment status:', response.data.status);
    }
  } catch (error) {
    console.error('Payment verification failed:', error);
  }
};

Inline Checkout

Important Note: The PayChangu inline checkout has specific requirements and limitations:

1. jQuery must be included on your page before the PayChangu script
2. A container element must exist on the page for the checkout to append to
3. If inline checkout fails, consider using standard checkout as a fallback

// 1. First include jQuery in your HTML
// <script src="https://code.jquery.com/jquery-3.6.0.min.js"></script>

// 2. Make sure you have a container in your HTML
// <div id="paychangu-checkout-container"></div>

// 3. Generate the configuration for inline checkout
const checkoutConfig = paymentsService.generateInlineCheckoutConfig({
  amount: 500,
  currency: 'MWK',
  customer: {
    email: '[email protected]',
    first_name: 'John',
    last_name: 'Doe'
  },
  callback_url: 'https://example.com/webhook',
  return_url: 'https://example.com/return',
  customization: {
    title: 'Purchase',
    description: 'Purchase description'
  }
});

// 4. Load the script and use the checkout function
import { loadPayChanguCheckoutScript } from 'paychangu-ts';

async function initiateCheckout() {
  try {
    await loadPayChanguCheckoutScript();
    
    // Use the configuration with the PayChangu checkout function
    window.PaychanguCheckout(checkoutConfig);
  } catch (error) {
    console.error('Error with inline checkout:', error);
    
    // Fallback to standard checkout if inline fails
    const standardCheckoutResponse = await paymentsService.initiatePayment({
      // Same parameters as above...
    });
    
    // Redirect to the standard checkout URL
    window.location.href = standardCheckoutResponse.data.checkout_url;
  }
}

Initiate a Mobile Money Payout

Note: Mobile money functionality may not be fully operational in the current PayChangu API. The library includes these methods for future compatibility, but they may not work as expected at this time.

Test Mobile Numbers

For testing mobile money functionality, PayChangu provides these test mobile numbers:

| Provider | Mobile Number | Result | |----------|--------------|--------| | Airtel Money | 990000000 | SUCCESS | | Airtel Money | 990000001 | FAILED | | TNM Mpamba | 899817565 | SUCCESS | | TNM Mpamba | 899817566 | FAILED |

const initiatePayout = async () => {
  try {
    const response = await paymentsService.initiateMobileMoneyPayout({
      mobile: '899817565', // TNM Mpamba test number (SUCCESS)
      amount: 500
    });
    
    console.log('Payout initiated:', response);
  } catch (error) {
    console.error('Payout initiation failed:', error);
  }
};

API Reference

PaymentsService

The main class for interacting with the PayChangu API.

Constructor

new PaymentsService(config: PayChanguConfig)

• config.apiKey (string, required): Your PayChangu API key
• config.baseURL (string, optional): Override the default API base URL

Methods

initiatePayment(params: PaymentInitParams): Promise<PaymentResponse>

Initiates a payment transaction.

verifyPayment(txRef: string): Promise<PaymentVerificationResponse>

Verifies the status of a payment transaction.

initiateMobileMoneyPayout(params: MobileMoneyPayoutParams): Promise<MobileMoneyPayoutResponse>

Initiates a mobile money payout.

License

ISC