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

import azampay from 'azampay'

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 |

2. 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

await token.bankCheckout(payload, options)

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

await token.mnoCheckout(payload, options)

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

await token.disburse(payload, options)

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

await token.nameLookup(payload, options)

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

await token.transactionStatus(payload, options)

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

await token.partners(options)

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