# Zibal Payment
**Zibal Payment** is a Python package designed to easily integrate Zibal’s online payment gateway into Django applications, providing a smooth setup process and efficient handling of payment requests, URL generation, and transaction verification.
## Key Features
- **Quick Integration**: Seamlessly integrate Zibal’s payment gateway into Django projects with minimal configuration.
- **Complete Payment Lifecycle**: Supports all steps of the payment process, from request creation to transaction verification.
- **Sandbox Mode**: Enables safe testing in a controlled environment without real transactions.
- **Secure and Reliable**: Built with robust measures to ensure transaction data security and reliability.
---
## Installation
Install the zibal_payment package from PyPI:
```bash
pip install zibal-payment
```
---
## Getting Started
Follow these steps to configure and use zibal_payment in your Django projects.
### 1. Initializing the Client
To initialize the `ZibalClient`, provide your Zibal `merchant_id`. This client is essential for interacting with Zibal’s payment services.
```python
from zibal_payment.client import ZibalClient
# Initialize ZibalClient with your merchant ID for handling payment requests
client = ZibalClient(merchant_id="your_merchant_id", sandbox=True)
```
#### Parameters
- **`merchant_id` (str)**: Your Zibal merchant ID.
- **`sandbox` (bool, optional)**: Set to `True` for testing purposes. Defaults to `True`.
- **`timeout` (int or float, optional)**: The maximum time (in seconds) to wait for Zibal's response. Defaults to `10` seconds.
- **`enable_logging` (bool, optional)**: Enables logging for debugging purposes. Defaults to `True`.
### 2. Creating a Payment Request
To initiate a payment request, use the `payment_request` method, specifying the `amount`, `callback_url`, and `description`. This method returns essential transaction information, including a `trackId`.
```python
try:
response = client.payment_request(
amount=1000, # Amount in Rials
callback_url="https://example.com/callback", # URL to redirect users after payment
description="Order #123" # Payment description
)
track_id = response.get("trackId")
print(f"Payment request successful. Track ID: {track_id}")
except ZibalError as e:
print(f"Payment request error: {e}")
```
#### Parameters
- **`amount` (int)**: Amount in Rials.
- **`callback_url` (str)**: URL where users will be redirected post-payment.
- **`description` (str)**: Description of the payment (e.g., order details).
#### Returns
A dictionary containing `trackId` and `result`. Track ID is necessary for generating a payment URL or verifying the transaction.
### 3. Generating a Payment URL
With the obtained `trackId`, you can generate a user-friendly URL for redirecting users to Zibal’s payment page.
```python
payment_url = client.generate_payment_url(track_id)
print(f"Payment URL: {payment_url}")
```
#### Returns
- **URL** (str): The complete URL for the user to make a payment on Zibal’s gateway.
### 4. Verifying a Payment
After users complete the payment, use `payment_verify` to confirm the transaction with Zibal using the `trackId`.
```python
try:
verification_response = client.payment_verify(track_id=track_id)
print("Payment verification successful:", verification_response)
except ZibalError as e:
print(f"Verification error: {e}")
```
#### Parameters
- **`track_id` (str)**: Track ID of the transaction to verify.
#### Returns
A dictionary containing verification details, including `result`, `amount`, and other transaction data.
### Example Workflow
Here's a quick workflow example to illustrate how these functions can be combined:
```python
from zibal_payment.client import ZibalClient
client = ZibalClient(merchant_id="your_merchant_id")
try:
# Step 1: Create a payment request
response = client.payment_request(
amount=1000,
callback_url="https://example.com/callback",
description="Test Payment"
)
track_id = response.get("trackId")
# Step 2: Generate the payment URL
payment_url = client.generate_payment_url(track_id)
print(f"Direct user to this URL for payment: {payment_url}")
# Step 3: After payment, verify the transaction
verification = client.payment_verify(track_id)
print("Payment verification details:", verification)
except ZibalError as e:
print(f"An error occurred: {e}")
```
---
## API Reference
For complete details on methods, parameters, and error handling, please refer to the [API Documentation](https://github.com/Mohammad222PR/zibal_payment/docs/api_reference.md).
---
## Contributions and Support
We welcome community contributions! To report issues, request features, or contribute to this project, please visit our [GitHub repository](https://github.com/Mohammad222PR/zibal-payment).
For further instructions on advanced usage and troubleshooting, see the [Usage Guide](https://github.com/Mohammad222PR/zibal-payment/blob/main/docs/usage.md).
---
Raw data
{
"_id": null,
"home_page": "https://github.com/Mohammad222PR/zibal_payment",
"name": "zibal-payment",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.6",
"maintainer_email": null,
"keywords": "payment gateway django integration online payments",
"author": "Mohammad Eslami",
"author_email": null,
"download_url": "https://files.pythonhosted.org/packages/c7/7f/b0ac321a0f6b7c2418560ff714966bbc5d15ca4ad2fc392381b4bcdfe9d0/zibal_payment-1.0.2.tar.gz",
"platform": null,
"description": "# Zibal Payment\r\n\r\n**Zibal Payment** is a Python package designed to easily integrate Zibal\u2019s online payment gateway into Django applications, providing a smooth setup process and efficient handling of payment requests, URL generation, and transaction verification. \r\n\r\n## Key Features\r\n\r\n- **Quick Integration**: Seamlessly integrate Zibal\u2019s payment gateway into Django projects with minimal configuration.\r\n- **Complete Payment Lifecycle**: Supports all steps of the payment process, from request creation to transaction verification.\r\n- **Sandbox Mode**: Enables safe testing in a controlled environment without real transactions.\r\n- **Secure and Reliable**: Built with robust measures to ensure transaction data security and reliability.\r\n\r\n---\r\n\r\n## Installation\r\n\r\nInstall the zibal_payment package from PyPI:\r\n\r\n```bash\r\npip install zibal-payment\r\n```\r\n\r\n---\r\n\r\n## Getting Started\r\n\r\nFollow these steps to configure and use zibal_payment in your Django projects.\r\n\r\n### 1. Initializing the Client\r\n\r\nTo initialize the `ZibalClient`, provide your Zibal `merchant_id`. This client is essential for interacting with Zibal\u2019s payment services.\r\n\r\n```python\r\nfrom zibal_payment.client import ZibalClient\r\n\r\n# Initialize ZibalClient with your merchant ID for handling payment requests\r\nclient = ZibalClient(merchant_id=\"your_merchant_id\", sandbox=True)\r\n```\r\n\r\n#### Parameters\r\n- **`merchant_id` (str)**: Your Zibal merchant ID.\r\n- **`sandbox` (bool, optional)**: Set to `True` for testing purposes. Defaults to `True`.\r\n- **`timeout` (int or float, optional)**: The maximum time (in seconds) to wait for Zibal's response. Defaults to `10` seconds.\r\n- **`enable_logging` (bool, optional)**: Enables logging for debugging purposes. Defaults to `True`.\r\n\r\n### 2. Creating a Payment Request\r\n\r\nTo initiate a payment request, use the `payment_request` method, specifying the `amount`, `callback_url`, and `description`. This method returns essential transaction information, including a `trackId`.\r\n\r\n```python\r\ntry:\r\n response = client.payment_request(\r\n amount=1000, # Amount in Rials\r\n callback_url=\"https://example.com/callback\", # URL to redirect users after payment\r\n description=\"Order #123\" # Payment description\r\n )\r\n track_id = response.get(\"trackId\")\r\n print(f\"Payment request successful. Track ID: {track_id}\")\r\n\r\nexcept ZibalError as e:\r\n print(f\"Payment request error: {e}\")\r\n```\r\n\r\n#### Parameters\r\n- **`amount` (int)**: Amount in Rials.\r\n- **`callback_url` (str)**: URL where users will be redirected post-payment.\r\n- **`description` (str)**: Description of the payment (e.g., order details).\r\n\r\n#### Returns\r\nA dictionary containing `trackId` and `result`. Track ID is necessary for generating a payment URL or verifying the transaction.\r\n\r\n### 3. Generating a Payment URL\r\n\r\nWith the obtained `trackId`, you can generate a user-friendly URL for redirecting users to Zibal\u2019s payment page.\r\n\r\n```python\r\npayment_url = client.generate_payment_url(track_id)\r\nprint(f\"Payment URL: {payment_url}\")\r\n```\r\n\r\n#### Returns\r\n- **URL** (str): The complete URL for the user to make a payment on Zibal\u2019s gateway.\r\n\r\n### 4. Verifying a Payment\r\n\r\nAfter users complete the payment, use `payment_verify` to confirm the transaction with Zibal using the `trackId`.\r\n\r\n```python\r\ntry:\r\n verification_response = client.payment_verify(track_id=track_id)\r\n print(\"Payment verification successful:\", verification_response)\r\n\r\nexcept ZibalError as e:\r\n print(f\"Verification error: {e}\")\r\n```\r\n\r\n#### Parameters\r\n- **`track_id` (str)**: Track ID of the transaction to verify.\r\n\r\n#### Returns\r\nA dictionary containing verification details, including `result`, `amount`, and other transaction data.\r\n\r\n### Example Workflow\r\n\r\nHere's a quick workflow example to illustrate how these functions can be combined:\r\n\r\n```python\r\nfrom zibal_payment.client import ZibalClient\r\n\r\nclient = ZibalClient(merchant_id=\"your_merchant_id\")\r\n\r\ntry:\r\n # Step 1: Create a payment request\r\n response = client.payment_request(\r\n amount=1000,\r\n callback_url=\"https://example.com/callback\",\r\n description=\"Test Payment\"\r\n )\r\n track_id = response.get(\"trackId\")\r\n \r\n # Step 2: Generate the payment URL\r\n payment_url = client.generate_payment_url(track_id)\r\n print(f\"Direct user to this URL for payment: {payment_url}\")\r\n\r\n # Step 3: After payment, verify the transaction\r\n verification = client.payment_verify(track_id)\r\n print(\"Payment verification details:\", verification)\r\n\r\nexcept ZibalError as e:\r\n print(f\"An error occurred: {e}\")\r\n```\r\n\r\n---\r\n\r\n## API Reference\r\n\r\nFor complete details on methods, parameters, and error handling, please refer to the [API Documentation](https://github.com/Mohammad222PR/zibal_payment/docs/api_reference.md).\r\n\r\n---\r\n\r\n## Contributions and Support\r\n\r\nWe welcome community contributions! To report issues, request features, or contribute to this project, please visit our [GitHub repository](https://github.com/Mohammad222PR/zibal-payment). \r\n\r\nFor further instructions on advanced usage and troubleshooting, see the [Usage Guide](https://github.com/Mohammad222PR/zibal-payment/blob/main/docs/usage.md).\r\n\r\n---\r\n\r\n",
"bugtrack_url": null,
"license": null,
"summary": "A simple and secure Python package for integrating online payment processing in Django projects.",
"version": "1.0.2",
"project_urls": {
"Homepage": "https://github.com/Mohammad222PR/zibal_payment"
},
"split_keywords": [
"payment",
"gateway",
"django",
"integration",
"online",
"payments"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "2115f924a339a48658cf4855f1f1c6ec2889714495738e2b47a237984ad1f225",
"md5": "ee3724a030c87d9e1812d5bd39f5b5f5",
"sha256": "222cbc16a0381d83fd40d6c6aba112e6e12dfbdf691232947ffab6b65fe8fcb8"
},
"downloads": -1,
"filename": "zibal_payment-1.0.2-py3-none-any.whl",
"has_sig": false,
"md5_digest": "ee3724a030c87d9e1812d5bd39f5b5f5",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.6",
"size": 8640,
"upload_time": "2024-10-26T16:13:02",
"upload_time_iso_8601": "2024-10-26T16:13:02.544929Z",
"url": "https://files.pythonhosted.org/packages/21/15/f924a339a48658cf4855f1f1c6ec2889714495738e2b47a237984ad1f225/zibal_payment-1.0.2-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "c77fb0ac321a0f6b7c2418560ff714966bbc5d15ca4ad2fc392381b4bcdfe9d0",
"md5": "bdfe32ce0ee7fd03ade856822e093fc9",
"sha256": "aeeecdae8d8c25cd0f561b8bee5f5adf18c48169334d0e1758415e034ed1bb53"
},
"downloads": -1,
"filename": "zibal_payment-1.0.2.tar.gz",
"has_sig": false,
"md5_digest": "bdfe32ce0ee7fd03ade856822e093fc9",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.6",
"size": 9397,
"upload_time": "2024-10-26T16:13:04",
"upload_time_iso_8601": "2024-10-26T16:13:04.752619Z",
"url": "https://files.pythonhosted.org/packages/c7/7f/b0ac321a0f6b7c2418560ff714966bbc5d15ca4ad2fc392381b4bcdfe9d0/zibal_payment-1.0.2.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-10-26 16:13:04",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "Mohammad222PR",
"github_project": "zibal_payment",
"github_not_found": true,
"lcname": "zibal-payment"
}
JSON
