pawapay-sdk

PawaPay SDK for Node.js

This SDK is a one-to-one mapping with the official pawaPay API documentation.
Please always refer to the official docs for the most up-to-date API details.
https://docs.pawapay.io/v1/api-reference/

A comprehensive TypeScript/JavaScript SDK for integrating with the pawaPay API, enabling seamless mobile money operations such as deposits, payouts, refunds, wallet balance checks, and more.

Features

• Deposits: Initiate, check status, and manage deposit transactions.
• Payouts: Send single or bulk payouts, check payout status, resend callbacks, and cancel enqueued payouts.
• Refunds: Request refunds, check refund status, and resend refund callbacks.
• Wallets: Retrieve wallet balances by country or overall.
• Payment Pages: Generate hosted payment pages for customer payments.
• Toolkit: Access configuration, available correspondents, correspondent prediction, and public keys.

Installation

npm install pawapay-sdk

Generating UUIDs for Transaction IDs

You can generate UUIDs for depositId, payoutId, and refundId using the uuid package (version 4):

npm install uuid

import { v4 as uuidv4 } from 'uuid';

const depositId = uuidv4();
const payoutId = uuidv4();
const refundId = uuidv4();

Usage

import { PawaPayClient } from 'pawapay-sdk';

const client = new PawaPayClient('YOUR_API_KEY', { environment: 'sandbox' });

API Reference & Examples

Deposits

• requestDeposit(data, options?): Initiate a deposit.

import { v4 as uuidv4 } from 'uuid';
const depositConfig = {
  depositId: uuidv4(),
  amount: '100.00',
  currency: 'MWK',
  country: 'MWI',
  correspondent: 'AIRTEL_MWI',
  payer: { type: 'MSISDN', address: { value: '265991234567' } },
  customerTimestamp: new Date().toISOString(),
  statementDescription: 'Payment for order 1234',
  metadata: [{ fieldName: 'orderId', fieldValue: '1234' }]
};
const depositResponse = await client.requestDeposit(depositConfig);

• checkDepositStatus(depositId, options?): Get status of a deposit.

const statusResponse = await client.checkDepositStatus(depositConfig.depositId);

• resendDepositCallback(depositId, options?): Resend deposit callback.

const resendResponse = await client.resendDepositCallback(depositConfig.depositId);

Payouts

• requestPayout(data, options?): Initiate a payout.

import { v4 as uuidv4 } from 'uuid';
const payoutConfig = {
  payoutId: uuidv4(),
  amount: '50.00',
  currency: 'MWK',
  correspondent: 'AIRTEL_MWI',
  recipient: '265991234567',
  customerTimestamp: new Date().toISOString(),
  statementDescription: 'Payout for service',
  country: 'MWI',
  metadata: []
};
const payoutResponse = await client.requestPayout(payoutConfig);

• checkPayoutStatus(payoutId, options?): Get payout status.

const payoutStatus = await client.checkPayoutStatus(payoutConfig.payoutId);

• resendPayoutCallback(payoutId, options?): Resend payout callback.

const resendPayout = await client.resendPayoutCallback(payoutConfig.payoutId);

• cancelEnqueuedPayout(payoutId, options?): Cancel an enqueued payout.

const cancelResponse = await client.cancelEnqueuedPayout(payoutConfig.payoutId);

• requestBulkPayout(data[], options?): Send multiple payouts in bulk.

const bulkPayouts = [payoutConfig, { ...payoutConfig, payoutId: uuidv4() }];
const bulkResponse = await client.requestBulkPayout(bulkPayouts);

Refunds

• requestRefund(refundConfig, options?): Request a refund.

import { v4 as uuidv4 } from 'uuid';
const refundConfig = {
  refundId: uuidv4(),
  depositId: depositConfig.depositId,
  amount: '100.00',
  metadata: [{ fieldName: 'reason', fieldValue: 'Customer request' }]
};
const refundResponse = await client.requestRefund(refundConfig);

• checkRefundStatus(refundId, options?): Get refund status.

const refundStatus = await client.checkRefundStatus(refundConfig.refundId);

• resendRefundCallback(refundId, options?): Resend refund callback.

const resendRefund = await client.resendRefundCallback(refundConfig.refundId);

Payment Pages

• requestPaymentPage(payload, options?): Create a hosted payment page session.

const payPageConfig = {
  depositId: uuidv4(),
  returnUrl: 'https://merchant.com/paymentProcessed',
  statementDescription: 'Ticket purchase',
  amount: '20.00',
  msisdn: '265991234567',
  language: 'EN',
  country: 'MWI',
  reason: 'Event ticket',
  metadata: [{ fieldName: 'eventId', fieldValue: 'E123' }]
};
const payPageResponse = await client.requestPaymentPage(payPageConfig);

Wallets

• checkWalletBalances(options?): Get all wallet balances.

const walletBalances = await client.checkWalletBalances({});

• checkWalletBalancesByCountry(country, options?): Get wallet balances for a specific country.

const mwBalances = await client.checkWalletBalancesByCountry('MWI', {});

Toolkit

• getActiveConfiguration(options?): Get merchant configuration and supported correspondents.

const config = await client.getActiveConfiguration({});

• getAvailableCorrespondent(options?): List available correspondents and their operational status.

const correspondents = await client.getAvailableCorrespondent({});

• predictCorrespondent(msisdn, options?): Predict the correct correspondent for a phone number.

const prediction = await client.predictCorrespondent('265991234567', {});

• getPublicKey(options?): Retrieve public keys for callback signature verification.

const publicKeys = await client.getPublicKey({});

Error Handling

All methods return a PawaPayResponse<T, E> object:

const response = await client.requestDeposit(depositConfig);
if (response.success) {
  // Access response.data
  console.log('Success:', response.data);
} else {
  // Access response.error and response.status
  console.error('Error:', response.error, 'Status:', response.status);
}

Types

The following TypeScript types are exported by the pawapay-sdk package and can be imported for use in your own code:

• PawaPayError
• DepositConfig
• DepositResponse
• RequestPayoutConfig
• RequestBulkPayoutConfig
• RequestPayPageConfig
• RequestRefundConfig
• WalletBalance
• PawaPayResponse<T, E>
• BaseRequestPayoutResponse
• RequestBulkPayoutResponse
• RequestPayPageResponse
• RequestRefundResponse
• WalletBalanceResponse
• DepositCallback
• PayoutCallback
• RefundCallback
• PayPageCallback

Example:

import { DepositConfig, PawaPayResponse, PawaPayError } from "pawapay-sdk";

• checkWalletBalancesByCountry(country, options?): Get wallet balances for a specific country.

const mwBalances = await client.checkWalletBalancesByCountry('MWI', {});

Toolkit

• getActiveConfiguration(options?): Get merchant configuration and supported correspondents.

const config = await client.getActiveConfiguration({});

• getAvailableCorrespondent(options?): List available correspondents and their operational status.

const correspondents = await client.getAvailableCorrespondent({});

• predictCorrespondent(msisdn, options?): Predict the correct correspondent for a phone number.

const prediction = await client.predictCorrespondent('265991234567', {});

• getPublicKey(options?): Retrieve public keys for callback signature verification.

const publicKeys = await client.getPublicKey({});

Error Handling

All methods return a PawaPayResponse<T, E> object:

const response = await client.requestDeposit(depositConfig);
if (response.success) {
  // Access response.data
  console.log('Success:', response.data);
} else {
  // Access response.error and response.status
  console.error('Error:', response.error, 'Status:', response.status);
}

Environments

• sandbox: For testing and development
• live: For production use

Connect

• Twitter
• LinkedIn
• GitHub

License

MIT