Skip to content

Commit cf8cb62

Browse files
GhostscypherGhostscypher
authored
Merge pull request #4 from Ghostscypher/dev
Dev
2 parents d8115d7 + 8fdf9b3 commit cf8cb62

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

44 files changed

+3780
-1669
lines changed

‎CHANGELOG.md‎

Lines changed: 8 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -2,10 +2,15 @@
22

33
All notable changes to `laravel-mpesa` will be documented in this file.
44

5+
56
## Release cadidate 1 - 2024-08-30
67

7-
Initial release without the documentation (WIP)
8+
- Initial release of the package 🎉, documentation included
9+
- Added support for Laravel 6, 7, 8, 9, 10, 11
10+
- Added support for PHP 7.4, 8.0, 8.1, 8.2, 8.3, 8.4
11+
- Added support for Mpesa API v1, v2
12+
- Added support for Mpesa B2C, B2B, C2B, STK Push, Reversal, Account Balance, Transaction Status, Lipa Na Mpesa Online Payment
813

9-
## 1.0.0 - 2020-07-01
14+
Initial release without the documentation (WIP)
1015

11-
- Initial release
16+
## 1.0.0 - 2020-07-01

‎composer.json‎

Lines changed: 0 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -38,7 +38,6 @@
3838
"spatie/laravel-package-tools": "^1.0"
3939
},
4040
"require-dev": {
41-
"irazasyed/docgen": "^0.2.0",
4241
"orchestra/testbench": "^5.0|^6.0|^7.0|^8.0|^9.0",
4342
"pestphp/pest": "^1.0 |^2.0",
4443
"pestphp/pest-plugin-laravel": "^1.0|^2.0"

‎composer.lock‎

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

‎config/mpesa.php‎

Lines changed: 11 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -271,6 +271,17 @@
271271
*/
272272
'bill_manager_callback_url' => env('MPESA_BILL_MANAGER_CALLBACK_URL', ''),
273273

274+
/*
275+
|--------------------------------------------------------------------------
276+
| M-Ratiba Callback URL
277+
|--------------------------------------------------------------------------
278+
|
279+
| This is the URL that safaricom will call when the transaction is complete
280+
| for a M-Ratiba transaction
281+
|
282+
*/
283+
'ratiba_callback_url' => env('MPESA_RATIBA_CALLBACK_URL', ''),
284+
274285
/*******************End of Mpesa options************************************/
275286

276287
/*******************Start of customization options************************************/

‎docs/Auth/_index.md‎

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,4 @@
1+
---
2+
title: Auth
3+
weight: 1
4+
---

‎docs/Auth/introduction.md‎

Lines changed: 84 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,84 @@
1+
---
2+
title: Initiating Mpesa API
3+
weight: 1
4+
---
5+
6+
## MpesaAuth Trait
7+
8+
We assume that you have already installed the package and have the necessary credentials from Safaricom. If you don't have the credentials, you can get them by registering on the [Safaricom Developer Portal](https://developer.safaricom.co.ke/).
9+
10+
The MpesaAuth trait contains several methods that will help you get started with the Mpesa APIs.
11+
12+
Ensure that you have the following environment variables set in your `.env` file in order to be able to authenticate with the Mpesa API.
13+
14+
```dotenv
15+
MPESA_CONSUMER_KEY=
16+
MPESA_CONSUMER_SECRET=
17+
MPESA_ENVIRONMENT=
18+
MPESA_SHORTCODE=
19+
MPESA_PASSKEY=
20+
MPESA_INITIATOR_NAME=
21+
MPESA_INITIATOR_PASSWORD=
22+
```
23+
24+
## Generate Token
25+
26+
Do note that this is automatically called when you make a request to any of the Mpesa APIs. You can also manually generate the token by calling the `generateToken` method.
27+
28+
```php
29+
use \Ghostscypher\Mpesa\Facades\Mpesa;
30+
31+
/**
32+
* @throws \Ghostscypher\Mpesa\Exceptions\MpesaAuthException
33+
*/
34+
$token = Mpesa::generateToken();
35+
36+
// Or to force a new token to be generated
37+
/**
38+
* @throws \Ghostscypher\Mpesa\Exceptions\MpesaAuthException
39+
*/
40+
$token = Mpesa::generateToken(true);
41+
42+
// $token = 1234567890.....
43+
44+
// To use the token in your requests you will need to set it in the headers
45+
$headers = [
46+
'Authorization' => 'Bearer ' . $token,
47+
'Content-Type' => 'application/json',
48+
];
49+
```
50+
51+
The method will internally make an API request to the Safaricom API and return the token. The token is then stored in the database if we have set the `MPESA_FEATURE_STORE_TOKEN` environment variable to true. If not, the token is returned as a string.
52+
53+
## Check if Token has Expired
54+
55+
This method will check if the token has expired. If the token has expired, it will return `true`, otherwise `false`.
56+
57+
**Warning**: This method will only work if the `MPESA_FEATURE_STORE_TOKEN` environment variable is set to true. It checks the token expiry date in the database.
58+
59+
```php
60+
use \Ghostscypher\Mpesa\Facades\Mpesa;
61+
62+
if (Mpesa::isTokenExpired()) {
63+
// Token has expired
64+
}
65+
```
66+
67+
## Generate Security Credential
68+
69+
This method will generate the security credential, it is used in some of the Mpesa APIs.
70+
If the `$initiatorPassword` is not provided, it will use the `MPESA_INITIATOR_PASSWORD` environment variable.
71+
72+
**Note**: the credentials are generated based on the environment, if in production the credentials will be generated using the production credentials, and if in sandbox the credentials will be generated using the sandbox credentials.
73+
74+
```php
75+
use \Ghostscypher\Mpesa\Facades\Mpesa;
76+
77+
/**
78+
* @throws \Ghostscypher\Mpesa\Exceptions\MpesaAuthException
79+
*/
80+
$securityCredential = Mpesa::generateSecurityCredential("myInitiatorPassword");
81+
82+
// $securityCredential = ejfedsc...
83+
84+
```

‎docs/B2B/_index.md‎

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,4 @@
1+
---
2+
title: B2B APIs
3+
weight: 5
4+
---

‎docs/B2B/introduction.md‎

Lines changed: 141 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,141 @@
1+
---
2+
title: Mpesa Utility APIs
3+
weight: 1
4+
---
5+
6+
## B2B APIs
7+
8+
The B2B APIs enable Business to Business (B2B) transactions between a business and another business e.g. The transfer of funds between a corporate organization and a service provider etc.
9+
10+
The following .env variables are required in order to authenticate with the Mpesa API:
11+
12+
```dotenv
13+
MPESA_CONSUMER_KEY=
14+
MPESA_CONSUMER_SECRET=
15+
MPESA_ENVIRONMENT=
16+
MPESA_SHORTCODE=
17+
MPESA_INITIATOR_NAME=
18+
MPESA_INITIATOR_PASSWORD=
19+
MPESA_PARTNER_NAME=
20+
```
21+
22+
The following actions are available in the B2B trait:
23+
24+
- Initiating a B2B Transaction
25+
- Remit tax to KRA
26+
- Initiate a B2B STK Push
27+
28+
### Initiating a B2B Transaction
29+
30+
This allows you to initiate a B2B transaction between a business and another business.
31+
32+
The method takes the following parameters:
33+
34+
- `receiving_shortcode`: The shortcode of the business that will receive the funds.
35+
- `amount`: The amount to be transferred.
36+
- `account_reference`: The account reference. This is used to identify the transaction. It is usually a unique identifier for the transaction. i.e. the account number, order number, etc.
37+
- `queue_timeout_url` *(optional)*: The URL to which the Mpesa API will send the queue timeout response. This is where you will handle the response from the Mpesa API. If not provided, the default queue timeout URL will be used.
38+
- `result_url` *(optional)*: The URL to which the Mpesa API will send the result response. This is where you will handle the response from the Mpesa API. If not provided, the default result URL will be used.
39+
- `command_id` *(optional)*: The command ID. This is used to specify the type of transaction. i.e. BusinessPayBill, BusinessBuyGoods, BusinessPayToBulk, DisburseFundsToBusiness, BusinessToBusinessTransfer, MerchantToMerchantTransfer. There may be other command IDs not listed here.
40+
- BusinessPayBill is the default command ID and is used by paybills.
41+
- BusinessBuyGoods is used by buy goods/till numbers. BusinessPayToBulk is used to pay to a bulk account.
42+
- DisburseFundsToBusiness is used to disburse funds to a business account.
43+
- BusinessToBusinessTransfer is used to transfer funds between businesses.
44+
- MerchantToMerchantTransfer is used to transfer funds between merchants.
45+
- `remarks` *(optional)*: The remarks. This is a description of the transaction.
46+
- `requester_phone_number` *(optional)*: The phone number of the requester. This is the phone number of the person making the request. This is usually the organization's phone number.
47+
- `originator_conversation_id` *(optional)*: The conversation ID. This is used to identify the transaction. It is usually a unique identifier for the transaction. i.e. the account number, order number, etc.
48+
- `shortcode` *(optional)*: The shortcode of the business that will send the funds. If not provided, the default shortcode will be used.
49+
- `initiator_name` *(optional)*: The name of the initiator. This is the name of the person making the request. This is usually the organization's name.
50+
- `initiator_password` *(optional)*: The password of the initiator. This is the password of the person making the request. This is usually the organization's password.
51+
- `sender_identifier_type` *(optional)*: The sender identifier type. This is used to specify the type of identifier. i.e. 4 we don't recommend changing this value.
52+
- `reciever_identifier_type` *(optional)*: The receiver identifier type. This is used to specify the type of identifier. i.e. 4 we don't recommend changing this value.
53+
54+
```php
55+
use \Ghostscypher\Mpesa\Facades\Mpesa;
56+
57+
/**
58+
* @throws \Ghostscypher\Mpesa\Exceptions\MpesaAuthException
59+
* @throws \Ghostscypher\Mpesa\Exceptions\MpesaValidationException
60+
*/
61+
$response = Mpesa::B2B('600000', '1', 'Test');
62+
63+
if($response->successfull()) {
64+
// Success
65+
$response = $response->json();
66+
} else {
67+
// Error
68+
$response = $response->json();
69+
}
70+
```
71+
72+
### Remit tax to KRA
73+
74+
This allows you to remit tax to KRA.
75+
76+
The method takes the following parameters:
77+
78+
- `amount`: The amount to be transferred.
79+
- `account_reference`: The KRA pin number. e.g. P051234567A.
80+
- `queue_timeout_url` *(optional)*: The URL to which the Mpesa API will send the queue timeout response. This is where you will handle the response from the Mpesa API. If not provided, the default queue timeout URL will be used.
81+
- `result_url` *(optional)*: The URL to which the Mpesa API will send the result response. This is where you will handle the response from the Mpesa API. If not provided, the default result URL will be used.
82+
- `remarks` *(optional)*: The remarks. This is a description of the transaction.
83+
- `requester_phone_number` *(optional)*: The phone number of the requester. This is the phone number of the person making the request. This is usually the organization's phone number.
84+
- `originator_conversation_id` *(optional)*: The conversation ID. This is used to identify the transaction. It is usually a unique identifier for the transaction. i.e. the account number, order number, etc.
85+
- `shortcode` *(optional)*: The shortcode of the business that will send the funds. If not provided, the default shortcode will be used.
86+
- `initiator_name` *(optional)*: The name of the initiator. This is the name of the person making the request. This is usually the organization's name.
87+
- `initiator_password` *(optional)*: The password of the initiator. This is the password of the person making the request. This is usually the organization's password.
88+
- `party_b`: The party B shortcode. This is the shortcode that will receive the funds. This is the KRA shortcode i.e. 572572.
89+
- `sender_identifier_type` *(optional)*: The sender identifier type. This is used to specify the type of identifier. i.e. 4 we don't recommend changing this value.
90+
- `reciever_identifier_type` *(optional)*: The receiver identifier type. This is used to specify the type of identifier. i.e. 4 we don't recommend changing this value.
91+
92+
```php
93+
use \Ghostscypher\Mpesa\Facades\Mpesa;
94+
95+
/**
96+
* @throws \Ghostscypher\Mpesa\Exceptions\MpesaAuthException
97+
* @throws \Ghostscypher\Mpesa\Exceptions\MpesaValidationException
98+
*/
99+
$response = Mpesa::B2BRemitTax('1', 'Test');
100+
101+
if($response->successfull()) {
102+
// Success
103+
$response = $response->json();
104+
} else {
105+
// Error
106+
$response = $response->json();
107+
}
108+
```
109+
110+
### Initiate a B2B STK Push
111+
112+
This allows you to initiate a B2B STK push. This is different from the normal STK push. The B2B STK push is used to initiate a payment from a business to another business.
113+
114+
The method takes the following parameters:
115+
116+
- `reciever_shortcode`: The shortcode of the business that will receive the funds.
117+
- `amount`: The amount to be transferred.
118+
- `account_reference`: The account reference. This is used to identify the transaction. It is usually a unique identifier for the transaction. i.e. the account number, order number, etc.
119+
- `callback_url` *(optional)*: The URL to which the Mpesa API will send the callback response. This is where you will handle the response from the Mpesa API. If not provided, the default callback URL will be used.
120+
- `shortcode` *(optional)*: The shortcode of the business that will send the funds. If not provided, the default shortcode will be used.
121+
- `partner_name` *(optional)*: The name of the partner. This is the name of the business that will receive the funds.
122+
- `request_reference_id` *(optional)*: The request reference ID. This is used to identify the transaction. It is usually a unique identifier for the transaction. i.e. the account number, order number, etc.
123+
124+
```php
125+
use \Ghostscypher\Mpesa\Facades\Mpesa;
126+
127+
/**
128+
* @throws \Ghostscypher\Mpesa\Exceptions\MpesaAuthException
129+
* @throws \Ghostscypher\Mpesa\Exceptions\MpesaValidationException
130+
*/
131+
$response = Mpesa::B2BStkPush('600000', '1', 'Test');
132+
133+
if($response->successfull()) {
134+
// Success
135+
$response = $response->json();
136+
} else {
137+
// Error
138+
$response = $response->json();
139+
}
140+
```
141+

‎docs/B2C/_index.md‎

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,4 @@
1+
---
2+
title: B2C APIs
3+
weight: 4
4+
---

‎docs/B2C/introduction.md‎

Lines changed: 44 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,44 @@
1+
---
2+
title: Mpesa B2C APIs
3+
weight: 1
4+
---
5+
6+
## B2C APIs
7+
8+
The M-Pesa B2C API is a powerful and versatile API that enables businesses to disburse funds to both registered and unregistered M-Pesa customers, in real-time. The API is ideal for businesses that need to make payments to individuals, such as refunds, rewards, salaries, and incentives.
9+
10+
This trait contains several methods that will help you get started with the B2C APIs.
11+
12+
## Initiating a B2C Transaction
13+
14+
The `B2C` method is used to initiate a B2C transaction. The method takes in the following parameters:
15+
16+
- `phone_number`: The phone number of the customer. The number is automatically formatted to the correct format. So it means you can pass the phone number in following formats. i.e. `254712345678`, `+254712345678`, `0712345678`
17+
- `amount`: The amount to be paid to the customer.
18+
- `queue_timeout_url` *(optional)*: The URL that Safaricom will send the result of the transaction to if the transaction times out. This URL should be accessible by the Safaricom API.
19+
- `result_url` *(optional)*: The URL that Safaricom will send the result of the transaction to. This URL should be accessible by the Safaricom API.
20+
- `command_id` *(optional)*: The command ID. This is used to specify the type of transaction. The default is `BusinessPayment`. Other options are `SalaryPayment` and `PromotionPayment`. There are many others that you can use. You can check the Safaricom documentation for more information.
21+
- `remarks` *(optional)*: The remarks of the transaction. This is used to describe the transaction. i.e. the product name, service name, etc. This appears in the admin portal.
22+
- `occasion` *(optional)*: The occasion of the transaction. This is used to describe the reason for the transaction. This appears in the admin portal.
23+
- `originator_conversation_id` *(optional)*: The conversation ID of the transaction. This is used to identify the transaction. It is usually a unique identifier for the transaction. i.e. the account number, order number, etc.
24+
- `shortcode` *(optional)*: The shortcode to be used for the transaction. If not provided, the default shortcode will be used.
25+
- `initiator_name` *(optional)*: The name of the initiator. This the username you use to log into the admin portal, or will be the name of user created by the admin. This is used to identify the initiator of the transaction. If not provided, the default initiator name will be used. Please add a valid initiator name in the admin portal.
26+
- `initiator_password` *(optional)*: The password of the initiator. This is the password you use to log into the admin portal, or will be the password of user created by the admin. This is used to authenticate the initiator of the transaction. If not provided, the default initiator password will be used. Please add a valid initiator password in the admin portal.
27+
28+
```php
29+
use Ghostscypher\Mpesa\Facades\Mpesa;
30+
31+
/**
32+
* @throws \Ghostscypher\Mpesa\Exceptions\MpesaAuthException
33+
* @throws \Ghostscypher\Mpesa\Exceptions\MpesaRequestException
34+
*/
35+
$response = Mpesa::B2C('254712345678', '1');
36+
37+
if($response->successful()) {
38+
// Success
39+
$response = $response->json();
40+
} else {
41+
// Error
42+
$response = $response->json();
43+
}
44+
```

0 commit comments

Comments
 (0)