Skip to content

Latest commit

 

History

History
723 lines (486 loc) · 21.5 KB

README.md

File metadata and controls

723 lines (486 loc) · 21.5 KB

NODEJS AZAMPAY SDK

AzamPay NodeJs SDK to help you easily and seamlessly integrate with Azampay APIs.

Table of Contents

  1. Installations
  2. Use
    2.1 Get Token
    2.2 Bank Checkout
    2.3 Mno Checkout
    2.4 Disbursement
    2.5 Name Lookup
    2.6 Transaction Status
    2.7 Post Checkout
    2.7 Payment Partners

Installation and Use

From terminal in the root directory of your project, run

npm i azampay

Use

ES6 Import
import azampay from 'azampay'
Module Require
const azampay = require('azampay').default
  • The import or require from azampay package exports two properties.

    1. getToken method that is used to retrieve access token from Azam Pay
    2. instance a class that can be used or extended to add functionalities to the azampay package

Get Token

Requirement Definition

Property Description Type Required
env Enum: SANDBOX | LIVE. Azampay environment. Default SANDBOX String [ ]
clientId It will be the client id generated during application registration. String [x]
appName It will be the name of application. String [x]
clientSecret It will be the secret key generated during application registration. String [x]
apiKey Azam Pay API key given as token in the settings page. String [x]

Request Payload

{
  "env": "string",
  "clientId": "string",
  "appName": "string",
  "clientSecret": "string",
  "apiKey": "string",
}

Request Method

const token = await azampay.getToken(payload);

Response

If successful, the response will be of type TokenResponse or ErrorResponse

{
  data: { accessToken: string; expire: string };
  success: boolean;
  message: string;
  code: string | number;
  statusCode: number;
  bankCheckout: (
    payload: BankCheckout,
    options: RequestOptions
  ) => Promise<CheckoutResponse>;

  mnoCheckout: (
    payload: MnoCheckout,
    options: RequestOptions
  ) => Promise<CheckoutResponse>;

  postCheckout: (
    payload: PostCheckOut,
    options: RequestOptions
  ) => Promise<PostCheckOutInterface>;

  disburse: (
    payload: Disburse,
    options: RequestOptions
  ) => Promise<DisburseResponse>;

  transactionStatus: (
    payload: TransactionStatus,
    options: RequestOptions
  ) => Promise<TransactionStatusResponse>;

  nameLookup: (
    payload: NameLookup,
    options: RequestOptions
  ) => Promise<NameLookupResponse>;
}

Response Definition

Property Description Type
data Azam Pay respnse with access token and expire time Object
success A true boolean value indicating that the request was successfull Boolean
message Response message String
code Response code. Number | String
statusCode Response Http Status code. Possibly 200 or 201 Number
bankCheckout A method to initiate a Bank checkout with Azam Pay. Method
mnoCheckout A method to initiate MNO checkout with Azam Pay. Method
disburse A method used to lookup the name associated with a bank account or Mobile Money account Method
transactionStatus A method used to retrieve the status of a disbursement transaction made through AzamPay. Method
nameLookup A method used to lookup the name associated with a bank account or Mobile Money account. Method

Bank Checkout

Initiating a bank checkout, we can use two methods, one from the token results method and the other from the Azam Pay instance exported from the azampay package.

Bank checkout method takes two arguments, the first with the request payload for Azam Pay bank checkout and second is optional with additional options.

Request Payload

{

  amount: string;
  currencyCode: string;
  merchantAccountNumber: string;
  merchantMobileNumber: string;
  merchantName?: string | null;
  otp: string;
  provider: 'CRDB' | 'NMB' |
  referenceId: string;
  additionalProperties?: Record<string, unknown> | null;
}
  1. Request Payload Definition
Property Definition Type
amount This is amount that will be charged from the given account. String
currencyCode Code of currency String
merchantAccountNumber This is the account number/MSISDN that consumer will provide. The amount will be deducted from this. String
merchantMobileNumber Mobile number String
merchantName Nullable consumer name. String
otp One time password String
provider Enum: CRDB | NMB BankProvider. String
referenceId This id belongs to the calling application. Maximum Allowed length for this field is 128 ascii characters. String
additionaProperties This is additional JSON data that calling application can provide. This is optional. Object
  1. Request Options Definition
  • These are optional if you use the method from the response in getToken otherwise mandatory if using the instance and the options were not passed during instantiation.

Method

Request from Token Response
await token.bankCheckout(payload, options)
Request from Instance
const instance = new azampay.instance({accessToken: token.data.accessToken,apiKey: 'YOUR API KEY'})
await instance.bankCheckout(payload, options)

Response

{
  transactionId: string,
  message: string,
  succcess: true
}

NB: Every response has a success property denoting whether the request was successful or not and if it wasn't, the response will be of type Error Response


MNO Checkout

For request method explanation, refer to Bank Checkout's explanation.

  1. Request Payload Definition
Property Definition Type
amount This is amount that will be charged from the given account. String
currencyCode Code of currency String
accountNumber This is the account number/MSISDN that consumer will provide. The amount will be deducted from this account. String
provider Enum: Airtel | Tigo | Halopesa | Azampesa | Mpesa. String
externalId This id belongs to the calling application. Maximum Allowed length for this field is 128 ascii characters. String
additionaProperties This is additional JSON data that calling application can provide. This is optional. Object
{
  accountNumber: string;
  amount: string;
  currency: string;
  externalId: string;
  provider: 'Airtel' | 'Tigo' | 'Halopesa' | 'Azampesa' | 'Mpesa' | string;
  additionalProperties?: Record<string, unknown> | null;
}

Method

Request from Token Response
await token.mnoCheckout(payload, options)
Request from Instance
const instance = new azampay.instance({accessToken: token.data.accessToken,apiKey: 'YOUR API KEY'})
await instance.mnoCheckout(payload, options)

Response The response is the same as the Bank Checkout's


Disbursement

This method allows for the transfer of money from other countries to Tanzania. It requires the authorization token generated above, passed as a header in the request. The request should also contain details of the source, destination, and transfer details. Additionally, the request can include an external reference ID and remarks.

This method takes two arguments, mandatory payload and the other optional options as explained in Bank Checkout

Payload

{
  source: Source;
  destination: Destination;
  transferDetails: TransferDetails;
  externalReferenceId: string;
  remarks: string;
}
Property Description Type
source Contains information about the source account. Object
destination Contains information about the destination account. Object
transferDetails Contains information about the transfer. Object
externalReferenceId An external reference ID to track the transaction. String
remarks Any remarks to be included with the transaction. String

Method

Request from Token Response
await token.disburse(payload, options)
Request from Instance
const instance = new azampay.instance({accessToken: token.data.accessToken,apiKey: 'YOUR API KEY'})
await instance.disburse(payload, options)

Response

{
  data: string;
  message: string;
  success: boolean;
  statusCode: number;
}

Description

Property Description Type
data A string containing the status of the transaction. String
message A string containing a human-readable message describing the response. String
success A boolean indicating whether the request was successful or not. Boolean
statusCode An integer indicating the status code of the response. Number

Name Lookup

This method is used to lookup the name associated with a bank account or Mobile Money account.

This method takes two arguments, mandatory payload and the other optional options as explained in Bank Checkout

Payload

{
  bankName: string;
  accountNumber: string;
}

Description

Property Description Type
bankName Bank name or Mobile Money name associated with the account. String
accountNumber Bank account number or Mobile Money number. String

Method

Request from Token Response
await token.nameLookup(payload, options)
Request from Instance
const instance = new azampay.instance({accessToken: token.data.accessToken,apiKey: 'YOUR API KEY'})
await instance.nameLookup(payload, options)

Response

{
  name: string;
  message: string;
  success: boolean;
  accountNumber: string;
  bankName: string;
}

Description

Property Description Type
bankName Bank name or Mobile Money name associated with the account. String
accountNumber Bank account number or Mobile Money number. String
name Name associated with the account. String
message A brief description of the response status. String
success A boolean value indicating if the request was successful or not. Boolean

Transaction Status

This method allows you to retrieve the status of a disbursement transaction made through AzamPay. This method takes two arguments, mandatory payload and the other optional options as explained in Bank Checkout

Payload

{
  reference: string;
  bankName: string;
}

Description

Property Description Type
reference The transaction ID you received when making the disbursement request. String
bankName The name of the mobile network operator (MNO) you used to make the disbursement request. String

Method

Request from Token Response
await token.transactionStatus(payload, options)
Request from Instance
const instance = new azampay.instance({accessToken: token.data.accessToken,apiKey: 'YOUR API KEY'})
await instance.transactionStatus(payload, options)

Response

Property Description Type
data A string containing the status of the transaction. String
message A string containing a human-readable message describing the response. String
success A boolean indicating whether the request was successful or not. Boolean
statusCode An integer indicating the status code of the response. Number

Post Checkout

For this post request, send all params that are mentioned below to this end point.

This end point will respond back with the URL of your payments. Merchant Application can open this url in a new window to continue with the checkout process of the transaction


Payload

{
  appName: string;
  clientId: string;
  vendorId: string;
  language: string;
  currency: string;
  externalId: string;
  requestOrigin: string;
  redirectFailURL: string;
  redirectSuccessURL: string;
  vendorName: string;
  amount: string;
  cart: Cart;
}

Description

Property Description Type
amount This is amount that will be charged from the given account. String
appName This is the application name. String
cart Shoping cart with multiple item. Object
clientId Client id is unique id for identify client. String
externalId 30 charecters long unique string. String
language Language code for transalate the application. String
redirectFailURL URL that you want to redirected to at transaction failure. String
redirectSuccessURL URL that you want to redirected to at transaction success. String
requestOrigin URL which the request is being originated. String
vendorId Unique id for validate vendor. String
vendorName Name of vendor. String

Response

This returns a success boolean property indicating whether the operation was successful or not and a data string

{
  data: string
  success: boolean;
  [key: string]: unknown;
}

Payment Partners

This method will return the registered partners of the provided merchant

This method takes optional options argument as explained in Bank Checkout

Method

Request from Token Response
await token.partners(options)
Request from Instance
const instance = new azampay.instance({accessToken: token.data.accessToken,apiKey: 'YOUR API KEY'})
await instance.partners(options)

Response

{
  success: boolean;
  partners: Partners[];
}

Description

Property Description Type
success A boolean value indicating if the request was successful or not. Boolean
partners An array of payment partners. Array

Partners

Property Description Type
currency Currency code that will convert amount into specific currency format String
logoUrl Payment Partner logo URL String
partnerName Name of the payment partner e.g (Azampesa, Airtel, Halopesa, Tigopesa, vodacom) String
paymentPartnerId Unique id for payment partner String
paymentVendorId Unique id for payment vendor String
provider Provider enum value e.g (airtel=2, tigo=3, halopesa=4, azampesa=5, Mpesa=10) String
vendorName Name of vendor String

Request Options

{
  apiKey: string;
  accessToken: string;
  env: 'LIVE' | 'SANDBOX';
}

Source or Destination

Payload

 {
  countryCode: string;
  fullName: string;
  bankName: string;
  accountNumber: string;
  currency: string;
}

Description

Property Description Type
countryCode Country / Destination code String
fullName Source / Destination account full name String
bankName Source / Destination account bank name String
accountNumber Source / Destination account account number String
currency Source / Destination account currency String

Transfer Details

Payload

 {
  type: string;
  amount: number;
  date: string;
}

Description

Property Description Type
type Transfer type String
amount Transfer amount String
date Transfer date String

Error Response

{

  success: boolean;
  message: string;
  code: string  | number;
  statusCode: number;
}

Property Definition

Property Description Type
success A false boolean value indicating that the request was not successfull. Boolean
message Error message String
code Error code Number | String
statusCode Error Http Status code Number

Developed and Maintained with ❤️ at Flexcode Labs