Skip to content

Commit db70124

Browse files
elias-haileselassieelias-haileselassie
committed
initial Lib source created
1 parent de687df commit db70124

File tree

6 files changed

+327
-3
lines changed

6 files changed

+327
-3
lines changed

‎CHANGELOG.md‎

Lines changed: 7 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,7 @@
1+
## 0.1.0
2+
3+
- test publication
4+
5+
## 1.0.0
6+
7+
- Initial version

‎LICENSE‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,6 @@
11
MIT License
22

3-
Copyright (c) 2021 webirr
3+
Copyright (c) 2021 WeBirr Technologies PLC
44

55
Permission is hereby granted, free of charge, to any person obtaining a copy
66
of this software and associated documentation files (the "Software"), to deal

‎README.md‎

Lines changed: 168 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -1,2 +1,168 @@
1-
# webirr-api-javascript-client
2-
Official JavaScript Client Library for WeBirr APIs
1+
Official JavaScript Client Library for WeBirr Payment Gateway APIs
2+
3+
This Client Library provides convenient access to WeBirr Payment Gateway APIs from JavaScript/Node/ReactNative Apps.
4+
5+
*Requires Javascript engine in browser or Node*
6+
7+
## Install
8+
9+
run the following command to install webirr client library
10+
11+
With npm
12+
13+
```bash
14+
$ npm install webirr
15+
```
16+
With yarn
17+
18+
```bash
19+
$ yarn add webirr
20+
```
21+
22+
With bower
23+
24+
```bash
25+
$ bower install webirr
26+
```
27+
28+
## Usage
29+
30+
The library needs to be configured with a *merchant Id* & *API key*. You can get it by contacting [webirr.com](https://webirr.com)
31+
32+
> You can use this library for production or test environments. you will need to set isTestEnv=true for test, and false for production apps when creating objects of class WeBirrClient
33+
34+
## Example
35+
36+
### Creating a new Bill / Updating an existing Bill on WeBirr Servers
37+
38+
```javascript
39+
40+
const WeBirrClient = require('webirr');
41+
42+
async function main()
43+
{
44+
const apikey = 'YOUR_API_KEY';
45+
const merchantId = 'YOUR_MERCHANT_ID';
46+
47+
var api = new WeBirrClient(apiKey, true);
48+
49+
let bill = {
50+
amount: '270.90',
51+
customerCode: 'cc01', // it can be email address or phone number if you dont have customer code
52+
customerName: 'Elias Haileselassie',
53+
time: '2021-07-22 22:14', // your bill time, always in this format
54+
description: 'hotel booking',
55+
billReference: 'drt/2021/131', // your unique reference number
56+
merchantID: merchantId,
57+
};
58+
59+
console.log('Creating Bill...');
60+
var res = await api.createBill(bill);
61+
62+
if (!res.error) {
63+
// success
64+
let paymentCode = res.res; // returns paymentcode such as 429 723 975
65+
console.log( `Payment Code = ${paymentCode}`); // we may want to save payment code in local db.
66+
67+
} else {
68+
// fail
69+
console.log(`error: ${res.error}`);
70+
console.log(
71+
`errorCode: ${res.errorCode}`); // can be used to handle specific busines error such as ERROR_INVLAID_INPUT_DUP_REF
72+
}
73+
74+
// update existing bill if it is not paid
75+
bill.amount = "278.00";
76+
bill.customerName = 'Elias javascript';
77+
//bill.billReference = "WE CAN NOT CHANGE THIS";
78+
79+
console.log('Updating Bill...');
80+
res = await api.updateBill(bill);
81+
82+
if (!res.error) {
83+
// success
84+
console.log('bill is updated succesfully'); //res.res will be 'OK' no need to check here!
85+
} else {
86+
// fail
87+
console.log(`error: ${res.error}`);
88+
console.log(`errorCode: ${res.errorCode}`); // can be used to handle specific busines error such as ERROR_INVLAID_INPUT
89+
}
90+
91+
}
92+
93+
main();
94+
95+
```
96+
97+
### Getting Payment status of an existing Bill from WeBirr Servers
98+
99+
```javascript
100+
101+
const WeBirrClient = require('webirr');
102+
103+
async function main()
104+
{
105+
const apikey = 'YOUR_API_KEY';
106+
const merchantId = 'YOUR_MERCHANT_ID';
107+
108+
var api = new WeBirrClient(apiKey, true);
109+
110+
var paymentCode = 'PAYMENT_CODE_YOU_SAVED_AFTER_CREATING_A_NEW_BILL' // suchas as '141 263 782';
111+
112+
console.log('Getting Payment Status...');
113+
var r = await api.getPaymentStatus('624549955')
114+
115+
if (!r.error) {
116+
// success
117+
if (r.res.isPaid) {
118+
console.log('bill is paid');
119+
console.log('bill payment detail');
120+
console.log(`Bank: ${r.res.data.bankID}`);
121+
console.log(`Bank Reference Number: ${r.res.data.paymentReference}`);
122+
console.log('Amount Paid: ${r.res?.data?.amount}');
123+
} else
124+
console.log('bill is pending payment');
125+
} else {
126+
// fail
127+
console.log(`error: ${r.error}`);
128+
console.log( `errorCode: ${r.errorCode}`); // can be used to handle specific busines error such as ERROR_INVLAID_INPUT
129+
}
130+
131+
}
132+
133+
main();
134+
135+
```
136+
137+
### Deleting an existing Bill from WeBirr Servers (if it is not paid)
138+
139+
```javascript
140+
141+
const WeBirrClient = require('webirr');
142+
143+
async function main()
144+
{
145+
const apikey = 'YOUR_API_KEY';
146+
const merchantId = 'YOUR_MERCHANT_ID';
147+
148+
var api = new WeBirrClient(apiKey, true);
149+
150+
var paymentCode = 'PAYMENT_CODE_YOU_SAVED_AFTER_CREATING_A_NEW_BILL' // suchas as '141 263 782';
151+
152+
console.log('Deleting Bill...');
153+
res = await api.deleteBill(paymentCode);
154+
155+
if (!res.error) {
156+
// success
157+
console.log('bill is deleted succesfully'); //res.res will be 'OK' no need to check here!
158+
} else {
159+
// fail
160+
console.log(`error: ${res.error}`);
161+
console.log(`errorCode: ${res.errorCode}`); // can be used to handle specific bussines error such as ERROR_INVLAID_INPUT
162+
}
163+
164+
}
165+
166+
main();
167+
168+
```

‎index.js‎

Lines changed: 103 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,103 @@
1+
const axios = require('axios').default;
2+
3+
/**
4+
* A WeBirrClient instance object can be used to
5+
* Create, Update or Delete a Bill at WeBirr Servers and also to
6+
* Get the Payment Status of a bill.
7+
* It is a wrapper for the REST Web Service API.
8+
*/
9+
class WeBirrClient {
10+
/**
11+
* Creates an instance of WeBirrClient object to interact with remote WebService API.
12+
* @param {string} apiKey
13+
* @param {boolean} isTestEnv
14+
*/
15+
constructor(apiKey, isTestEnv = true)
16+
{
17+
this._apiKey = apiKey;
18+
this._baseAddress = isTestEnv? 'https://api.webirr.com' : 'https://api.webirr.com:8080';
19+
}
20+
21+
/**
22+
* Create a new bill at WeBirr Servers.
23+
* @param {object} bill represents an invoice or bill for a customer. see sample for structure of the Bill
24+
* @returns {object} see sample for structure of the returned ApiResponse Object
25+
* Check if(ApiResponse.error == null) to see if there are errors.
26+
* ApiResponse.res will have the value of the returned PaymentCode on success.
27+
*/
28+
async createBill(bill) {
29+
var resp = await axios({
30+
method: 'post',
31+
url: `${this._baseAddress}/einvoice/api/postbill?api_key=${this._apiKey}`,
32+
headers: {"Content-Type": "application/json"},
33+
data: JSON.stringify(bill) } );
34+
35+
if (resp.status == 200)
36+
return resp.data;
37+
else
38+
return { error: `http error ${resp.status} ${resp.statusText}` };
39+
}
40+
41+
/**
42+
* Update an existing bill at WeBirr Servers, if the bill is not paid yet.
43+
* The billReference has to be the same as the original bill created.
44+
* @param {object} bill represents an invoice or bill for a customer. see sample for structure of the Bill
45+
* @returns {object} see sample for structure of the returned ApiResponse Object
46+
* Check if(ApiResponse.error == null) to see if there are errors.
47+
* ApiResponse.res will have the value of "OK" on success.
48+
*/
49+
async updateBill(bill) {
50+
51+
var resp = await axios({
52+
method: 'put',
53+
url: `${this._baseAddress}/einvoice/api/postbill?api_key=${this._apiKey}`,
54+
headers: {"Content-Type": "application/json"},
55+
data: JSON.stringify(bill) } );
56+
57+
if (resp.status == 200)
58+
return resp.data;
59+
else
60+
return { error: `http error ${resp.status} ${resp.statusText}` };
61+
62+
}
63+
64+
/**
65+
* Delete an existing bill at WeBirr Servers, if the bill is not paid yet.
66+
* @param {string} paymentCode is the number that WeBirr Payment Gateway returns on createBill.
67+
* @returns {object} see sample for structure of the returned ApiResponse Object
68+
* Check if(ApiResponse.error == null) to see if there are errors.
69+
* ApiResponse.res will have the value of "OK" on success.
70+
*/
71+
async deleteBill(paymentCode) {
72+
var resp = await axios({
73+
method: 'put',
74+
url: `${this._baseAddress}/einvoice/api/deletebill?api_key=${this._apiKey}&wbc_code=${paymentCode}`} );
75+
76+
if (resp.status == 200)
77+
return resp.data;
78+
else
79+
return { error: `http error ${resp.status} ${resp.statusText}` };
80+
81+
}
82+
83+
/**
84+
* Get Payment Status of a bill from WeBirr Servers
85+
* @param {string} paymentCode is the number that WeBirr Payment Gateway returns on createBill.
86+
* @returns {object} see sample for structure of the returned ApiResponse Object
87+
* Check if(returnedResult.error == null) to see if there are errors.
88+
* returnedResult.res will have `Payment` object on success (will be null otherwise!)
89+
* returnedResult.res?.isPaid ?? false -> will return true if the bill is paid (payment completed)
90+
* returnedResult.res?.data ?? null -> will have `PaymentDetail` object
91+
*/
92+
async getPaymentStatus(paymentCode) {
93+
var resp = await axios(
94+
`${this._baseAddress}/einvoice/api/getPaymentStatus?api_key=${this._apiKey}&wbc_code=${paymentCode}`);
95+
if (resp.status == 200)
96+
return resp.data;
97+
else
98+
return { error: `http error ${resp.status} ${resp.statusText}` };
99+
}
100+
101+
}
102+
103+
module.exports.WeBirrClient = WeBirrClient;

‎package-lock.json‎

Lines changed: 21 additions & 0 deletions
Some generated files are not rendered by default. Learn more about customizing how changed files appear on GitHub.

‎package.json‎

Lines changed: 27 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,27 @@
1+
{
2+
"name": "webirr",
3+
"version": "0.1.0",
4+
"description": "Official JavaScript Client Library for WeBirr APIs",
5+
"main": "index.js",
6+
"scripts": {
7+
"test": "echo \"Error: no test specified\" && exit 1"
8+
},
9+
"repository": {
10+
"type": "git",
11+
"url": "git+https://github.com/webirr/webirr-api-javascript-client.git"
12+
},
13+
"keywords": [
14+
"webirr",
15+
"fintech",
16+
"ethiopia"
17+
],
18+
"author": "WeBirr Technologies <[email protected]> (https://webirr.com)",
19+
"license": "MIT",
20+
"bugs": {
21+
"url": "https://github.com/webirr/webirr-api-javascript-client/issues"
22+
},
23+
"homepage": "https://github.com/webirr/webirr-api-javascript-client#readme",
24+
"dependencies": {
25+
"axios": "^0.21.1"
26+
}
27+
}

0 commit comments

Comments
 (0)