Skip to content

Commit c192089

Browse files
elias-haileselassieelias-haileselassie
committed
api enhancements
1 parent e0d740d commit c192089

12 files changed

+1020
-986
lines changed

‎README.md

+183-38
Original file line numberDiff line numberDiff line change
@@ -10,7 +10,7 @@ $ composer require webirr/webirr
1010

1111
## Usage
1212

13-
The library needs to be configured with a *merchant Id* & *API key*. You can get it by contacting [webirr.com](https://webirr.com)
13+
The library needs to be configured with a *merchant Id* & *API key*. You can get it by contacting [webirr.com](https://webirr.net)
1414

1515
> 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
1616
@@ -29,13 +29,13 @@ use WeBirr\WeBirrClient;
2929
// Create & Update Bill
3030
function main()
3131
{
32-
$apiKey = 'YOUR_API_KEY';
33-
$merchantId = 'YOUR_MERCHANT_ID';
32+
$apiKey = getenv('wb_apikey_1') !== false ? getenv('wb_apikey_1') : "";
33+
$merchantId = getenv('wb_merchid_1') !== false ? getenv('wb_merchid_1') : "";
3434

35-
//$apiKey = getenv('wb_apikey_1');
36-
//$merchantId = getenv('wb_merchid_1');
35+
//$apiKey = 'YOUR_API_KEY';
36+
//$merchantId = 'YOUR_MERCHANT_ID';
3737

38-
$api = new WeBirrClient($apiKey, true);
38+
$api = new WeBirrClient($merchantId, $apiKey, true);
3939

4040
$bill = new Bill();
4141

@@ -44,7 +44,7 @@ function main()
4444
$bill->customerName = 'Elias Haileselassie';
4545
$bill->time = '2021-07-22 22:14'; // your bill time, always in this format
4646
$bill->description = 'hotel booking';
47-
$bill->billReference = 'php/2021/127'; // your unique reference number
47+
$bill->billReference = 'php/2021/128'; // your unique reference number
4848
$bill->merchantID = $merchantId;
4949

5050
echo "\nCreating Bill...";
@@ -94,35 +94,36 @@ main();
9494

9595
require 'vendor/autoload.php';
9696

97-
use WeBirr\Bill;
9897
use WeBirr\WeBirrClient;
98+
use WeBirr\PaymentDetail;
9999

100-
// Get Payment Status of Bill
100+
// Get Payment Status of a Bill
101101
function main()
102102
{
103-
$apiKey = 'YOUR_API_KEY';
104-
$merchantId = 'YOUR_MERCHANT_ID';
105103

106-
//$apiKey = getenv('wb_apikey_1');
107-
//$merchantId = getenv('wb_merchid_1');
104+
$apiKey = getenv('wb_apikey_1') !== false ? getenv('wb_apikey_1') : "";
105+
$merchantId = getenv('wb_merchid_1') !== false ? getenv('wb_merchid_1') : "";
106+
107+
//$apiKey = 'YOUR_API_KEY';
108+
//$merchantId = 'YOUR_MERCHANT_ID';
108109

109-
$api = new WeBirrClient($apiKey, true);
110+
$api = new WeBirrClient($merchantId, $apiKey, true);
110111

111-
$paymentCode = 'PAYMENT_CODE_YOU_SAVED_AFTER_CREATING_A_NEW_BILL'; // suchas as '141 263 782';
112+
$paymentCode = '149 233 514'; // PAYMENT_CODE_YOU_SAVED_AFTER_CREATING_A_NEW_BILL
112113

113114
echo "\nGetting Payment Status...";
114115

115116
$res = $api->getPaymentStatus($paymentCode);
116117

117118
if (!$res->error) {
118119
// success
119-
if ($res->res->status == 2) {
120-
$data = $res->res->data;
120+
if ($res->res->status == 2) { // 0. Pending ( $res->res->data will be null !), 1. Payment in Progress (unconfirmed payment) 2. Paid
121+
$payment = new PaymentDetail($res->res->data);
121122
echo "\nbill is paid";
122123
echo "\nbill payment detail";
123-
echo "\nBank: $data->bankID";
124-
echo "\nBank Reference Number: $data->paymentReference";
125-
echo "\nAmount Paid: $data->amount";
124+
echo "\nBank: $payment->bankID";
125+
echo "\nBank Reference Number: $payment->paymentReference";
126+
echo "\nAmount Paid: $payment->amount";
126127
} else
127128
echo "\nbill is pending payment";
128129
} else {
@@ -145,18 +146,20 @@ main();
145146
error: null,
146147
res: {
147148
status: 2,
148-
data: {
149-
id: 111112347,
150-
paymentReference: '8G3303GHJN',
151-
confirmed: true,
152-
confirmedTime: '2021-07-03 10:25:35',
153-
bankID: 'cbe_birr',
154-
time: '2021-07-03 10:25:33',
155-
amount: '4.60',
156-
wbcCode: '624 549 955'
157-
}
158-
},
159-
errorCode: null
149+
data: {
150+
status: 2,
151+
id: 111219507,
152+
bankID: "cbe_mobile",
153+
paymentReference: "TX70e78862148f4c249606",
154+
paymentDate: "2025-02-26 22:17:19",
155+
confirmed: true,
156+
confirmedTime: "2025-02-26 22:17:19",
157+
amount: "278",
158+
wbcCode: "149 233 514",
159+
updateTimeStamp: "2025022622171981338"
160+
}
161+
},
162+
errorCode: null
160163
}
161164

162165
```
@@ -173,15 +176,16 @@ use WeBirr\WeBirrClient;
173176
// Delete an existing Bill
174177
function main()
175178
{
176-
$apiKey = 'YOUR_API_KEY';
177-
$merchantId = 'YOUR_MERCHANT_ID';
178179

179-
//$apiKey = getenv('wb_apikey_1');
180-
//$merchantId = getenv('wb_merchid_1');
180+
$apiKey = getenv('wb_apikey_1') !== false ? getenv('wb_apikey_1') : "";
181+
$merchantId = getenv('wb_merchid_1') !== false ? getenv('wb_merchid_1') : "";
182+
183+
//$apiKey = 'YOUR_API_KEY';
184+
//$merchantId = 'YOUR_MERCHANT_ID';
181185

182-
$api = new WeBirrClient($apiKey, true);
186+
$api = new WeBirrClient($merchantId, $apiKey, true);
183187

184-
$paymentCode = 'PAYMENT_CODE_YOU_SAVED_AFTER_CREATING_A_NEW_BILL'; // suchas as '141 263 782';
188+
$paymentCode = '460 609 416'; // PAYMENT_CODE_YOU_SAVED_AFTER_CREATING_A_NEW_BILL
185189

186190
echo "\nDeleting Bill...";
187191

@@ -200,4 +204,145 @@ function main()
200204

201205
main();
202206

207+
```
208+
209+
### Getting list of Payments and process them with Bulk Polling Consumer
210+
211+
```php
212+
213+
<?php
214+
215+
require 'vendor/autoload.php';
216+
217+
use WeBirr\WeBirrClient;
218+
use WeBirr\Payment;
219+
220+
// Get list of Payments and process them with bulk polling consumer
221+
class PaymentProcessor
222+
{
223+
private $apiKey;
224+
private $merchantId;
225+
private $api;
226+
private $lastTimeStamp;
227+
228+
public function __construct()
229+
{
230+
$this->apiKey = getenv('wb_apikey_1') !== false ? getenv('wb_apikey_1') : "";
231+
$this->merchantId = getenv('wb_merchid_1') !== false ? getenv('wb_merchid_1') : "";
232+
$this->api = new WeBirrClient($this->merchantId, $this->apiKey, true);
233+
$this->lastTimeStamp = '20250224120000'; // Example timestamp, replace with your actual last timestamp retrieved from your database to current date stamp for first time call
234+
}
235+
236+
public function Run()
237+
{
238+
while (true) {
239+
echo "\nRetrieving Payments...";
240+
$this->FetchPayments();
241+
echo "\nSleeping for 5 seconds...";
242+
sleep(5); // Sleep for 5 seconds before the next polling
243+
}
244+
}
245+
246+
private function FetchPayments()
247+
{
248+
$limit = 100; // Number of records to retrieve depending on your processing requirement & capacity
249+
$response = $this->api->getPayments($this->lastTimeStamp, $limit);
250+
251+
if (!$response->error) {
252+
// success
253+
if (count($response->res) == 0) {
254+
echo "\nNo new payments found.";
255+
}
256+
foreach ($response->res as $obj) {
257+
$payment = new Payment($obj);
258+
$this->ProcessPayment($payment);
259+
echo "\n-----------------------------";
260+
}
261+
262+
if (count($response->res) > 0) {
263+
$this->lastTimeStamp = $response->res[count($response->res) - 1]->updateTimeStamp;
264+
echo "\nLast Timestamp: " . $this->lastTimeStamp; // save this to your database for next polling/call to getPayments()
265+
}
266+
267+
} else {
268+
// fail
269+
echo "\nerror: " . $response->error;
270+
echo "\nerrorCode: " . $response->errorCode; // can be used to handle specific business error such as ERROR_INVALID_INPUT
271+
}
272+
}
273+
274+
// Process Payment should be impleneted as idempotent operation for production use cases
275+
private function ProcessPayment(Payment $payment)
276+
{
277+
echo "\nPayment Status: " . $payment->status;
278+
if ($payment->IsPaid()) {
279+
echo "\nPayment Status Text: Paid.";
280+
}
281+
if ($payment->IsReversed()) {
282+
echo "\nPayment Status Text: Reversed.";
283+
}
284+
echo "\nBank: " . $payment->bankID;
285+
echo "\nBank Reference Number: " . $payment->paymentReference;
286+
echo "\nAmount Paid: " . $payment->amount;
287+
echo "\nPayment Date: " . $payment->paymentDate;
288+
echo "\nReversal/Cancel Date: " . $payment->canceledTime;
289+
echo "\nUpdate Timestamp: " . $payment->updateTimeStamp;
290+
}
291+
}
292+
293+
// Run the payment processor
294+
$processor = new PaymentProcessor();
295+
$processor->Run();
296+
297+
```
298+
299+
### Gettting basic Statistics about bills created and payments received for a date range
300+
301+
```php
302+
303+
<?php
304+
305+
require 'vendor/autoload.php';
306+
307+
use WeBirr\WeBirrClient;
308+
use WeBirr\Stat;
309+
310+
// Get basic statistics about bills created and payments received for a date range
311+
function main()
312+
{
313+
$apiKey = getenv('wb_apikey_1') !== false ? getenv('wb_apikey_1') : "";
314+
$merchantId = getenv('wb_merchid_1') !== false ? getenv('wb_merchid_1') : "";
315+
316+
//$apiKey = 'YOUR_API_KEY';
317+
//$merchantId = 'YOUR_MERCHANT_ID';
318+
319+
$api = new WeBirrClient($merchantId, $apiKey, true);
320+
321+
$dateFrom = '2025-01-01'; // YYYY-MM-DD
322+
$dateTo = '2030-01-31'; // YYYY-MM-DD
323+
324+
echo "\nRetrieving Statistics...";
325+
echo "\nDate From: $dateFrom";
326+
echo "\nDate To: $dateTo";
327+
328+
$response = $api->getStat($dateFrom, $dateTo);
329+
330+
if (!$response->error){
331+
//success
332+
$stat = new Stat($response->res);
333+
334+
echo "\nNumber of Bills Created: " . $stat->nBills;
335+
echo "\nNumber of Paid Bills: " . $stat->nBillsPaid;
336+
echo "\nNumber of Unpaid Bills: " . $stat->nBillsUnpaid;
337+
echo "\nAmount of Bills: " . $stat->amountBills;
338+
echo "\nAmount Paid: " . $stat->amountPaid;
339+
echo "\nAmount Unpaid: " . $stat->amountUnpaid;
340+
} else {
341+
// error
342+
echo "\nError: " . $response->error;
343+
}
344+
}
345+
346+
main();
347+
203348
```

‎composer.json

+7-7
Original file line numberDiff line numberDiff line change
@@ -1,25 +1,25 @@
11
{
22
"name": "webirr/webirr",
33
"type": "library",
4-
"version": "1.0.0",
4+
"version": "2.0.0",
55
"description": "Official PHP Client Library for WeBirr Payment Gateway APIs",
66
"keywords": ["ethiopia", "fintech"],
77
"homepage": "https://github.com/webirr/webirr-api-php-client",
88
"license": "MIT",
99
"authors": [
1010
{
1111
"name": "WeBirr",
12-
"email": "tech@webirr.com",
13-
"homepage": "https://webirr.com"
12+
"email": "tech@webirr.net",
13+
"homepage": "https://webirr.net"
1414
}
1515
],
1616
"require": {
17-
"php": "^5.6||^7.0||^8.0",
18-
"guzzlehttp/guzzle": "~5.3.3||~6.0||~7.3",
19-
"guzzlehttp/psr7": "^1.8"
17+
"php": ">=7.2.5",
18+
"guzzlehttp/guzzle": ">=7.9.0",
19+
"guzzlehttp/psr7": ">=2.7.0"
2020
},
2121
"require-dev": {
22-
"phpunit/phpunit": "^9.5"
22+
"phpunit/phpunit": ">=9.5"
2323
},
2424
"autoload": {
2525
"psr-4": {

0 commit comments

Comments
 (0)