Skip to content

Commit

Permalink
Merge pull request #5 from chapimenge3/main
Browse files Browse the repository at this point in the history
  • Loading branch information
@isrugeek
isrugeek committed Mar 18, 2024
2 parents 87e0c9b + 5bd105f commit dc118e8
Show file tree
Hide file tree
Showing 9 changed files with 884 additions and 117 deletions.
6 changes: 3 additions & 3 deletions .github/workflows/Linter.yml
View file
Expand Up @@ -11,7 +11,7 @@ jobs:
runs-on: ubuntu-latest
strategy:
matrix:
python-version: ["3.8", "3.9", "3.10"]
python-version: ["3.8", "3.9", "3.10", "3.11"]
steps:
- uses: actions/checkout@v3
- name: Set up Python ${{ matrix.python-version }}
Expand All @@ -21,9 +21,9 @@ jobs:
- name: Install dependencies
run: |
python -m pip install --upgrade pip
pip install pylint
pip install ruff
pip install -r requirements.txt
- name: Analysing the code with pylint
run: |
pylint chapa/*
ruff check
4 changes: 2 additions & 2 deletions .github/workflows/deployment.yml
View file
Expand Up @@ -16,10 +16,10 @@ jobs:
- name: Checkout
uses: actions/checkout@v3

- name: Set up Python 3.9
- name: Set up Python 3.10
uses: actions/setup-python@v1
with:
python-version: 3.9
python-version: "3.10"

- name: Version the package
run: |
Expand Down
198 changes: 134 additions & 64 deletions README.md
View file
Expand Up @@ -7,95 +7,165 @@

Unofficial Python SDK for [Chapa API](https://developer.chapa.co/docs).

## Instructions
## Introduction

This is a Python SDK for Chapa API. It is not official and is not supported by Chapa. It is provided as-is. Anyone can contribute to this project.
This document provides a comprehensive guide to integrating and using the Chapa Payment Gateway SDK in your application. Chapa is a powerful payment gateway that supports various payment methods, facilitating seamless transactions for businesses. This SDK simplifies interaction with Chapa’s API, enabling operations such as initiating payments, verifying transactions, and managing subaccounts.

## Installation

```
To use the Chapa SDK in your project, you need to install it using pip, as it is a dependency for making HTTP requests it will also install `httpx` as a dependency.

```bash
pip install chapa
```

## Usage

To begin using the SDK, import the `Chapa` class from the module and instantiate it with your secret key.

### Initializing the SDK

```python
from chapa import Chapa

data = {
'email': 'abebe@bikila.com',
'amount': 1000,
'first_name': 'Abebe',
'last_name': 'Bikila',
'tx_ref': '<your-unique-transaction-id>',
# optional
'callback_url': 'https://www.your-site.com/callback',
'customization': {
'title': '<Your-Company>',
'description': 'Payment for your services',
}
}

chapa = Chapa('<your_api_key>')
response = chapa.initialize(**data)
print(response['data']['checkout_url'])

# Another Implementation
chapa = Chapa('<your_api_key>', response_format='obj')
response = chapa.initialize(**data)
# notice how the response is an object
print(response.data.checkout_url)


# How to verify a transaction
response = chapa.verify('<your-unique-transaction-id>')
# Replace 'your_secret_key' with your actual Chapa secret key
chapa = Chapa('your_secret_key')
```

## Contributing
### Async Support

Pull requests are welcome. For major changes, please open an issue first to discuss what you would like to change. After that free to contribute to this project. Please read the [CONTRIBUTING.md](https://github.com/chapimenge3/chapa/blob/main/CONTRIBUTING.md) file for more information.
The Chapa SDK implements async support using the `AsyncChapa` class. To use the async version of the SDK, import the `AsyncChapa` class from the module and instantiate it with your secret key.

Please make sure to update tests as appropriate.
```python
from chapa import AsyncChapa

# Replace 'your_secret_key' with your actual Chapa secret key
chapa = AsyncChapa('your_secret')
```

All of the below methods are available in the async version of the SDK. So you can just use it as you would use the sync version.

```python
response = await chapa.initialize(
...
)
```

### Making Payments

To initiate a payment, use the `initialize` method. This method requires a set of parameters like the customer's email, amount, first name, last name, and a transaction reference.

```python
response = chapa.initialize(
email="customer@example.com",
amount=1000,
first_name="John",
last_name="Doe",
tx_ref="your_unique_transaction_reference",
callback_url="https://yourcallback.url/here"
)
print(response)
```

### Verifying Payments

After initiating a payment, you can verify the transaction status using the `verify` method.

```python
transaction_id = "your_transaction_id"
verification_response = chapa.verify(transaction_id)
print(verification_response)
```

### Creating Subaccounts

You can create subaccounts for split payments using the `create_subaccount` method.

## API Reference
```python
subaccount_response = chapa.create_subaccount(
business_name="My Business",
account_name="My Business Account",
bank_code="12345",
account_number="0012345678",
split_value="0.2",
split_type="percentage"
)
print(subaccount_response)
```

### Create new Transaction
### Bank Transfers

Base endpoint https://api.chapa.co/v1
To initiate a bank transfer, use the `transfer_to_bank` method.

```http
POST /transaction/initialize
```python
transfer_response = chapa.transfer_to_bank(
account_name="Recipient Name",
account_number="0987654321",
amount="500",
reference="your_transfer_reference",
bank_code="67890",
currency="ETB"
)
print(transfer_response)
```

| Parameter | Type | Description |
| :---------------------- | :-------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `key` | `string` | **Required**. This will be your public key from Chapa. When on test mode use the test key, and when on live mode use the live key. |
| `email` | `string` | **Required**. A customer’s email. address |
| `amount` | `integer` | **Required**. The amount you will be charging your customer. |
| `first_name` | `string` | **Required**. Your API key |
| `last_name` | `string` | **Required**. A customer’s last name. |
| `tx_ref` | `string` | **Required**. A unique reference given to each transaction. |
| `currency` | `string` | **Required**. The currency in which all the charges are made. Currency allowed is ETB. |
| `callback_url` | `string` | The URL to redirect the customer to after payment is done. |
| `customization[title]` | `string` | The customizations field (optional) allows you to customize the look and feel of the payment modal. You can set a logo, the store name to be displayed (title), and a description for the payment. |

| HEADER Key | Value |
| :-------------- | :---------------------- |
| `Authorization` | `Bearer <YOUR-API-KEY>` |

### Verify Transaction

```http
GET /transaction/verify/${tx_ref}
### Verifying Webhook

The reason for verifying a webhook is to ensure that the request is coming from Chapa. You can verify a webhook using the `verify_webhook` method.

```python
from chapa import verify_webhook

# request is just an example of a request object
# request.body is the request body
# request.headers.get("Chapa-Signature") is the Chapa-Signature header

verify_webhook(
secret_key="your_secret_key",
body=request.body,
chapa_signature=request.headers.get("Chapa-Signature")
)
```

| Parameter | Type | Description |
| :-------- | :------- | :--------------------------------------------------------- |
| `tx_ref` | `string` | **Required**. A unique reference given to each transaction |
### Getting Testing Cards and Mobile Numbers

For testing purposes, you can retrieve a set of test cards and mobile numbers.

```python
from chapa import get_testing_cards, get_testing_mobile

# Get a list of testing cards
test_cards = get_testing_cards()
print(test_cards)

# Get a list of testing mobile numbers
test_mobiles = get_testing_mobile()
print(test_mobiles)
```

## FAQ
### Get Webhook Events

#### No Available Questions!
You can get webhook events details with description like below

```python
from chapa import WEBHOOK_EVENTS, WEBHOOKS_EVENT_DESCRIPTION

# Get a list of webhook events
print(WEBHOOK_EVENTS)

# Get a list of webhook events with description
print(WEBHOOKS_EVENT_DESCRIPTION)
```

## Conclusion

The Chapa Payment Gateway SDK is a flexible tool that allows developers to integrate various payment functionalities into their applications easily. By following the steps outlined in this documentation, you can implement features like payment initialization, transaction verification, and sub-account management. Feel free to explore the SDK further to discover all the supported features and functionalities.

## Contributing

Pull requests are welcome. For major changes, please open an issue first to discuss what you would like to change. After that free to contribute to this project. Please read the [CONTRIBUTING.md](https://github.com/chapimenge3/chapa/blob/main/CONTRIBUTING.md) file for more information.

Please make sure to update tests as appropriate.

## Run Locally

Expand All @@ -108,7 +178,7 @@ git clone https://github.com/chapimenge3/chapa.git
Go to the project directory

```bash
cd chapa
cd chapa
```

Install dependencies
Expand Down
14 changes: 12 additions & 2 deletions chapa/__init__.py
View file
Expand Up @@ -12,5 +12,15 @@
PyPI: https://pypi.org/project/Chapa/
"""

from .api import *
from .webhook import *
from .api import Chapa, AsyncChapa, get_testing_cards, get_testing_mobile
from .webhook import verify_webhook, WEBHOOK_EVENTS, WEBHOOKS_EVENT_DESCRIPTION

__all__ = [
'Chapa',
'AsyncChapa',
'get_testing_cards',
'get_testing_mobile',
'verify_webhook',
'WEBHOOK_EVENTS',
'WEBHOOKS_EVENT_DESCRIPTION'
]

0 comments on commit dc118e8

Please sign in to comment.