# Himosoft Payment Client
A Python client library for integrating with the Himosoft Payment Logging API. This package provides a simple and robust way to log payment transactions from your applications to a centralized payment monitoring system.
## Features
- **Simple Integration**: Easy-to-use client library for logging payments
- **Comprehensive Validation**: Built-in validation for all payment data
- **Error Handling**: Detailed error handling with custom exceptions
- **Environment Configuration**: Support for environment variable configuration
- **Multiple Data Types**: Support for float, Decimal, and string amounts
- **Connection Testing**: Built-in connection testing functionality
- **Django Integration**: Ready-to-use Django integration examples
- **Comprehensive Testing**: Full test coverage with pytest
## Installation
### Using pip
```bash
pip install himosoft-payment-logging-client
```
### From source
```bash
git clone https://github.com/Swe-HimelRana/payment-logging-client.git
cd payment-client
pip install -e .
```
## Quick Start
### 1. Set up environment variables
```bash
export PAYMENT_RECORD_SERVER_URL="http://your-payment-server.com"
export PAYMENT_RECORD_PLATFORM_API_KEY="your-platform-api-key-here"
```
### 2. Basic usage
```python
from himosoft_payment_client import PaymentLogger
# Initialize the client
logger = PaymentLogger()
# Log a successful payment
result = logger.log_payment(
user="john.doe@example.com",
package="Premium Plan",
amount=99.99,
status="paid",
trx_id="TXN123456789",
payment_method="credit_card",
gateway_name="Stripe",
gateway_log={
"payment_intent_id": "pi_1234567890",
"charge_id": "ch_1234567890",
"amount": 9999,
"currency": "usd",
"status": "succeeded"
}
)
print(f"Payment logged: {result}")
```
## Configuration
### Environment Variables
The package uses the following environment variables:
- `PAYMENT_RECORD_SERVER_URL`: The URL of your payment logging server
- `PAYMENT_RECORD_PLATFORM_API_KEY`: Your platform's API key
### Manual Configuration
You can also pass configuration directly to the client:
```python
logger = PaymentLogger(
server_url="http://your-server.com",
api_key="your-api-key"
)
```
## API Reference
### PaymentLogger Class
#### Constructor
```python
PaymentLogger(server_url=None, api_key=None)
```
**Parameters:**
- `server_url` (str, optional): Payment server URL
- `api_key` (str, optional): Platform API key
If not provided, these values will be read from environment variables.
#### Methods
##### log_payment()
```python
log_payment(
user,
package,
amount,
status,
trx_id=None,
payment_method=None,
gateway_name=None,
gateway_log=None
)
```
**Parameters:**
- `user` (str): User identifier (email, username, or phone)
- `package` (str): Package or plan name
- `amount` (float/Decimal/str): Payment amount (positive number)
- `status` (str): Payment status ('paid', 'failed', 'canceled', 'refunded')
- `trx_id` (str, optional): Transaction ID (required for 'paid' and 'refunded' status)
- `payment_method` (str, optional): Payment method used
- `gateway_name` (str, optional): Payment gateway name
- `gateway_log` (dict, optional): Complete gateway response
**Returns:**
- `dict`: API response containing status and message
**Raises:**
- `PaymentLoggerValidationError`: If input validation fails
- `PaymentLoggerAPIError`: If the API returns an error
- `PaymentLoggerNetworkError`: If there's a network error
##### test_connection()
```python
test_connection()
```
**Returns:**
- `bool`: True if connection is successful
**Raises:**
- `PaymentLoggerNetworkError`: If connection fails
## Payment Statuses
The following payment statuses are supported:
- `paid`: Payment was successful (requires trx_id)
- `failed`: Payment failed
- `canceled`: Payment was canceled
- `refunded`: Payment was refunded (requires trx_id)
## Error Handling
The package provides several custom exceptions for different error types:
### PaymentLoggerError
Base exception for all payment logger errors.
### PaymentLoggerValidationError
Raised when input validation fails.
```python
try:
logger.log_payment(
user="",
package="Basic Plan",
amount=19.99,
status="paid"
)
except PaymentLoggerValidationError as e:
print(f"Validation error: {e}")
```
### PaymentLoggerAPIError
Raised when the API returns an error response.
```python
try:
result = logger.log_payment(...)
except PaymentLoggerAPIError as e:
print(f"API error: {e}")
print(f"Status code: {e.status_code}")
print(f"Response data: {e.response_data}")
```
### PaymentLoggerNetworkError
Raised when there's a network-related error.
```python
try:
result = logger.log_payment(...)
except PaymentLoggerNetworkError as e:
print(f"Network error: {e}")
```
### PaymentLoggerConfigError
Raised when there's a configuration error.
```python
try:
logger = PaymentLogger()
except PaymentLoggerConfigError as e:
print(f"Configuration error: {e}")
```
## Examples
### Basic Usage
```python
from himosoft_payment_client import PaymentLogger
logger = PaymentLogger()
# Successful payment
result = logger.log_payment(
user="user@example.com",
package="Premium Plan",
amount=99.99,
status="paid",
trx_id="TXN123456",
payment_method="credit_card",
gateway_name="Stripe",
gateway_log={"charge_id": "ch_123"}
)
# Failed payment
result = logger.log_payment(
user="user@example.com",
package="Basic Plan",
amount=19.99,
status="failed",
payment_method="credit_card",
gateway_name="Stripe",
gateway_log={"error": "card_declined"}
)
```
### Django Integration
```python
# settings.py
PAYMENT_RECORD_SERVER_URL = 'http://your-payment-server.com'
PAYMENT_RECORD_PLATFORM_API_KEY = 'your-api-key-here'
# views.py
from himosoft_payment_client import PaymentLogger
from django.conf import settings
def process_payment(request):
logger = PaymentLogger(
server_url=settings.PAYMENT_RECORD_SERVER_URL,
api_key=settings.PAYMENT_RECORD_PLATFORM_API_KEY
)
try:
result = logger.log_payment(
user=request.user.email,
package="Premium Plan",
amount=99.99,
status="paid",
trx_id=transaction_id,
payment_method="credit_card",
gateway_name="Stripe",
gateway_log=gateway_response
)
return JsonResponse({"status": "success", "result": result})
except PaymentLoggerError as e:
return JsonResponse({"status": "error", "message": str(e)})
```
### Testing Connection
```python
logger = PaymentLogger()
try:
if logger.test_connection():
print("Connection successful")
else:
print("Connection failed")
except PaymentLoggerNetworkError as e:
print(f"Connection error: {e}")
```
## Validation Rules
The package enforces the following validation rules:
1. **User**: Required, cannot be empty
2. **Package**: Required, cannot be empty
3. **Amount**: Required, must be a positive number
4. **Status**: Must be one of: 'paid', 'failed', 'canceled', 'refunded'
5. **TRX ID**: Required for 'paid' and 'refunded' statuses
6. **Gateway Log**: Must be a dictionary if provided
## Development
### Setting up development environment
```bash
# Clone the repository
git clone https://github.com/Swe-HimelRana/payment-logging-client.git
cd payment-logging-client
# Create virtual environment
python3 -m venv venv
source venv/bin/activate # On Windows: venv\Scripts\activate
# Install development dependencies
pip install -r requirements-dev.txt
# Install package in development mode
pip install -e .
```
### Running tests
```bash
# Run all tests
pytest
# Run tests with coverage
pytest --cov=payment-logging-client
# Run specific test file
pytest tests/test_client.py
# Run tests with verbose output
pytest -v
```
### Code formatting
```bash
# Format code with black
black payment-logging-client/ tests/ examples/
# Check code style with flake8
flake8 payment-logging-client/ tests/ examples/
```
### Running examples
```bash
# Run basic usage example
python examples/basic_usage.py
# Run Django integration example (requires Django)
python examples/django_integration.py
```
## Contributing
1. Fork the repository
2. Create a feature branch (`git checkout -b feature/amazing-feature`)
3. Commit your changes (`git commit -m 'Add some amazing feature'`)
4. Push to the branch (`git push origin feature/amazing-feature`)
5. Open a Pull Request
### Development Guidelines
- Follow PEP 8 style guidelines
- Write comprehensive tests for new features
- Update documentation for any API changes
- Ensure all tests pass before submitting a PR
## License
This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.
## Support
For support and questions:
- Check the [documentation](https://github.com/Swe-HimelRana/payment-logging-client#readme)
- Review the [examples](examples/) directory
- Open an issue on GitHub
- Contact support@himosoft.com
## Changelog
### Version 1.0.0
- Initial release
- Basic payment logging functionality
- Comprehensive validation
- Error handling with custom exceptions
- Environment variable configuration
- Django integration examples
- Full test coverage
## Acknowledgments
- Built for the Himosoft Payment Logging System
- Inspired by modern Python package development practices
- Thanks to all contributors and users
Raw data
{
"_id": null,
"home_page": "https://github.com/Swe-HimelRana/payment-logging-client",
"name": "himosoft-payment-client",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.8",
"maintainer_email": "Himosoft <support@himosoft.com>",
"keywords": "payment, logging, api, client, himosoft",
"author": "Himosoft",
"author_email": "Himosoft <support@himosoft.com>",
"download_url": "https://files.pythonhosted.org/packages/00/b6/ad693b0ec012dabb3c91f86660dae36524c8094f07fb4ab008520913910c/himosoft_payment_client-1.0.0.tar.gz",
"platform": null,
"description": "# Himosoft Payment Client\n\nA Python client library for integrating with the Himosoft Payment Logging API. This package provides a simple and robust way to log payment transactions from your applications to a centralized payment monitoring system.\n\n## Features\n\n- **Simple Integration**: Easy-to-use client library for logging payments\n- **Comprehensive Validation**: Built-in validation for all payment data\n- **Error Handling**: Detailed error handling with custom exceptions\n- **Environment Configuration**: Support for environment variable configuration\n- **Multiple Data Types**: Support for float, Decimal, and string amounts\n- **Connection Testing**: Built-in connection testing functionality\n- **Django Integration**: Ready-to-use Django integration examples\n- **Comprehensive Testing**: Full test coverage with pytest\n\n## Installation\n\n### Using pip\n\n```bash\npip install himosoft-payment-logging-client\n```\n\n### From source\n\n```bash\ngit clone https://github.com/Swe-HimelRana/payment-logging-client.git\ncd payment-client\npip install -e .\n```\n\n## Quick Start\n\n### 1. Set up environment variables\n\n```bash\nexport PAYMENT_RECORD_SERVER_URL=\"http://your-payment-server.com\"\nexport PAYMENT_RECORD_PLATFORM_API_KEY=\"your-platform-api-key-here\"\n```\n\n### 2. Basic usage\n\n```python\nfrom himosoft_payment_client import PaymentLogger\n\n# Initialize the client\nlogger = PaymentLogger()\n\n# Log a successful payment\nresult = logger.log_payment(\n user=\"john.doe@example.com\",\n package=\"Premium Plan\",\n amount=99.99,\n status=\"paid\",\n trx_id=\"TXN123456789\",\n payment_method=\"credit_card\",\n gateway_name=\"Stripe\",\n gateway_log={\n \"payment_intent_id\": \"pi_1234567890\",\n \"charge_id\": \"ch_1234567890\",\n \"amount\": 9999,\n \"currency\": \"usd\",\n \"status\": \"succeeded\"\n }\n)\n\nprint(f\"Payment logged: {result}\")\n```\n\n## Configuration\n\n### Environment Variables\n\nThe package uses the following environment variables:\n\n- `PAYMENT_RECORD_SERVER_URL`: The URL of your payment logging server\n- `PAYMENT_RECORD_PLATFORM_API_KEY`: Your platform's API key\n\n### Manual Configuration\n\nYou can also pass configuration directly to the client:\n\n```python\nlogger = PaymentLogger(\n server_url=\"http://your-server.com\",\n api_key=\"your-api-key\"\n)\n```\n\n## API Reference\n\n### PaymentLogger Class\n\n#### Constructor\n\n```python\nPaymentLogger(server_url=None, api_key=None)\n```\n\n**Parameters:**\n- `server_url` (str, optional): Payment server URL\n- `api_key` (str, optional): Platform API key\n\nIf not provided, these values will be read from environment variables.\n\n#### Methods\n\n##### log_payment()\n\n```python\nlog_payment(\n user,\n package,\n amount,\n status,\n trx_id=None,\n payment_method=None,\n gateway_name=None,\n gateway_log=None\n)\n```\n\n**Parameters:**\n- `user` (str): User identifier (email, username, or phone)\n- `package` (str): Package or plan name\n- `amount` (float/Decimal/str): Payment amount (positive number)\n- `status` (str): Payment status ('paid', 'failed', 'canceled', 'refunded')\n- `trx_id` (str, optional): Transaction ID (required for 'paid' and 'refunded' status)\n- `payment_method` (str, optional): Payment method used\n- `gateway_name` (str, optional): Payment gateway name\n- `gateway_log` (dict, optional): Complete gateway response\n\n**Returns:**\n- `dict`: API response containing status and message\n\n**Raises:**\n- `PaymentLoggerValidationError`: If input validation fails\n- `PaymentLoggerAPIError`: If the API returns an error\n- `PaymentLoggerNetworkError`: If there's a network error\n\n##### test_connection()\n\n```python\ntest_connection()\n```\n\n**Returns:**\n- `bool`: True if connection is successful\n\n**Raises:**\n- `PaymentLoggerNetworkError`: If connection fails\n\n## Payment Statuses\n\nThe following payment statuses are supported:\n\n- `paid`: Payment was successful (requires trx_id)\n- `failed`: Payment failed\n- `canceled`: Payment was canceled\n- `refunded`: Payment was refunded (requires trx_id)\n\n## Error Handling\n\nThe package provides several custom exceptions for different error types:\n\n### PaymentLoggerError\nBase exception for all payment logger errors.\n\n### PaymentLoggerValidationError\nRaised when input validation fails.\n\n```python\ntry:\n logger.log_payment(\n user=\"\",\n package=\"Basic Plan\",\n amount=19.99,\n status=\"paid\"\n )\nexcept PaymentLoggerValidationError as e:\n print(f\"Validation error: {e}\")\n```\n\n### PaymentLoggerAPIError\nRaised when the API returns an error response.\n\n```python\ntry:\n result = logger.log_payment(...)\nexcept PaymentLoggerAPIError as e:\n print(f\"API error: {e}\")\n print(f\"Status code: {e.status_code}\")\n print(f\"Response data: {e.response_data}\")\n```\n\n### PaymentLoggerNetworkError\nRaised when there's a network-related error.\n\n```python\ntry:\n result = logger.log_payment(...)\nexcept PaymentLoggerNetworkError as e:\n print(f\"Network error: {e}\")\n```\n\n### PaymentLoggerConfigError\nRaised when there's a configuration error.\n\n```python\ntry:\n logger = PaymentLogger()\nexcept PaymentLoggerConfigError as e:\n print(f\"Configuration error: {e}\")\n```\n\n## Examples\n\n### Basic Usage\n\n```python\nfrom himosoft_payment_client import PaymentLogger\n\nlogger = PaymentLogger()\n\n# Successful payment\nresult = logger.log_payment(\n user=\"user@example.com\",\n package=\"Premium Plan\",\n amount=99.99,\n status=\"paid\",\n trx_id=\"TXN123456\",\n payment_method=\"credit_card\",\n gateway_name=\"Stripe\",\n gateway_log={\"charge_id\": \"ch_123\"}\n)\n\n# Failed payment\nresult = logger.log_payment(\n user=\"user@example.com\",\n package=\"Basic Plan\",\n amount=19.99,\n status=\"failed\",\n payment_method=\"credit_card\",\n gateway_name=\"Stripe\",\n gateway_log={\"error\": \"card_declined\"}\n)\n```\n\n### Django Integration\n\n```python\n# settings.py\nPAYMENT_RECORD_SERVER_URL = 'http://your-payment-server.com'\nPAYMENT_RECORD_PLATFORM_API_KEY = 'your-api-key-here'\n\n# views.py\nfrom himosoft_payment_client import PaymentLogger\nfrom django.conf import settings\n\ndef process_payment(request):\n logger = PaymentLogger(\n server_url=settings.PAYMENT_RECORD_SERVER_URL,\n api_key=settings.PAYMENT_RECORD_PLATFORM_API_KEY\n )\n \n try:\n result = logger.log_payment(\n user=request.user.email,\n package=\"Premium Plan\",\n amount=99.99,\n status=\"paid\",\n trx_id=transaction_id,\n payment_method=\"credit_card\",\n gateway_name=\"Stripe\",\n gateway_log=gateway_response\n )\n return JsonResponse({\"status\": \"success\", \"result\": result})\n except PaymentLoggerError as e:\n return JsonResponse({\"status\": \"error\", \"message\": str(e)})\n```\n\n### Testing Connection\n\n```python\nlogger = PaymentLogger()\n\ntry:\n if logger.test_connection():\n print(\"Connection successful\")\n else:\n print(\"Connection failed\")\nexcept PaymentLoggerNetworkError as e:\n print(f\"Connection error: {e}\")\n```\n\n## Validation Rules\n\nThe package enforces the following validation rules:\n\n1. **User**: Required, cannot be empty\n2. **Package**: Required, cannot be empty\n3. **Amount**: Required, must be a positive number\n4. **Status**: Must be one of: 'paid', 'failed', 'canceled', 'refunded'\n5. **TRX ID**: Required for 'paid' and 'refunded' statuses\n6. **Gateway Log**: Must be a dictionary if provided\n\n## Development\n\n### Setting up development environment\n\n```bash\n# Clone the repository\ngit clone https://github.com/Swe-HimelRana/payment-logging-client.git\ncd payment-logging-client\n\n# Create virtual environment\npython3 -m venv venv\nsource venv/bin/activate # On Windows: venv\\Scripts\\activate\n\n# Install development dependencies\npip install -r requirements-dev.txt\n\n# Install package in development mode\npip install -e .\n```\n\n### Running tests\n\n```bash\n# Run all tests\npytest\n\n# Run tests with coverage\npytest --cov=payment-logging-client\n\n# Run specific test file\npytest tests/test_client.py\n\n# Run tests with verbose output\npytest -v\n```\n\n### Code formatting\n\n```bash\n# Format code with black\nblack payment-logging-client/ tests/ examples/\n\n# Check code style with flake8\nflake8 payment-logging-client/ tests/ examples/\n```\n\n### Running examples\n\n```bash\n# Run basic usage example\npython examples/basic_usage.py\n\n# Run Django integration example (requires Django)\npython examples/django_integration.py\n```\n\n## Contributing\n\n1. Fork the repository\n2. Create a feature branch (`git checkout -b feature/amazing-feature`)\n3. Commit your changes (`git commit -m 'Add some amazing feature'`)\n4. Push to the branch (`git push origin feature/amazing-feature`)\n5. Open a Pull Request\n\n### Development Guidelines\n\n- Follow PEP 8 style guidelines\n- Write comprehensive tests for new features\n- Update documentation for any API changes\n- Ensure all tests pass before submitting a PR\n\n## License\n\nThis project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.\n\n## Support\n\nFor support and questions:\n\n- Check the [documentation](https://github.com/Swe-HimelRana/payment-logging-client#readme)\n- Review the [examples](examples/) directory\n- Open an issue on GitHub\n- Contact support@himosoft.com\n\n## Changelog\n\n### Version 1.0.0\n- Initial release\n- Basic payment logging functionality\n- Comprehensive validation\n- Error handling with custom exceptions\n- Environment variable configuration\n- Django integration examples\n- Full test coverage\n\n## Acknowledgments\n\n- Built for the Himosoft Payment Logging System\n- Inspired by modern Python package development practices\n- Thanks to all contributors and users \n",
"bugtrack_url": null,
"license": "MIT",
"summary": "A Python client library for integrating with the Himosoft Payment Logging API",
"version": "1.0.0",
"project_urls": {
"Bug Tracker": "https://github.com/himosoft/payment-client/issues",
"Documentation": "https://github.com/himosoft/payment-client#readme",
"Homepage": "https://github.com/himosoft/payment-client",
"Repository": "https://github.com/himosoft/payment-client",
"Source Code": "https://github.com/himosoft/payment-client"
},
"split_keywords": [
"payment",
" logging",
" api",
" client",
" himosoft"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "00b6ad693b0ec012dabb3c91f86660dae36524c8094f07fb4ab008520913910c",
"md5": "83491fc536a20faeafaaf4940eb904af",
"sha256": "7ae047536ef69f1fd612c518f6ba4e2198fb0107e997c2388cd5139cd62d73dc"
},
"downloads": -1,
"filename": "himosoft_payment_client-1.0.0.tar.gz",
"has_sig": false,
"md5_digest": "83491fc536a20faeafaaf4940eb904af",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.8",
"size": 9133,
"upload_time": "2025-07-27T21:22:29",
"upload_time_iso_8601": "2025-07-27T21:22:29.986409Z",
"url": "https://files.pythonhosted.org/packages/00/b6/ad693b0ec012dabb3c91f86660dae36524c8094f07fb4ab008520913910c/himosoft_payment_client-1.0.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-07-27 21:22:29",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "Swe-HimelRana",
"github_project": "payment-logging-client",
"github_not_found": true,
"lcname": "himosoft-payment-client"
}
JSON
