# DARAJA CONNECT
A wrapper library for the Daraja Mpesa API
[![Language](https://img.shields.io/badge/language-python-green.svg)](https://python.org)
## Features
- Authorization
- Mpesa Express
- STK Push
- Query
- Customer To Business (C2B)
- Register URL
- Simulate
- Business To Customer (B2C)
- Account Balance
- Transaction Status
## Installation
$ pip install daraja-connect
## Usage
*NOTE: Before you start, make sure to go through the official Daraja Mpesa API [documentation](https://developer.safaricom.co.ke/Documentation)*
Create an app instance.
```python
from daraja_connect import App
# Sandbox
app = App.create_sandbox(consumer_key=..., consumer_secret=...)
# Production
app = App.create_production(consumer_key=..., consumer_secret=...)
```
Generate an authorization token.
```python
from daraja_connect import Authorization
auth = Authorization(app)
result = auth.generate_token()
access_token = result.access_token
```
*You can attach this token to the service instance or include it as an argument to the api methods calls*
### Mpesa Express
**STK Push**
```python
from daraja_connect import STKPush
stk = STKPush(app, access_token=access_token)
result = stk.process_request(
business_short_code=...,
phone_number=...,
amount=...,
call_back_url=...,
account_reference=...,
transaction_desc=...,
password=...,
timestamp=...,
)
```
**Query**
```python
result = stk.query(
business_short_code=...,
checkout_request_id=...,
password=...,
)
```
You can use the `generate_password` helper to create a password
```python
from daraja_connect.utils import generate_password
password = generate_password(
business_short_code=....,
pass_key=...,
timestamp=...,
)
```
Alternatively, you can include the `pass_key` argument in place of `password` to auto generate the password
### Customer To Business (C2B) API
**Register URL**
```python
from daraja_connect import C2B
from daraja_connect.enums import ResponseType
c2b = C2B(app, access_token=access_token)
result = c2b.register_url(
short_code=...,
validation_url=...,
confirmation_url=...,
response_type=ResponseType.COMPLETED,
)
```
**Simulate**
```python
result = c2b.simulate(
short_code=...,
command_id=TransactionType.CUSTOMER_PAY_BILL_ONLINE,
amount=...,
msisdn=...,
bill_ref_number=...,
)
```
### Business To Customer (B2C) API
```python
from daraja_connect import B2C
from daraja_connect.enums import TransactionType
b2c = B2C(app, access_token=access_token)
result = b2c.payment_request(
initiator_name=...,
security_credential=...,
amount=...,
command_id=TransactionType.BUSINESS_PAYMENT,
party_a=...,
party_b=...,
queue_time_out_url=...,
result_url=...,
remarks=...,
occassion=...,
)
```
### Account Balance API
```python
from daraja_connect import AccountBalance
from daraja_connect.enums import TransactionType, IdentifierType
ab = AccountBalance(app, access_token=access_token)
result = ab.query(
initiator=...,
security_credential=...,
command_id=TransactionType.ACCOUNT_BALANCE,
identifier_type=IdentifierType.ORGANIZATION_SHORT_CODE,
party_a=...,
queue_time_out_url=...,
result_url=...,
remarks=...,
)
```
### Transaction Status API
```python
from daraja_connect import TransactionStatus
from daraja_connect.enums import TransactionType, IdentifierType
ts = TransactionStatus(app, access_token=access_token)
result = ts.query(
initiator=...,
security_credential=...,
transaction_id=...,
command_id=TransactionType.TRANSACTION_STATUS_QUERY,
identifier_type=IdentifierType.ORGANIZATION_SHORT_CODE,
party_a=...,
queue_time_out_url=...,
result_url=...,
remarks=...,
occassion=...,
)
```
All API methods return a result object with a response property which is a [`requests.Response`](https://requests.readthedocs.io/en/latest/api/#requests.Response) object and various properties corresponding to the json body of the response
## Running Tests
Install dependencies
$ poetry install
Create `.env` file from [.env.example](https://github.com/enwawerueli/daraja-connect/blob/main/.env.example) then edit it to add your app credentials and test parameters
$ cp .env.example .env
Run tests
$ poetry run pytest
## License
[MIT](https://github.com/enwawerueli/daraja-connect/blob/main/LICENSE)
Raw data
{
"_id": null,
"home_page": "https://github.com/enwawerueli/daraja-connect",
"name": "daraja-connect",
"maintainer": "",
"docs_url": null,
"requires_python": ">=3.8,<4.0",
"maintainer_email": "",
"keywords": "daraja,mpesa,payment",
"author": "Emz D",
"author_email": "seaworndrift@gmail.com",
"download_url": "https://files.pythonhosted.org/packages/45/1a/d29399ca97f761bec7bfdf57994cfadb65c70b20c5d8ac3d584c74bab478/daraja_connect-0.1.0b2.tar.gz",
"platform": null,
"description": "# DARAJA CONNECT\n\nA wrapper library for the Daraja Mpesa API\n\n[![Language](https://img.shields.io/badge/language-python-green.svg)](https://python.org)\n\n## Features\n\n- Authorization\n- Mpesa Express\n - STK Push\n - Query\n- Customer To Business (C2B)\n - Register URL\n - Simulate\n- Business To Customer (B2C)\n- Account Balance\n- Transaction Status\n\n## Installation\n\n $ pip install daraja-connect\n\n## Usage\n\n*NOTE: Before you start, make sure to go through the official Daraja Mpesa API [documentation](https://developer.safaricom.co.ke/Documentation)* \n\nCreate an app instance. \n\n```python\nfrom daraja_connect import App\n\n# Sandbox\napp = App.create_sandbox(consumer_key=..., consumer_secret=...)\n\n# Production\napp = App.create_production(consumer_key=..., consumer_secret=...)\n```\n\nGenerate an authorization token.\n\n```python\nfrom daraja_connect import Authorization\n\nauth = Authorization(app)\nresult = auth.generate_token()\naccess_token = result.access_token\n```\n*You can attach this token to the service instance or include it as an argument to the api methods calls*\n\n### Mpesa Express\n\n**STK Push**\n```python\nfrom daraja_connect import STKPush\n\nstk = STKPush(app, access_token=access_token)\nresult = stk.process_request(\n business_short_code=...,\n phone_number=...,\n amount=...,\n call_back_url=...,\n account_reference=...,\n transaction_desc=...,\n password=...,\n timestamp=...,\n)\n```\n\n**Query**\n```python\nresult = stk.query(\n business_short_code=...,\n checkout_request_id=...,\n password=...,\n)\n```\nYou can use the `generate_password` helper to create a password\n\n```python\nfrom daraja_connect.utils import generate_password\n\npassword = generate_password(\n business_short_code=....,\n pass_key=...,\n timestamp=...,\n)\n```\nAlternatively, you can include the `pass_key` argument in place of `password` to auto generate the password\n\n### Customer To Business (C2B) API\n\n**Register URL**\n```python\nfrom daraja_connect import C2B\nfrom daraja_connect.enums import ResponseType\n\nc2b = C2B(app, access_token=access_token)\nresult = c2b.register_url(\n short_code=...,\n validation_url=...,\n confirmation_url=...,\n response_type=ResponseType.COMPLETED,\n)\n```\n\n**Simulate**\n```python\nresult = c2b.simulate(\n short_code=...,\n command_id=TransactionType.CUSTOMER_PAY_BILL_ONLINE,\n amount=...,\n msisdn=...,\n bill_ref_number=...,\n)\n```\n\n### Business To Customer (B2C) API\n\n```python\nfrom daraja_connect import B2C\nfrom daraja_connect.enums import TransactionType\n\nb2c = B2C(app, access_token=access_token)\nresult = b2c.payment_request(\n initiator_name=...,\n security_credential=...,\n amount=...,\n command_id=TransactionType.BUSINESS_PAYMENT,\n party_a=...,\n party_b=...,\n queue_time_out_url=...,\n result_url=...,\n remarks=...,\n occassion=...,\n)\n```\n\n### Account Balance API\n\n```python\nfrom daraja_connect import AccountBalance\nfrom daraja_connect.enums import TransactionType, IdentifierType\n\nab = AccountBalance(app, access_token=access_token)\nresult = ab.query(\n initiator=...,\n security_credential=...,\n command_id=TransactionType.ACCOUNT_BALANCE,\n identifier_type=IdentifierType.ORGANIZATION_SHORT_CODE,\n party_a=...,\n queue_time_out_url=...,\n result_url=...,\n remarks=...,\n)\n```\n\n### Transaction Status API\n\n```python\nfrom daraja_connect import TransactionStatus\nfrom daraja_connect.enums import TransactionType, IdentifierType\n\nts = TransactionStatus(app, access_token=access_token)\nresult = ts.query(\n initiator=...,\n security_credential=...,\n transaction_id=...,\n command_id=TransactionType.TRANSACTION_STATUS_QUERY,\n identifier_type=IdentifierType.ORGANIZATION_SHORT_CODE,\n party_a=...,\n queue_time_out_url=...,\n result_url=...,\n remarks=...,\n occassion=...,\n)\n```\n\nAll API methods return a result object with a response property which is a [`requests.Response`](https://requests.readthedocs.io/en/latest/api/#requests.Response) object and various properties corresponding to the json body of the response\n\n## Running Tests\n\nInstall dependencies\n\n $ poetry install\n\nCreate `.env` file from [.env.example](https://github.com/enwawerueli/daraja-connect/blob/main/.env.example) then edit it to add your app credentials and test parameters\n\n $ cp .env.example .env\n\n Run tests\n\n $ poetry run pytest\n\n## License\n\n[MIT](https://github.com/enwawerueli/daraja-connect/blob/main/LICENSE)\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "A wrapper library for the Daraja Mpesa API",
"version": "0.1.0b2",
"split_keywords": [
"daraja",
"mpesa",
"payment"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "ea1962b0339f28f992e3f7d0053a4a2f48b25a085ea733e98e6d62519a8af30d",
"md5": "3b88d414e5489f0fa894d7716295b2cc",
"sha256": "e4d7dc7f2554a97bba465ce6eb5be716e281957bd63b0fc4bd49ed0a70f05c78"
},
"downloads": -1,
"filename": "daraja_connect-0.1.0b2-py3-none-any.whl",
"has_sig": false,
"md5_digest": "3b88d414e5489f0fa894d7716295b2cc",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.8,<4.0",
"size": 11813,
"upload_time": "2023-01-31T12:00:54",
"upload_time_iso_8601": "2023-01-31T12:00:54.165319Z",
"url": "https://files.pythonhosted.org/packages/ea/19/62b0339f28f992e3f7d0053a4a2f48b25a085ea733e98e6d62519a8af30d/daraja_connect-0.1.0b2-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "451ad29399ca97f761bec7bfdf57994cfadb65c70b20c5d8ac3d584c74bab478",
"md5": "d1842d64cbde5f4f0a345ddf4530411d",
"sha256": "bbb992da6a2fd0ff4f99a0df4b6735040314acbc0ace59ff31ad439297d85150"
},
"downloads": -1,
"filename": "daraja_connect-0.1.0b2.tar.gz",
"has_sig": false,
"md5_digest": "d1842d64cbde5f4f0a345ddf4530411d",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.8,<4.0",
"size": 10675,
"upload_time": "2023-01-31T12:00:56",
"upload_time_iso_8601": "2023-01-31T12:00:56.531456Z",
"url": "https://files.pythonhosted.org/packages/45/1a/d29399ca97f761bec7bfdf57994cfadb65c70b20c5d8ac3d584c74bab478/daraja_connect-0.1.0b2.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2023-01-31 12:00:56",
"github": true,
"gitlab": false,
"bitbucket": false,
"github_user": "enwawerueli",
"github_project": "daraja-connect",
"travis_ci": false,
"coveralls": false,
"github_actions": false,
"lcname": "daraja-connect"
}