payhere-sdk v0.1.0

Payhere API NodeJS Client

World class payments for your apps with Payhere API

Usage

Installation

Add the library to your project

npm install payhere-sdk --save-dev

User Credentials

You get the APP-ID, username and password from https://dashboard.payhere.africa/register.

The credentials for the sandbox environment can be used straight away. In production, the credentials are provided for you after KYC requirements are met.

Configuration

Before we can fully utilize the library, we need to specify global configurations. The global configuration must contain the following:

• baseUrl: An optional base url to the Payhere API. By default the staging base url will be used
• environment: Optional enviroment, either "sandbox" or "production". Default is 'sandbox'
• version: The API version being accessed. This is mandatory.

As an example, you might configure the library like this:

const payhere = require("payhere-sdk");

const defaultGlobalConfig: payhere.GlobalConfig = {
  baseUrl: "http://sandbox.payhere.africa",
  environment: payhere.Environment.SANDBOX,
  version: "v1"
};

const userConfig: payhere.UserConfig = {
  appId: "11011",
  username: "sdk",
  password: "sdk@2020"
};

const { Inpayments, Outpayments } = payhere.create(defaultGlobalConfig, userConfig);

Inpayments

Used for receiving money

You can create a inpayments client with the following:

const inpayments = Inpayments();

Methods

1. requestToPay(request: PaymentRequest): Promise<string>: This operation is used to request a payment from a consumer (Payer). The payer will be asked to authorize the payment. The transaction is executed once the payer has authorized the payment. The transaction will be in status PENDING until it is authorized or declined by the payer or it is timed out by the system. Status of the transaction can be validated by using getTransaction

2. getTransaction(transactionId: string): Promise<Payment>: Retrieve transaction information using the transactionId returned by requestToPay. You can invoke it at intervals until the transaction fails or succeeds. If the transaction has failed, it will throw an appropriate error. The error will be a subclass of PayhereError. Check src/error.ts for the various errors that can be thrown

Sample Code

const payhere = require("payhere-sdk");

const defaultGlobalConfig: payhere.GlobalConfig = {
  baseUrl: "http://sandbox.payhere.africa",
  environment: payhere.Environment.SANDBOX,
  version: "v1"
};

const userConfig: payhere.UserConfig = {
  appId: "11011",
  username: "sdk",
  password: "sdk@2020"
};

const { Inpayments } = payhere.create(defaultGlobalConfig, userConfig);

const inpayments = Inpayments();

// Request to pay
inpayments
  .requestToPay({
    amount: "50",
    processingNumber: "123456",
    msisdn: "256774290781",
    narration: "testing"
  })
  .then(transactionId => {
    console.log({ transactionId });

    // Get transaction status
    return inpayments.getTransaction(transactionId);
  })
  .then(transaction => {
    console.log({ transaction });
  })
  .catch(error => {
    console.log(error);
  });

Outpayments

Used for sending money to users

You can create a outpayments client with the following

const outpayments = Outpayments();

Methods

1. transfer(request: TransferRequest): Promise<string>

Used to transfer an amount from the owner’s account to a payee account. It returns a transaction id which can use to check the transaction status with the getTransaction function

2. getTransaction(transactionId: string): Promise<Transfer>: Retrieve transaction information using the transactionId returned by transfer. You can invoke it at intervals until the transaction fails or succeeds. If the transaction has failed, it will throw an appropriate error. The error will be a subclass of PayhereError. Check src/error.ts for the various errors that can be thrown

Sample Code

const payhere = require("payhere-sdk");

const defaultGlobalConfig: payhere.GlobalConfig = {
  baseUrl: "http://sandbox.payhere.africa",
  environment: payhere.Environment.SANDBOX,
  version: "v1"
};

const userConfig: payhere.UserConfig = {
  appId: "11011",
  username: "sdk",
  password: "sdk@2020"
};
// initialise payhere library
const { Outpayments } = payhere.create(defaultGlobalConfig, userConfig);

// initialise outpayments
const outpayments = Outpayments();

// Transfer
outpayments
  .transfer({
    amount: "50",
    processingNumber: "123456",
    msisdn: "256774290781",
    narration: "testing"
  })
  .then(transactionId => {
    console.log({ transactionId });

    // Get transaction status
    return outpayments.getTransaction(transactionId);
  })
  .then(transaction => {
    console.log({ transaction });
  })
  .catch(error => {
    console.log(error);
  });